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