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