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