2 .\" Copyright (c) 2010 The FreeBSD Foundation
3 .\" All rights reserved.
5 .\" Portions of this documentation were written by Shteryana Sotirova Shopova
6 .\" under sponsorship from the FreeBSD Foundation.
8 .\" Copyright (c) 2005-2007 The FreeBSD Project.
9 .\" All rights reserved.
11 .\" Author: Shteryana Shopova <syrinx@FreeBSD.org>
13 .\" Redistribution and use in source and binary forms, with or without
14 .\" modification, are permitted provided that the following conditions
16 .\" 1. Redistributions of source code must retain the above copyright
17 .\" notice, this list of conditions and the following disclaimer.
18 .\" 2. Redistributions in binary form must reproduce the above copyright
19 .\" notice, this list of conditions and the following disclaimer in the
20 .\" documentation and/or other materials provided with the distribution.
22 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
43 .Nd "simple tools for querying SNMP agents"
48 .Op Fl b Ar buffersize
53 .Op Fl M Ar max-repetitions
54 .Op Fl N Ar non-repeaters
59 .Op Fl s Ar [trans::][community@][server][:port]
68 .Op Fl b Ar buffersize
76 .Op Fl s Ar [trans::][community@][server][:port]
85 .Op Fl b Ar buffersize
93 .Op Fl s Ar [trans::][community@][server][:port]
97 .Ar OID Ns = Ar syntax Ns : Ns Ar value
98 .Op Ar OID Ns = Ar syntax Ns : Ns Ar value ...
104 are simple tools for retrieving management information from and setting
105 management information to a Simple Network Management Protocol (SNMP) agent.
107 Depending on the options
109 constructs either a SMNP GetRequest, GetNextRequest
110 or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the
111 objects whose values will be retrived, waits for a response and prints it if
112 received successfully.
115 queries an agent with ether SMNP GetNextRequest or GetBulkRequest packets,
116 asking for values of OID instances that are a part of the object subtree
117 rooted at the provided OIDs.
120 constructs a SMNP SetRequest packet, fills in the OIDs (object identifiers),
121 syntaxes and values of the objects whose values are to be set and waits for a
122 response from server.
124 The options are as follows (not all apply to all three programs):
125 .Bl -tag -width ".It Fl D Ar options"
127 Authentication options to use with SNMPv3 PDUs
129 .It Cm proto=[md5|sha]
130 The protocol to use when calculating the PDU message digest.
132 A binary localized authentication key to use when calculating the PDU message
136 By default SNMPv3 PDUs are sent unauthenticated.
138 Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU):
139 ingore syntax/access type, allow adding of non-leaf objects for GetPdu and
140 read-only objects to a SetPDU.
141 .It Fl b Ar buffersize
142 Tune the size of buffers used to send and receive packets.
143 The default size is 10000 bytes which should be enough unless an agent sends
144 a really large octetstring.
145 The maximum allowed length is 65535 according to the Structure of Management
148 The context to query with SNMPv3 PDUs.
151 The context name. Default is "" (empty).
152 .It Cm context-engine=engine-id
153 The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as
154 binary octet string. By default, this is set to the Engine ID of the SNMP agent.
157 Perform SNMP USM Engine Discovery, rather than sending a request for the value
158 of a specific object.
161 This option will cause the packets sent and received to be dumped to the
165 If an error is returned in the response PDU, resend the request removing the
166 variable that caused the error until a valid response is received.
167 This is only useful for a GetRequest- and a GetNextRequest-PDU.
169 Print a short help text with default values for various options.
171 Load each MIB description file from the given list to translate symbolic
172 object names to their numerical representation and vice versa.
173 Use the other options to obtain a non-default behaviour:
176 Specifies the initial OID that was cut by
178 when producing the MIB description file.
179 The default value is .iso(1).org(3).dod(6) which is what should have been
180 used for all the files installed under /usr/share/snmp/defs.
181 Use this only if you generated your own files, providing a
186 The directory where files in the list will be searched.
188 .Pa /usr/share/snmp/defs Ns .
190 A comma separated list of files to which the two options above will apply.
193 The file suboption has to come after the other suboptions so that their
194 non-default values will be applied to the list of files.
195 The order of the other suboptions before each file suboption can be random.
196 Suboptions may be separated either by commas or by spaces.
197 If using spaces make sure the entire option string is one argument, for
198 example using quotes.
200 List of MIB description files produced by
201 .Xr gensnmpdef 1 which
206 will search to translate numerical OIDs to their symbolic object names.
207 Multiple files can be provided either giving this option multiple times
208 or a comma separated list of file names.
209 If a filename begins with a letter the default directory,
210 /usr/share/snmp/defs,
213 Calculate and display the localized authentication and privacy keys
214 corresponding to a plain text password. The password is obtain via the
215 environment. Additionally, if one or more OIDs are specified, the calculated
216 keys are used when processing the SNMPv3 requests.
218 The path of the posix local (unix domain) socket if local
220 .It Fl M Ar max-repetitions
221 The value for the max-repetitions field in a GetBulk PDU.
223 .It Fl N Ar non-repeaters
224 The value for the non-repeaters field in a GetBulk PDU.
227 Only use numerical representations for input and output OIDs and do not
228 try to resolve symbolic object names.
234 will print numerical OIDs anyway if the corresponding string representation
235 is not found in the MIB description files.
236 .It Fl o Ar [quiet|short|verbose]
237 The format used to print the received response.
238 Quiet only prints values, short (default) prints an abbreviated OID
239 representation and the value.
240 In addition to the short output verbose prints the type before the value.
242 Privacy options to use with SNMPv3 PDUs
244 .It Cm proto=[aes|des]
245 The protocol to use when encypting/decrypting SNMPv3 PDU data.
247 A binary localized privacy key to use when encypting/decrypting SNMPv3 PDU data.
250 By default plain text SNMPv3 PDUs are sent.
251 .It Fl p Ar [get|getnext|getbulk]
252 The PDU type to send by
261 Getbulk allows executing the so called SNMP "bulkwalks" allowing the values of
262 multiple columns to be retrived in a single PDU by
265 Number of resends of request packets before giving up if the agent does
266 not respond after the first try.
268 .It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port]
269 Each of the server specification components is optional but at least one
270 has to be provided if
273 The server specification is constructed in the following manner:
276 Transport type may be one of udp, stream or dgram.
277 If this option is not provided an udp inet/inet6 socket will be used, which
279 Stream stands for a posix local stream socket and a posix local datagram
280 socket will be used if dgram is specified.
282 Specify an SNMP community string to be used when sending packets.
283 If the option is skipped the default "public" will be used for
287 and the default "private" community string will be used for
290 This might be either the IP address or the hostname where the agent is
295 The destination port to send the requests to.
296 This is useful if the SNMP agent listens on a non-default port.
297 Default is given by the
304 Number of seconds before resending a request packet if the agent does
306 The default value is 3 seconds.
308 User credentials when sending SNMPv3 PDUs.
311 The Engine ID of the SNMP agent represented as a binary octet string.
312 .It Cm engine-boots=value
313 The value of the snmpEngineBoots of the SNMP agent.
314 .It Cm engine-time=value
315 The value of the snmpEngineTime of the SNMP agent.
317 If any of the above is not specified, SNMP USM Engine Discovery is attempted.
318 This is also the default behavior.
320 The USM user name to include in the SNMPv3 PDUs. By default, the user name is
321 obtain via the environment
324 The SNMP protocol version to use when sending requests. SNMP versions 1, 2 and
326 If no version option is provided
332 Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the
333 version to 1 is incompatiable with sending a GetBulk PDU.
335 The object identifier whose value to retrive.
336 At least one OID should be provided for
338 to be able to send a request.
342 this is the root object identifier of the subtree whose values are to be
344 If no OID is provided
346 will walk the mib2 subtree rooted
347 at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) .
349 Any of the formats used to print a single variable
350 is valid as input OID:
352 .It 1.3.6.1.2.1.25.1.1.0
355 .It ifRcvAddressStatus.2.6.255.255.255.255.255.255
356 .It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff]
357 .It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]
363 Square brackets are used to denote an entry's indexes.
364 When used in an input OID, the square brackets may have to be
365 escaped or the OID has to be quoted to protect it from the shell.
366 Note there is no difference between ifName.1 and "ifName[1]".
367 .It OID Ns = Ns Ar [syntax Ns :] Ns Ar value
368 The object identifier with its syntax type and value that is to be set.
369 At least one such string OID=[syntax:]value should be provided to
371 to be able to send a request.
374 OID may be input as a string, a string followed by a random number of integers
375 (suboids) separated by dots, a sequence of integers separated by dots - that is
378 options is used - and in such case a syntax is required for every value,
379 or a string followed by square brackets (used to denote an entry's indexes) and
380 corresponding indexes.
381 Any of formats used to print a single variable by
383 valid for inpit OID as well:
385 .It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486
386 .It sysLocation=OctetString:"@ Home" (with Fl o Ar verbose No option)
387 .It sysLocation.0="@ Home"
388 .It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff
389 .It ifPhysAddress.1="00:02:b3:1d:1c:a3"
390 .It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1
391 .It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1"
397 where syntax string is one of:
398 Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64.
400 The value to be set - IP address in form of u.u.u.u - for example
401 1.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they
402 contain any special characters or spaces, all other numeric types don't.
410 use the following environment variables:
411 .Bl -tag -width SNMPAUTH
413 Specifies a default SNMP USM authentication protocol.
415 Specifies a default SNMP USM privacy protocol.
417 Specifies a default SNMP USM user name.
419 Specifies the SNMP USM plain text password to use when calculating localized
420 authentication and privacy keys. If this variable exists in the environment,
421 SMNPv3 is the default version to use for outgoing requests.
426 .An Shteryana Shopova Aq syrinx@FreeBSD.org