Annotation of src/usr.bin/snmp/snmp.1, Revision 1.15
1.15 ! martijn 1: .\" $OpenBSD: snmp.1,v 1.14 2020/08/08 07:11: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.15 ! martijn 17: .Dd $Mdocdate: August 8 2020 $
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
! 173: is specified it wil print the objects in the requested output format if
! 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
200: .Cm MD5 .
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
442: .Cm AES .
443: This option is only used by
444: .Fl v Cm 3 .
1.4 martijn 445: .It Fl Z Ar boots , Ns Ar time
446: Set the engine boots and engine time.
447: Under normal circumstances this value is discovered via snmpv3 discovery and
448: does not need to be specified.
449: This option is only used by
450: .Fl v Cm 3 .
1.1 martijn 451: .El
452: .Pp
453: The syntax for the
454: .Ar agent
455: argument is
1.8 martijn 456: .Oo Ar protocol : Oc Ns Ar address ,
457: with the following format:
1.1 martijn 458: .Bl -column udp6XXXtcp6X address -offset indent
459: .It Ar protocol Ta Ar address
460: .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc |
461: .Ar IPv4-address Ns Op Pf : Ar port
462: .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc |
463: .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc |
464: .Ar IPv6-address Ns Pf : Ar port
465: .It Cm unix Ta Ar pathname
466: .El
467: .Pp
468: The default
469: .Ar protocol
470: is
471: .Cm udp
472: and the default
473: .Ar port
1.8 martijn 474: is 161, except for the
475: .Cm trap
476: subcommand, which uses 162.
1.1 martijn 477: .Cm udpv6
478: and
479: .Cm udpipv6
480: are aliases for
481: .Cm udp6 ;
482: .Cm tcpv6
483: and
484: .Cm tcpipv6
485: for
486: .Cm tcp6 .
487: To specify an IPv6-address without a
488: .Ar port ,
489: the
490: .Ar IPv6-address
491: must be enclosed in square brackets.
492: If the square brackets are omitted,
493: the value after the last colon is always interpreted as a
494: .Ar port .
495: .Ss Data types
496: Additional data sent to the server is formatted by specifying one or more
497: triples of
498: .Ar varoid ,
499: .Ar type ,
500: and
501: .Ar value .
502: Supported types are:
1.8 martijn 503: .Bl -tag -width 1n -offset indent
1.1 martijn 504: .It Cm a
505: An IPv4 Address.
506: .It Cm b
507: A bitstring.
508: A list of individual bit offsets separated by comma, space or tab.
509: Must be supplied as a single argument.
510: .It Cm c
511: A counter32.
512: .It Cm d
513: A decimal string.
514: A list of individual bytes in decimal form separated by space or tab.
515: .It Cm i
516: An integer.
517: .It Cm n
518: A null object.
519: .It Cm o
520: An OID.
521: .It Cm s
522: A regular string.
523: .It Cm t
524: Timeticks in centiseconds.
525: .It Cm u
526: Unsigned integer.
527: Actually a normal integer for compatibility with netsnmp.
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 .
![[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