Annotation of src/usr.bin/snmp/snmp.1, Revision 1.19
1.19 ! sthen 1: .\" $OpenBSD: snmp.1,v 1.18 2021/06/20 20:02:14 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.19 ! sthen 17: .Dd $Mdocdate: June 20 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.
306: Defaults to
307: .Cm public .
1.4 martijn 308: This option is only used by
309: .Fl v Cm 1
310: and
311: .Fl v Cm 2c .
312: .It Fl e Ar secengineid
313: The USM security engine id.
314: Under normal circumstances this value is discovered via snmpv3 discovery and
315: does not need to be specified.
316: This option is only used by
317: .Fl v Cm 3 .
318: .It Fl E Ar ctxengineid
319: The snmpv3 context engine id.
320: Most of the time this value can be safely ignored.
1.5 martijn 321: This option is only used by
322: .Fl v Cm 3 .
1.6 martijn 323: .It Fl K Ar localpriv
324: The localized privacy password for the user in hexadecimal format
325: .Po
326: optionally prefixed with a
327: .Cm 0x
328: .Pc .
329: This option is only used by
330: .Fl v Cm 3 .
1.5 martijn 331: .It Fl k Ar localauth
332: The localized authentication password for the user in hexadecimal format
333: .Po
334: optionally prefixed with a
335: .Cm 0x
336: .Pc .
337: This option is only used by
338: .Fl v Cm 3 .
339: .It Fl l Ar seclevel
340: The security level.
341: Values can be
1.6 martijn 342: .Cm noAuthNoPriv Pq default ,
1.5 martijn 343: .Cm authNoPriv
344: .Po
345: requires either
346: .Fl A
347: or
348: .Fl k
1.6 martijn 349: .Pc
350: or
351: .Cm authPriv
352: .Po
353: requires either
354: .Fl X
355: or
356: .Fl K
357: in addition to the
358: .Cm authNoPriv
359: requirements
1.5 martijn 360: .Pc .
1.4 martijn 361: This option is only used by
362: .Fl v Cm 3 .
363: .It Fl n Ar ctxname
364: Sets the context name.
365: Defaults to an empty string.
366: This option is only used by
367: .Fl v Cm 3 .
1.1 martijn 368: .It Fl O Ar output
369: Set the
370: .Ar output
371: options by supplying a string of one or more
372: of the following modifier letters:
373: .Bl -tag -width 1n
374: .It Cm a
375: Print the varbind string unchanged
376: rather than replacing non-printable bytes with dots.
377: .It Cm f
378: When displaying an OID, include the full list of MIB objects.
379: By default only the last textual MIB object is shown.
380: .It Cm n
381: Display the OID numerically.
382: .It Cm Q
383: Remove the type information.
384: .It Cm q
385: Remove the type information and the equal sign.
386: .It Cm S
387: Display the MIB name and the type information.
388: This is the default behaviour.
389: .It Cm v
390: Only display the varbind value, removing the OID.
391: .It Cm x
392: Display the varbind string values as hexadecimal strings.
393: .El
1.8 martijn 394: .Pp
395: The
396: .Cm mibtree
397: subcommand may only use the
398: .Op Fl fnS
399: output options;
400: no output options are available for
401: .Cm trap .
1.1 martijn 402: .It Fl r Ar retries
403: Set the number of
404: .Ar retries
405: in case of packet loss.
406: Defaults to 5.
407: .It Fl t Ar timeout
408: Set the
409: .Ar timeout
410: to wait for a reply, in seconds.
411: Defaults to 1.
1.4 martijn 412: .It Fl u Ar user
413: Sets the username.
414: If
415: .Fl v Cm 3
416: is used this option is required.
417: This option is only used by
418: .Fl v Cm 3 .
1.1 martijn 419: .It Fl v Ar version
420: Set the snmp protocol
421: .Ar version
422: to either
1.4 martijn 423: .Cm 1 ,
424: .Cm 2c
1.1 martijn 425: or
1.4 martijn 426: .Cm 3 .
1.1 martijn 427: Currently defaults to
428: .Cm 2c .
1.6 martijn 429: .It Fl X Ar privpass
430: The privacy password for the user.
431: This will be tansformed to
432: .Ar localpriv .
433: This option is only used by
434: .Fl v Cm 3 .
435: .It Fl x Ar cipher
436: Sets the cipher
437: .Pq privacy
438: protocol.
439: Options are
440: .Cm DES
441: and
1.18 martijn 442: .Cm AES .
443: This option defaults to
1.6 martijn 444: .Cm AES .
445: This option is only used by
446: .Fl v Cm 3 .
1.4 martijn 447: .It Fl Z Ar boots , Ns Ar time
448: Set the engine boots and engine time.
449: Under normal circumstances this value is discovered via snmpv3 discovery and
450: does not need to be specified.
451: This option is only used by
452: .Fl v Cm 3 .
1.1 martijn 453: .El
454: .Pp
455: The syntax for the
456: .Ar agent
457: argument is
1.8 martijn 458: .Oo Ar protocol : Oc Ns Ar address ,
459: with the following format:
1.1 martijn 460: .Bl -column udp6XXXtcp6X address -offset indent
461: .It Ar protocol Ta Ar address
462: .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc |
463: .Ar IPv4-address Ns Op Pf : Ar port
464: .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc |
465: .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc |
466: .Ar IPv6-address Ns Pf : Ar port
467: .It Cm unix Ta Ar pathname
468: .El
469: .Pp
470: The default
471: .Ar protocol
472: is
473: .Cm udp
474: and the default
475: .Ar port
1.8 martijn 476: is 161, except for the
477: .Cm trap
478: subcommand, which uses 162.
1.1 martijn 479: .Cm udpv6
480: and
481: .Cm udpipv6
482: are aliases for
483: .Cm udp6 ;
484: .Cm tcpv6
485: and
486: .Cm tcpipv6
487: for
488: .Cm tcp6 .
489: To specify an IPv6-address without a
490: .Ar port ,
491: the
492: .Ar IPv6-address
493: must be enclosed in square brackets.
494: If the square brackets are omitted,
495: the value after the last colon is always interpreted as a
496: .Ar port .
497: .Ss Data types
498: Additional data sent to the server is formatted by specifying one or more
499: triples of
500: .Ar varoid ,
501: .Ar type ,
502: and
503: .Ar value .
504: Supported types are:
1.8 martijn 505: .Bl -tag -width 1n -offset indent
1.1 martijn 506: .It Cm a
507: An IPv4 Address.
508: .It Cm b
509: A bitstring.
510: A list of individual bit offsets separated by comma, space or tab.
511: Must be supplied as a single argument.
512: .It Cm c
513: A counter32.
514: .It Cm d
515: A decimal string.
516: A list of individual bytes in decimal form separated by space or tab.
517: .It Cm i
518: An integer.
519: .It Cm n
520: A null object.
521: .It Cm o
522: An OID.
523: .It Cm s
524: A regular string.
525: .It Cm t
526: Timeticks in centiseconds.
527: .It Cm u
528: Unsigned integer.
529: .It Cm x
530: A hex string.
531: Similar to a decimal string, but in hexadecimal format.
1.14 martijn 532: .El
533: .Sh ENVIRONMENT
534: .Bl -tag -width LC_CTYPE
535: .It Ev LC_CTYPE
536: The character encoding
537: .Xr locale 1
538: used for output.
539: It decides whether objects having a display format of UTF-8 are printed as
540: UTF-8, and whether each byte invalid according to the object's display format is
541: printed as a UTF-8 replacement character
542: .Pq Sq \[uFFFD] .
543: .Pp
544: If unset or set to
545: .Qq C ,
546: .Qq POSIX ,
547: or an unsupported value, for objects having a display format of UTF-8, each
548: .Em printable
549: non-ASCII character is replaced with a single dot
550: .Pq Sq \&. .
551: Each byte invalid according to the object's display format is printed as a
552: question mark
553: .Pq Sq \&? .
554: .Pp
555: Each non-printable character is always replaced with a single dot
556: .Pq Sq \&. .
1.1 martijn 557: .El
558: .Sh SEE ALSO
559: .Xr snmpd 8
560: .Sh HISTORY
561: The
562: .Nm
563: program first appeared in
564: .Ox 6.6 .
565: .Sh AUTHORS
566: The
567: .Nm
568: program was written by
569: .An Martijn van Duren Aq Mt martijn@openbsd.org .