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