Annotation of src/usr.bin/snmp/snmp.1, Revision 1.20
1.20 ! martijn 1: .\" $OpenBSD: snmp.1,v 1.19 2021/08/08 13:41:26 sthen 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.20 ! martijn 17: .Dd $Mdocdate: August 8 2021 $
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
1.8 martijn 25: .Cm get | getnext | bulkget
26: .Op Ar options
1.1 martijn 27: .Ar agent
28: .Ar oid ...
29: .Nm
1.8 martijn 30: .Cm walk | bulkwalk
31: .Op Ar options
1.1 martijn 32: .Ar agent
33: .Op Ar oid
34: .Nm
1.7 martijn 35: .Cm set
1.8 martijn 36: .Op Ar options
1.7 martijn 37: .Ar agent
38: .Ar varoid type value
39: .Oo Ar varoid type value Oc ...
40: .Nm
1.1 martijn 41: .Cm trap
1.8 martijn 42: .Op Ar options
1.1 martijn 43: .Ar agent uptime trapoid
44: .Oo Ar varoid type value Oc ...
45: .Nm
1.10 martijn 46: .Cm df
47: .Op Ar options
48: .Ar agent
49: .Nm
1.1 martijn 50: .Cm mibtree
1.8 martijn 51: .Op Fl O Ar fns
1.15 martijn 52: .Op Ar oid ...
1.1 martijn 53: .Sh DESCRIPTION
54: The
55: .Nm
56: utility is a simple SNMP client.
57: .Pp
58: The subcommands are as follows:
1.8 martijn 59: .Bl -tag -width Ds
60: .It Xo
61: .Nm snmp
62: .Cm get
63: .Op Ar options
64: .Ar agent oid ...
65: .Xc
66: Retrieve the varbind for
1.1 martijn 67: .Ar oid
68: from the
69: .Ar agent .
70: If more than one
71: .Ar oid
1.8 martijn 72: is specified, retrieve the varbind for each one.
73: .It Xo
74: .Nm snmp
75: .Cm getnext
76: .Op Ar options
77: .Ar agent oid ...
78: .Xc
79: Retrieve the varbind that follows
1.1 martijn 80: .Ar oid
81: from the
82: .Ar agent .
83: If more than one
84: .Ar oid
1.8 martijn 85: is specified, retrieve the varbind following each one of them.
86: .It Nm snmp Cm walk Oo Ar options Oc Ar agent Op Ar oid
87: Retrieve all the varbinds that are branches of
1.1 martijn 88: .Ar oid
89: from the
90: .Ar agent .
91: This uses the
92: .Cm getnext
1.8 martijn 93: subcommand internally and requests a single varbind at a time.
94: If no
95: .Ar oid
96: is specified it defaults to mib-2
1.1 martijn 97: .Pq .1.3.6.1.2.1 .
1.8 martijn 98: .It Xo
99: .Nm snmp
100: .Cm bulkget
101: .Op Ar options
1.13 jmc 102: .Ar agent oid ...
1.8 martijn 103: .Xc
104: Retrieve the next 10 varbinds following each
1.1 martijn 105: .Ar oid
106: from the
107: .Ar agent .
108: This command is not available for
109: .Fl v Cm 1 .
1.8 martijn 110: .It Xo
111: .Nm snmp
112: .Cm bulkwalk
113: .Op Ar options
114: .Ar agent
115: .Op Ar oid
116: .Xc
117: Retrieve all the varbinds from the
1.1 martijn 118: .Ar agent
119: that are branches of
120: .Ar oid .
121: This uses the
122: .Cm bulkget
1.8 martijn 123: subcommand internally to retrieve multiple varbinds at a time.
1.1 martijn 124: This command is not available for
125: .Fl v Cm 1 .
1.8 martijn 126: .It Xo
127: .Nm snmp
128: .Cm set
129: .Op Ar options
130: .Ar agent varoid type value ...
131: .Xc
132: Set one or more
133: .Ar varoid to a new
134: .Ar value .
135: The format of the
136: .Ar varoid type value
137: triple is described in
138: .Sx Data types ,
139: below.
140: .It Xo
141: .Nm snmp
142: .Cm trap
143: .Op Ar options
144: .Ar agent uptime trapoid
145: .Op Ar varoid type value ...
146: .Xc
1.1 martijn 147: Send a trap message to the
148: .Ar agent .
149: The
150: .Ar uptime
151: is specified in timeticks
152: .Pq centiseconds
153: or defaults to the system uptime if an empty string is given.
154: The
155: .Ar trapoid
156: is the identification OID used by the trap handler to determine its action.
157: This command is not available for
158: .Fl v Cm 1 .
1.10 martijn 159: .It Xo
160: .Nm
1.12 jmc 161: .Cm df
1.10 martijn 162: .Op Ar options
163: .Ar agent
164: .Xc
165: An SNMP based version of the
166: .Xr df 1
167: command.
168: If no size suffix is shown the sizes are in kilobytes.
1.15 martijn 169: .It Nm Cm mibtree Oo Fl O Ar fnS Oc Op Ar oid ...
1.1 martijn 170: Dump the tree of compiled-in MIB objects.
1.15 martijn 171: If
172: .Ar oid
1.16 jsg 173: is specified it will print the objects in the requested output format if
1.15 martijn 174: available, or print a warning if the object can't be found.
1.1 martijn 175: .El
176: .Pp
1.8 martijn 177: The
178: .Ar options
179: are as follows:
1.1 martijn 180: .Bl -tag -width Ds
1.5 martijn 181: .It Fl A Ar authpass
182: The authentication password for the user.
183: This will be transformed to
184: .Ar localauth .
185: This option is only used by
186: .Fl v Cm 3 .
187: .It Fl a Ar digest
188: Set the digest
189: .Pq authentication
190: protocol.
191: Options are
192: .Cm MD5 ,
193: .Cm SHA ,
194: .Cm SHA-224 ,
195: .Cm SHA-256 ,
196: .Cm SHA-384
197: or
198: .Cm SHA-512 .
199: This option defaults to
1.19 sthen 200: .Cm SHA .
1.5 martijn 201: This option is only used by
202: .Fl v Cm 3 .
1.1 martijn 203: .It Fl C Ar appopt
1.8 martijn 204: For the
205: .Cm bulkget ,
206: .Cm bulkwalk ,
1.11 martijn 207: .Cm df ,
1.8 martijn 208: and
209: .Cm walk
210: subcommands, set the application specific
1.1 martijn 211: .Ar appopt
212: options by supplying a string of one or more
213: of the following modifier letters:
214: .Bl -tag -width Ds
215: .It Cm c
1.8 martijn 216: For
1.1 martijn 217: .Cm walk
1.8 martijn 218: and
1.1 martijn 219: .Cm bulkwalk ,
220: disable checking the order of MIBs.
221: On some devices that return MIBs out of order,
222: this may cause an infinite loop.
223: .It Cm E Ar endoid
1.8 martijn 224: For
225: .Cm walk ,
226: walk the tree up to but excluding
1.1 martijn 227: .Ar endoid .
1.2 schwarze 228: The blank before
229: .Ar endoid
230: is mandatory.
1.10 martijn 231: .It Cm h
232: For
233: .Cm df
234: print the output in
235: .Dq human-readable
236: format.
1.1 martijn 237: .It Cm I
1.8 martijn 238: For
1.1 martijn 239: .Cm walk ,
240: do not fall back to returning the original MIB via a
241: .Cm get
242: request.
243: .It Cm i
1.8 martijn 244: For
1.1 martijn 245: .Cm walk
1.8 martijn 246: and
1.1 martijn 247: .Cm bulkwalk ,
248: always do a
249: .Cm get
250: request on the specified
251: .Ar oid
252: first.
253: .It Cm n Ns Ar nonrep
1.8 martijn 254: For
255: .Cm bulkget
256: and
257: .Cm bulkwalk ,
1.1 martijn 258: Set the non-repeaters field in the request to the non-negative integer
259: .Ar nonrep .
260: This causes the first
261: .Ar nonrep
262: .Ar oid
263: arguments to only return a single MIB instead of
264: .Ar maxrep .
265: This value defaults to 0.
1.2 schwarze 266: No blank is allowed before
267: .Ar nonrep .
1.1 martijn 268: .It Cm p
1.8 martijn 269: For
1.1 martijn 270: .Cm walk
271: or
272: .Cm bulkwalk ,
1.8 martijn 273: also show a summary of the total variables received.
1.1 martijn 274: .It Cm r Ns Ar maxrep
275: For
1.10 martijn 276: .Cm bulkget ,
277: .Cm bulkwalk
1.8 martijn 278: and
1.10 martijn 279: .Cm df ,
1.8 martijn 280: set the max-repetitions field in the request to the positive integer
281: .Ar maxrep .
282: This determines the amount of MIBs to return for each specified OID.
1.1 martijn 283: This value defaults to 10.
1.2 schwarze 284: No blank is allowed before
285: .Ar maxrep .
1.9 martijn 286: .It Cm s Ar skipoid
287: For
288: .Cm walk
289: or
290: .Cm bulkwalk
291: don't include
292: .Ar skipoid
293: or its children in the walk output.
294: The blank before
295: .Ar skipoid
296: is mandatory.
1.1 martijn 297: .It Cm t
1.8 martijn 298: For
299: .Cm walk ,
300: Show how long it took to walk the entire tree.
1.1 martijn 301: .El
302: .It Fl c Ar community
303: Set the
304: .Ar community
305: string.
1.4 martijn 306: This option is only used by
307: .Fl v Cm 1
308: and
1.20 ! martijn 309: .Fl v Cm 2c
! 310: and has no default.
1.4 martijn 311: .It Fl e Ar secengineid
312: The USM security engine id.
313: Under normal circumstances this value is discovered via snmpv3 discovery and
314: does not need to be specified.
315: This option is only used by
316: .Fl v Cm 3 .
317: .It Fl E Ar ctxengineid
318: The snmpv3 context engine id.
319: Most of the time this value can be safely ignored.
1.5 martijn 320: This option is only used by
321: .Fl v Cm 3 .
1.6 martijn 322: .It Fl K Ar localpriv
323: The localized privacy password for the user in hexadecimal format
324: .Po
325: optionally prefixed with a
326: .Cm 0x
327: .Pc .
328: This option is only used by
329: .Fl v Cm 3 .
1.5 martijn 330: .It Fl k Ar localauth
331: The localized authentication password for the user in hexadecimal format
332: .Po
333: optionally prefixed with a
334: .Cm 0x
335: .Pc .
336: This option is only used by
337: .Fl v Cm 3 .
338: .It Fl l Ar seclevel
339: The security level.
340: Values can be
1.6 martijn 341: .Cm noAuthNoPriv Pq default ,
1.5 martijn 342: .Cm authNoPriv
343: .Po
344: requires either
345: .Fl A
346: or
347: .Fl k
1.6 martijn 348: .Pc
349: or
350: .Cm authPriv
351: .Po
352: requires either
353: .Fl X
354: or
355: .Fl K
356: in addition to the
357: .Cm authNoPriv
358: requirements
1.5 martijn 359: .Pc .
1.4 martijn 360: This option is only used by
361: .Fl v Cm 3 .
362: .It Fl n Ar ctxname
363: Sets the context name.
364: Defaults to an empty string.
365: This option is only used by
366: .Fl v Cm 3 .
1.1 martijn 367: .It Fl O Ar output
368: Set the
369: .Ar output
370: options by supplying a string of one or more
371: of the following modifier letters:
372: .Bl -tag -width 1n
373: .It Cm a
374: Print the varbind string unchanged
375: rather than replacing non-printable bytes with dots.
376: .It Cm f
377: When displaying an OID, include the full list of MIB objects.
378: By default only the last textual MIB object is shown.
379: .It Cm n
380: Display the OID numerically.
381: .It Cm Q
382: Remove the type information.
383: .It Cm q
384: Remove the type information and the equal sign.
385: .It Cm S
386: Display the MIB name and the type information.
387: This is the default behaviour.
388: .It Cm v
389: Only display the varbind value, removing the OID.
390: .It Cm x
391: Display the varbind string values as hexadecimal strings.
392: .El
1.8 martijn 393: .Pp
394: The
395: .Cm mibtree
396: subcommand may only use the
397: .Op Fl fnS
398: output options;
399: no output options are available for
400: .Cm trap .
1.1 martijn 401: .It Fl r Ar retries
402: Set the number of
403: .Ar retries
404: in case of packet loss.
405: Defaults to 5.
406: .It Fl t Ar timeout
407: Set the
408: .Ar timeout
409: to wait for a reply, in seconds.
410: Defaults to 1.
1.4 martijn 411: .It Fl u Ar user
412: Sets the username.
413: If
414: .Fl v Cm 3
415: is used this option is required.
416: This option is only used by
417: .Fl v Cm 3 .
1.1 martijn 418: .It Fl v Ar version
419: Set the snmp protocol
420: .Ar version
421: to either
1.4 martijn 422: .Cm 1 ,
423: .Cm 2c
1.1 martijn 424: or
1.4 martijn 425: .Cm 3 .
1.1 martijn 426: Currently defaults to
1.20 ! martijn 427: .Cm 3 .
1.6 martijn 428: .It Fl X Ar privpass
429: The privacy password for the user.
430: This will be tansformed to
431: .Ar localpriv .
432: This option is only used by
433: .Fl v Cm 3 .
434: .It Fl x Ar cipher
435: Sets the cipher
436: .Pq privacy
437: protocol.
438: Options are
439: .Cm DES
440: and
1.18 martijn 441: .Cm AES .
442: This option defaults to
1.6 martijn 443: .Cm AES .
444: This option is only used by
445: .Fl v Cm 3 .
1.4 martijn 446: .It Fl Z Ar boots , Ns Ar time
447: Set the engine boots and engine time.
448: Under normal circumstances this value is discovered via snmpv3 discovery and
449: does not need to be specified.
450: This option is only used by
451: .Fl v Cm 3 .
1.1 martijn 452: .El
453: .Pp
454: The syntax for the
455: .Ar agent
456: argument is
1.8 martijn 457: .Oo Ar protocol : Oc Ns Ar address ,
458: with the following format:
1.1 martijn 459: .Bl -column udp6XXXtcp6X address -offset indent
460: .It Ar protocol Ta Ar address
461: .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc |
462: .Ar IPv4-address Ns Op Pf : Ar port
463: .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc |
464: .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc |
465: .Ar IPv6-address Ns Pf : Ar port
466: .It Cm unix Ta Ar pathname
467: .El
468: .Pp
469: The default
470: .Ar protocol
471: is
472: .Cm udp
473: and the default
474: .Ar port
1.8 martijn 475: is 161, except for the
476: .Cm trap
477: subcommand, which uses 162.
1.1 martijn 478: .Cm udpv6
479: and
480: .Cm udpipv6
481: are aliases for
482: .Cm udp6 ;
483: .Cm tcpv6
484: and
485: .Cm tcpipv6
486: for
487: .Cm tcp6 .
488: To specify an IPv6-address without a
489: .Ar port ,
490: the
491: .Ar IPv6-address
492: must be enclosed in square brackets.
493: If the square brackets are omitted,
494: the value after the last colon is always interpreted as a
495: .Ar port .
496: .Ss Data types
497: Additional data sent to the server is formatted by specifying one or more
498: triples of
499: .Ar varoid ,
500: .Ar type ,
501: and
502: .Ar value .
503: Supported types are:
1.8 martijn 504: .Bl -tag -width 1n -offset indent
1.1 martijn 505: .It Cm a
506: An IPv4 Address.
507: .It Cm b
508: A bitstring.
509: A list of individual bit offsets separated by comma, space or tab.
510: Must be supplied as a single argument.
511: .It Cm c
512: A counter32.
513: .It Cm d
514: A decimal string.
515: A list of individual bytes in decimal form separated by space or tab.
516: .It Cm i
517: An integer.
518: .It Cm n
519: A null object.
520: .It Cm o
521: An OID.
522: .It Cm s
523: A regular string.
524: .It Cm t
525: Timeticks in centiseconds.
526: .It Cm u
527: Unsigned integer.
528: .It Cm x
529: A hex string.
530: Similar to a decimal string, but in hexadecimal format.
1.14 martijn 531: .El
532: .Sh ENVIRONMENT
533: .Bl -tag -width LC_CTYPE
534: .It Ev LC_CTYPE
535: The character encoding
536: .Xr locale 1
537: used for output.
538: It decides whether objects having a display format of UTF-8 are printed as
539: UTF-8, and whether each byte invalid according to the object's display format is
540: printed as a UTF-8 replacement character
541: .Pq Sq \[uFFFD] .
542: .Pp
543: If unset or set to
544: .Qq C ,
545: .Qq POSIX ,
546: or an unsupported value, for objects having a display format of UTF-8, each
547: .Em printable
548: non-ASCII character is replaced with a single dot
549: .Pq Sq \&. .
550: Each byte invalid according to the object's display format is printed as a
551: question mark
552: .Pq Sq \&? .
553: .Pp
554: Each non-printable character is always replaced with a single dot
555: .Pq Sq \&. .
1.1 martijn 556: .El
557: .Sh SEE ALSO
558: .Xr snmpd 8
559: .Sh HISTORY
560: The
561: .Nm
562: program first appeared in
563: .Ox 6.6 .
564: .Sh AUTHORS
565: The
566: .Nm
567: program was written by
568: .An Martijn van Duren Aq Mt martijn@openbsd.org .