Annotation of src/usr.bin/snmp/snmp.1, Revision 1.6
1.6 ! martijn 1: .\" $OpenBSD: snmp.1,v 1.5 2019/09/18 09:52:47 martijn Exp $
1.1 martijn 2: .\"
3: .\" Copyright (c) 2019 Martijn van Duren <martijn@openbsd.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.5 martijn 17: .Dd $Mdocdate: September 18 2019 $
1.1 martijn 18: .Dt SNMP 1
19: .Os
20: .Sh NAME
21: .Nm snmp
22: .Nd simple SNMP client
23: .Sh SYNOPSIS
24: .Nm
25: .Cm get | getnext
1.5 martijn 26: .Op Fl A Ar authpass
27: .Op Fl a Ar digest
1.1 martijn 28: .Op Fl c Ar community
1.4 martijn 29: .Op Fl E Ar ctxengineid
30: .Op Fl e Ar secengineid
1.6 ! martijn 31: .Op Fl K Ar localpriv
1.5 martijn 32: .Op Fl k Ar localauth
33: .Op Fl l Ar seclevel
1.4 martijn 34: .Op Fl n Ar ctxname
35: .Op Fl O Cm afnQqSvx
1.1 martijn 36: .Op Fl r Ar retries
37: .Op Fl t Ar timeout
1.4 martijn 38: .Op Fl u Ar user
1.1 martijn 39: .Op Fl v Ar version
1.6 ! martijn 40: .Op Fl X Ar privpass
! 41: .Op Fl x Ar cipher
1.4 martijn 42: .Op Fl Z Ar boots , Ns Ar time
1.1 martijn 43: .Ar agent
44: .Ar oid ...
45: .Nm
46: .Cm walk
1.5 martijn 47: .Op Fl A Ar authpass
48: .Op Fl a Ar digest
1.1 martijn 49: .Op Fl c Ar community
1.4 martijn 50: .Op Fl E Ar ctxengineid
51: .Op Fl e Ar secengineid
1.6 ! martijn 52: .Op Fl K Ar localpriv
1.5 martijn 53: .Op Fl k Ar localauth
54: .Op Fl l Ar seclevel
1.4 martijn 55: .Op Fl n Ar ctxname
56: .Op Fl O Cm afnQqSvx
1.1 martijn 57: .Op Fl r Ar retries
58: .Op Fl t Ar timeout
1.4 martijn 59: .Op Fl u Ar user
1.1 martijn 60: .Op Fl v Ar version
1.6 ! martijn 61: .Op Fl X Ar privpass
! 62: .Op Fl x Ar cipher
1.4 martijn 63: .Op Fl Z Ar boots , Ns Ar time
1.3 deraadt 64: .Op Fl C Cm cIipt
65: .Op Fl C Cm E Ar endoid
1.1 martijn 66: .Ar agent
67: .Op Ar oid
68: .Nm
69: .Cm bulkget
1.5 martijn 70: .Op Fl A Ar authpass
71: .Op Fl a Ar digest
1.1 martijn 72: .Op Fl c Ar community
1.4 martijn 73: .Op Fl E Ar ctxengineid
74: .Op Fl e Ar secengineid
1.6 ! martijn 75: .Op Fl K Ar localpriv
1.5 martijn 76: .Op Fl k Ar localauth
77: .Op Fl l Ar seclevel
1.4 martijn 78: .Op Fl n Ar ctxname
79: .Op Fl O Cm afnQqSvx
1.1 martijn 80: .Op Fl r Ar retries
81: .Op Fl t Ar timeout
1.4 martijn 82: .Op Fl u Ar user
1.1 martijn 83: .Op Fl v Ar version
1.6 ! martijn 84: .Op Fl X Ar privpass
! 85: .Op Fl x Ar cipher
1.4 martijn 86: .Op Fl Z Ar boots , Ns Ar time
1.3 deraadt 87: .Op Fl C Cm n Ns Ar nonrep Ns Cm r Ns Ar maxrep
1.1 martijn 88: .Ar agent
89: .Ar oid ...
90: .Nm
91: .Cm bulkwalk
1.5 martijn 92: .Op Fl A Ar authpass
93: .Op Fl a Ar digest
1.1 martijn 94: .Op Fl c Ar community
1.4 martijn 95: .Op Fl E Ar ctxengineid
96: .Op Fl e Ar secengineid
1.6 ! martijn 97: .Op Fl K Ar localpriv
1.5 martijn 98: .Op Fl k Ar localauth
99: .Op Fl l Ar seclevel
1.4 martijn 100: .Op Fl n Ar ctxname
101: .Op Fl O Cm afnQqSvx
1.1 martijn 102: .Op Fl r Ar retries
103: .Op Fl t Ar timeout
1.4 martijn 104: .Op Fl u Ar user
1.1 martijn 105: .Op Fl v Ar version
1.6 ! martijn 106: .Op Fl X Ar privpass
! 107: .Op Fl x Ar cipher
1.4 martijn 108: .Op Fl Z Ar boots , Ns Ar time
1.3 deraadt 109: .Op Fl C Cm cipn Ns Ar nonrep Ns Cm r Ns Ar maxrep
1.1 martijn 110: .Ar agent
111: .Op Ar oid
112: .Nm
113: .Cm trap
1.5 martijn 114: .Op Fl A Ar authpass
115: .Op Fl a Ar digest
1.1 martijn 116: .Op Fl c Ar community
1.4 martijn 117: .Op Fl E Ar ctxengineid
118: .Op Fl e Ar secengineid
1.6 ! martijn 119: .Op Fl K Ar localpriv
1.5 martijn 120: .Op Fl k Ar localauth
121: .Op Fl l Ar seclevel
1.4 martijn 122: .Op Fl n Ar ctxname
1.3 deraadt 123: .Op Fl r Ar retries
124: .Op Fl t Ar timeout
1.4 martijn 125: .Op Fl u Ar user
1.1 martijn 126: .Op Fl v Ar version
1.6 ! martijn 127: .Op Fl X Ar privpass
! 128: .Op Fl x Ar cipher
1.4 martijn 129: .Op Fl Z Ar boots , Ns Ar time
1.1 martijn 130: .Ar agent uptime trapoid
131: .Oo Ar varoid type value Oc ...
132: .Nm
133: .Cm mibtree
134: .Op Fl O Cm fnS
135: .Sh DESCRIPTION
136: The
137: .Nm
138: utility is a simple SNMP client.
139: .Pp
140: The subcommands are as follows:
141: .Bl -tag -width bulkwalk
142: .It Cm get
143: Retrieve the MIB for
144: .Ar oid
145: from the
146: .Ar agent .
147: If more than one
148: .Ar oid
149: is specified, retrieve the MIB for each one.
150: .It Cm getnext
151: Retrieve the MIB that follows
152: .Ar oid
153: from the
154: .Ar agent .
155: If more than one
156: .Ar oid
157: is specified, retrieve the MIB following each one of them.
158: .It Cm walk
159: Retrieve all the MIBs that are branches of
160: .Ar oid
161: from the
162: .Ar agent .
163: This uses the
164: .Cm getnext
165: subcommand internally and requests a single MIB at a time.
166: If no OID is specified it defaults to mib-2
167: .Pq .1.3.6.1.2.1 .
168: .It Cm bulkget
169: Retrieve the next 10 MIBs following each
170: .Ar oid
171: from the
172: .Ar agent .
173: This command is not available for
174: .Fl v Cm 1 .
175: .It Cm bulkwalk
176: Retrieve all the MIBs from the
177: .Ar agent
178: that are branches of
179: .Ar oid .
180: This uses the
181: .Cm bulkget
182: subcommand internally to retrieve multiple MIBs at a time.
183: This command is not available for
184: .Fl v Cm 1 .
185: .It Cm trap
186: Send a trap message to the
187: .Ar agent .
188: The
189: .Ar uptime
190: is specified in timeticks
191: .Pq centiseconds
192: or defaults to the system uptime if an empty string is given.
193: The
194: .Ar trapoid
195: is the identification OID used by the trap handler to determine its action.
196: The triple
197: .Op Ar varoid , type, value
198: is described below
199: .Sx Data types .
200: This command is not available for
201: .Fl v Cm 1 .
202: .It Cm mibtree
203: Dump the tree of compiled-in MIB objects.
204: .El
205: .Pp
206: The options are as follows:
207: .Bl -tag -width Ds
1.5 martijn 208: .It Fl A Ar authpass
209: The authentication password for the user.
210: This will be transformed to
211: .Ar localauth .
212: This option is only used by
213: .Fl v Cm 3 .
214: .It Fl a Ar digest
215: Set the digest
216: .Pq authentication
217: protocol.
218: Options are
219: .Cm MD5 ,
220: .Cm SHA ,
221: .Cm SHA-224 ,
222: .Cm SHA-256 ,
223: .Cm SHA-384
224: or
225: .Cm SHA-512 .
226: This option defaults to
227: .Cm MD5 .
228: This option is only used by
229: .Fl v Cm 3 .
1.1 martijn 230: .It Fl C Ar appopt
231: Set the application specific
232: .Ar appopt
233: options by supplying a string of one or more
234: of the following modifier letters:
235: .Bl -tag -width Ds
236: .It Cm c
237: During a
238: .Cm walk
239: or
240: .Cm bulkwalk ,
241: disable checking the order of MIBs.
242: On some devices that return MIBs out of order,
243: this may cause an infinite loop.
244: .It Cm E Ar endoid
245: Walk the tree up to but excluding
246: .Ar endoid .
1.2 schwarze 247: The blank before
248: .Ar endoid
249: is mandatory.
1.1 martijn 250: .It Cm I
251: If no branches are found during a
252: .Cm walk ,
253: do not fall back to returning the original MIB via a
254: .Cm get
255: request.
256: .It Cm i
257: Before starting a
258: .Cm walk
259: or
260: .Cm bulkwalk ,
261: always do a
262: .Cm get
263: request on the specified
264: .Ar oid
265: first.
266: .It Cm n Ns Ar nonrep
267: Set the non-repeaters field in the request to the non-negative integer
268: .Ar nonrep .
269: This causes the first
270: .Ar nonrep
271: .Ar oid
272: arguments to only return a single MIB instead of
273: .Ar maxrep .
274: This value defaults to 0.
1.2 schwarze 275: No blank is allowed before
276: .Ar nonrep .
1.1 martijn 277: .It Cm p
278: At the end of a
279: .Cm walk
280: or
281: .Cm bulkwalk ,
282: show a summary of the total variables received.
283: .It Cm r Ns Ar maxrep
284: Set the max-repetitions field in the request to the positive integer
285: .Ar maxrep .
286: For
287: .Cm bulkget
288: or
289: .Cm bulkwalk
290: this determines the amount of MIBs to return for each specified OID.
291: This value defaults to 10.
1.2 schwarze 292: No blank is allowed before
293: .Ar maxrep .
1.1 martijn 294: .It Cm t
295: Show how long it took to
296: .Cm walk
297: the entire tree.
298: .El
299: .It Fl c Ar community
300: Set the
301: .Ar community
302: string.
303: Defaults to
304: .Cm public .
1.4 martijn 305: This option is only used by
306: .Fl v Cm 1
307: and
308: .Fl v Cm 2c .
309: .It Fl e Ar secengineid
310: The USM security engine id.
311: Under normal circumstances this value is discovered via snmpv3 discovery and
312: does not need to be specified.
313: This option is only used by
314: .Fl v Cm 3 .
315: .It Fl E Ar ctxengineid
316: The snmpv3 context engine id.
317: Most of the time this value can be safely ignored.
1.5 martijn 318: This option is only used by
319: .Fl v Cm 3 .
1.6 ! martijn 320: .It Fl K Ar localpriv
! 321: The localized privacy password for the user in hexadecimal format
! 322: .Po
! 323: optionally prefixed with a
! 324: .Cm 0x
! 325: .Pc .
! 326: This option is only used by
! 327: .Fl v Cm 3 .
1.5 martijn 328: .It Fl k Ar localauth
329: The localized authentication password for the user in hexadecimal format
330: .Po
331: optionally prefixed with a
332: .Cm 0x
333: .Pc .
334: This option is only used by
335: .Fl v Cm 3 .
336: .It Fl l Ar seclevel
337: The security level.
338: Values can be
1.6 ! martijn 339: .Cm noAuthNoPriv Pq default ,
1.5 martijn 340: .Cm authNoPriv
341: .Po
342: requires either
343: .Fl A
344: or
345: .Fl k
1.6 ! martijn 346: .Pc
! 347: or
! 348: .Cm authPriv
! 349: .Po
! 350: requires either
! 351: .Fl X
! 352: or
! 353: .Fl K
! 354: in addition to the
! 355: .Cm authNoPriv
! 356: requirements
1.5 martijn 357: .Pc .
1.4 martijn 358: This option is only used by
359: .Fl v Cm 3 .
360: .It Fl n Ar ctxname
361: Sets the context name.
362: Defaults to an empty string.
363: This option is only used by
364: .Fl v Cm 3 .
1.1 martijn 365: .It Fl O Ar output
366: Set the
367: .Ar output
368: options by supplying a string of one or more
369: of the following modifier letters:
370: .Bl -tag -width 1n
371: .It Cm a
372: Print the varbind string unchanged
373: rather than replacing non-printable bytes with dots.
374: .It Cm f
375: When displaying an OID, include the full list of MIB objects.
376: By default only the last textual MIB object is shown.
377: .It Cm n
378: Display the OID numerically.
379: .It Cm Q
380: Remove the type information.
381: .It Cm q
382: Remove the type information and the equal sign.
383: .It Cm S
384: Display the MIB name and the type information.
385: This is the default behaviour.
386: .It Cm v
387: Only display the varbind value, removing the OID.
388: .It Cm x
389: Display the varbind string values as hexadecimal strings.
390: .El
391: .It Fl r Ar retries
392: Set the number of
393: .Ar retries
394: in case of packet loss.
395: Defaults to 5.
396: .It Fl t Ar timeout
397: Set the
398: .Ar timeout
399: to wait for a reply, in seconds.
400: Defaults to 1.
1.4 martijn 401: .It Fl u Ar user
402: Sets the username.
403: If
404: .Fl v Cm 3
405: is used this option is required.
406: This option is only used by
407: .Fl v Cm 3 .
1.1 martijn 408: .It Fl v Ar version
409: Set the snmp protocol
410: .Ar version
411: to either
1.4 martijn 412: .Cm 1 ,
413: .Cm 2c
1.1 martijn 414: or
1.4 martijn 415: .Cm 3 .
1.1 martijn 416: Currently defaults to
417: .Cm 2c .
1.6 ! martijn 418: .It Fl X Ar privpass
! 419: The privacy password for the user.
! 420: This will be tansformed to
! 421: .Ar localpriv .
! 422: This option is only used by
! 423: .Fl v Cm 3 .
! 424: .It Fl x Ar cipher
! 425: Sets the cipher
! 426: .Pq privacy
! 427: protocol.
! 428: Options are
! 429: .Cm DES
! 430: and
! 431: .Cm AES .
! 432: This option is only used by
! 433: .Fl v Cm 3 .
1.4 martijn 434: .It Fl Z Ar boots , Ns Ar time
435: Set the engine boots and engine time.
436: Under normal circumstances this value is discovered via snmpv3 discovery and
437: does not need to be specified.
438: This option is only used by
439: .Fl v Cm 3 .
1.1 martijn 440: .El
441: .Pp
442: The syntax for the
443: .Ar agent
444: argument is
445: .Oo Ar protocol : Oc Ns Ar address
446: with the follwing forms:
447: .Bl -column udp6XXXtcp6X address -offset indent
448: .It Ar protocol Ta Ar address
449: .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc |
450: .Ar IPv4-address Ns Op Pf : Ar port
451: .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc |
452: .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc |
453: .Ar IPv6-address Ns Pf : Ar port
454: .It Cm unix Ta Ar pathname
455: .El
456: .Pp
457: The default
458: .Ar protocol
459: is
460: .Cm udp
461: and the default
462: .Ar port
463: is 161; except for the
464: .Nm snmp Cm trap
465: command which uses 162.
466: .Cm udpv6
467: and
468: .Cm udpipv6
469: are aliases for
470: .Cm udp6 ;
471: .Cm tcpv6
472: and
473: .Cm tcpipv6
474: for
475: .Cm tcp6 .
476: To specify an IPv6-address without a
477: .Ar port ,
478: the
479: .Ar IPv6-address
480: must be enclosed in square brackets.
481: If the square brackets are omitted,
482: the value after the last colon is always interpreted as a
483: .Ar port .
484: .Ss Data types
485: Additional data sent to the server is formatted by specifying one or more
486: triples of
487: .Ar varoid ,
488: .Ar type ,
489: and
490: .Ar value .
491: Supported types are:
492: .Bl -tag -width 1n
493: .It Cm a
494: An IPv4 Address.
495: .It Cm b
496: A bitstring.
497: A list of individual bit offsets separated by comma, space or tab.
498: Must be supplied as a single argument.
499: .It Cm c
500: A counter32.
501: .It Cm d
502: A decimal string.
503: A list of individual bytes in decimal form separated by space or tab.
504: .It Cm i
505: An integer.
506: .It Cm n
507: A null object.
508: .It Cm o
509: An OID.
510: .It Cm s
511: A regular string.
512: .It Cm t
513: Timeticks in centiseconds.
514: .It Cm u
515: Unsigned integer.
516: Actually a normal integer for compatibility with netsnmp.
517: .It Cm x
518: A hex string.
519: Similar to a decimal string, but in hexadecimal format.
520: .El
521: .Sh SEE ALSO
522: .Xr snmpd 8
523: .Sh HISTORY
524: The
525: .Nm
526: program first appeared in
527: .Ox 6.6 .
528: .Sh AUTHORS
529: The
530: .Nm
531: program was written by
532: .An Martijn van Duren Aq Mt martijn@openbsd.org .
![[BACK]](/icons/back.gif){kind=icon}
Return to snmp.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / snmp