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