Annotation of src/usr.bin/snmp/snmp.1, Revision 1.8
1.7 martijn 1: .\" $OpenBSD: snmp.1,v 1.6 2019/09/18 09:54:36 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
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.1 martijn 259: .It Cm t
1.8 ! martijn 260: For
! 261: .Cm walk ,
! 262: Show how long it took to walk the entire tree.
1.1 martijn 263: .El
264: .It Fl c Ar community
265: Set the
266: .Ar community
267: string.
268: Defaults to
269: .Cm public .
1.4 martijn 270: This option is only used by
271: .Fl v Cm 1
272: and
273: .Fl v Cm 2c .
274: .It Fl e Ar secengineid
275: The USM security engine id.
276: Under normal circumstances this value is discovered via snmpv3 discovery and
277: does not need to be specified.
278: This option is only used by
279: .Fl v Cm 3 .
280: .It Fl E Ar ctxengineid
281: The snmpv3 context engine id.
282: Most of the time this value can be safely ignored.
1.5 martijn 283: This option is only used by
284: .Fl v Cm 3 .
1.6 martijn 285: .It Fl K Ar localpriv
286: The localized privacy password for the user in hexadecimal format
287: .Po
288: optionally prefixed with a
289: .Cm 0x
290: .Pc .
291: This option is only used by
292: .Fl v Cm 3 .
1.5 martijn 293: .It Fl k Ar localauth
294: The localized authentication password for the user in hexadecimal format
295: .Po
296: optionally prefixed with a
297: .Cm 0x
298: .Pc .
299: This option is only used by
300: .Fl v Cm 3 .
301: .It Fl l Ar seclevel
302: The security level.
303: Values can be
1.6 martijn 304: .Cm noAuthNoPriv Pq default ,
1.5 martijn 305: .Cm authNoPriv
306: .Po
307: requires either
308: .Fl A
309: or
310: .Fl k
1.6 martijn 311: .Pc
312: or
313: .Cm authPriv
314: .Po
315: requires either
316: .Fl X
317: or
318: .Fl K
319: in addition to the
320: .Cm authNoPriv
321: requirements
1.5 martijn 322: .Pc .
1.4 martijn 323: This option is only used by
324: .Fl v Cm 3 .
325: .It Fl n Ar ctxname
326: Sets the context name.
327: Defaults to an empty string.
328: This option is only used by
329: .Fl v Cm 3 .
1.1 martijn 330: .It Fl O Ar output
331: Set the
332: .Ar output
333: options by supplying a string of one or more
334: of the following modifier letters:
335: .Bl -tag -width 1n
336: .It Cm a
337: Print the varbind string unchanged
338: rather than replacing non-printable bytes with dots.
339: .It Cm f
340: When displaying an OID, include the full list of MIB objects.
341: By default only the last textual MIB object is shown.
342: .It Cm n
343: Display the OID numerically.
344: .It Cm Q
345: Remove the type information.
346: .It Cm q
347: Remove the type information and the equal sign.
348: .It Cm S
349: Display the MIB name and the type information.
350: This is the default behaviour.
351: .It Cm v
352: Only display the varbind value, removing the OID.
353: .It Cm x
354: Display the varbind string values as hexadecimal strings.
355: .El
1.8 ! martijn 356: .Pp
! 357: The
! 358: .Cm mibtree
! 359: subcommand may only use the
! 360: .Op Fl fnS
! 361: output options;
! 362: no output options are available for
! 363: .Cm trap .
1.1 martijn 364: .It Fl r Ar retries
365: Set the number of
366: .Ar retries
367: in case of packet loss.
368: Defaults to 5.
369: .It Fl t Ar timeout
370: Set the
371: .Ar timeout
372: to wait for a reply, in seconds.
373: Defaults to 1.
1.4 martijn 374: .It Fl u Ar user
375: Sets the username.
376: If
377: .Fl v Cm 3
378: is used this option is required.
379: This option is only used by
380: .Fl v Cm 3 .
1.1 martijn 381: .It Fl v Ar version
382: Set the snmp protocol
383: .Ar version
384: to either
1.4 martijn 385: .Cm 1 ,
386: .Cm 2c
1.1 martijn 387: or
1.4 martijn 388: .Cm 3 .
1.1 martijn 389: Currently defaults to
390: .Cm 2c .
1.6 martijn 391: .It Fl X Ar privpass
392: The privacy password for the user.
393: This will be tansformed to
394: .Ar localpriv .
395: This option is only used by
396: .Fl v Cm 3 .
397: .It Fl x Ar cipher
398: Sets the cipher
399: .Pq privacy
400: protocol.
401: Options are
402: .Cm DES
403: and
404: .Cm AES .
405: This option is only used by
406: .Fl v Cm 3 .
1.4 martijn 407: .It Fl Z Ar boots , Ns Ar time
408: Set the engine boots and engine time.
409: Under normal circumstances this value is discovered via snmpv3 discovery and
410: does not need to be specified.
411: This option is only used by
412: .Fl v Cm 3 .
1.1 martijn 413: .El
414: .Pp
415: The syntax for the
416: .Ar agent
417: argument is
1.8 ! martijn 418: .Oo Ar protocol : Oc Ns Ar address ,
! 419: with the following format:
1.1 martijn 420: .Bl -column udp6XXXtcp6X address -offset indent
421: .It Ar protocol Ta Ar address
422: .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc |
423: .Ar IPv4-address Ns Op Pf : Ar port
424: .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc |
425: .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc |
426: .Ar IPv6-address Ns Pf : Ar port
427: .It Cm unix Ta Ar pathname
428: .El
429: .Pp
430: The default
431: .Ar protocol
432: is
433: .Cm udp
434: and the default
435: .Ar port
1.8 ! martijn 436: is 161, except for the
! 437: .Cm trap
! 438: subcommand, which uses 162.
1.1 martijn 439: .Cm udpv6
440: and
441: .Cm udpipv6
442: are aliases for
443: .Cm udp6 ;
444: .Cm tcpv6
445: and
446: .Cm tcpipv6
447: for
448: .Cm tcp6 .
449: To specify an IPv6-address without a
450: .Ar port ,
451: the
452: .Ar IPv6-address
453: must be enclosed in square brackets.
454: If the square brackets are omitted,
455: the value after the last colon is always interpreted as a
456: .Ar port .
457: .Ss Data types
458: Additional data sent to the server is formatted by specifying one or more
459: triples of
460: .Ar varoid ,
461: .Ar type ,
462: and
463: .Ar value .
464: Supported types are:
1.8 ! martijn 465: .Bl -tag -width 1n -offset indent
1.1 martijn 466: .It Cm a
467: An IPv4 Address.
468: .It Cm b
469: A bitstring.
470: A list of individual bit offsets separated by comma, space or tab.
471: Must be supplied as a single argument.
472: .It Cm c
473: A counter32.
474: .It Cm d
475: A decimal string.
476: A list of individual bytes in decimal form separated by space or tab.
477: .It Cm i
478: An integer.
479: .It Cm n
480: A null object.
481: .It Cm o
482: An OID.
483: .It Cm s
484: A regular string.
485: .It Cm t
486: Timeticks in centiseconds.
487: .It Cm u
488: Unsigned integer.
489: Actually a normal integer for compatibility with netsnmp.
490: .It Cm x
491: A hex string.
492: Similar to a decimal string, but in hexadecimal format.
493: .El
494: .Sh SEE ALSO
495: .Xr snmpd 8
496: .Sh HISTORY
497: The
498: .Nm
499: program first appeared in
500: .Ox 6.6 .
501: .Sh AUTHORS
502: The
503: .Nm
504: program was written by
505: .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