1.\" 2.\" Copyright (c) 2010 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" Portions of this documentation were written by Shteryana Sotirova Shopova 6.\" under sponsorship from the FreeBSD Foundation. 7.\" 8.\" Copyright (c) 2005-2007 The FreeBSD Project. 9.\" All rights reserved. 10.\" 11.\" Author: Shteryana Shopova <syrinx@FreeBSD.org> 12.\" 13.\" Redistribution and use in source and binary forms, with or without 14.\" modification, are permitted provided that the following conditions 15.\" are met: 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. 21.\" 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 32.\" SUCH DAMAGE. 33.\" 34.\" $FreeBSD$ 35.\" 36.Dd January 10, 2012 37.Dt BSNMPGET 1 38.Os 39.Sh NAME 40.Nm bsnmpget , 41.Nm bsnmpwalk , 42.Nm bsnmpset 43.Nd "simple tools for querying SNMP agents" 44.Sh SYNOPSIS 45.Nm 46.Op Fl aDdehnK 47.Op Fl A Ar options 48.Op Fl b Ar buffersize 49.Op Fl C Ar options 50.Op Fl I Ar options 51.Op Fl i Ar filelist 52.Op Fl l Ar filename 53.Op Fl M Ar max-repetitions 54.Op Fl N Ar non-repeaters 55.Op Fl o Ar output 56.Op Fl P Ar options 57.Op Fl p Ar pdu 58.Op Fl r Ar retries 59.Op Fl s Ar [trans::][community@][server][:port] 60.Op Fl t Ar timeout 61.Op Fl U Ar options 62.Op Fl v Ar version 63.Op Ar OID ... 64.Pp 65.Nm bsnmpwalk 66.Op Fl dhnK 67.Op Fl A Ar options 68.Op Fl b Ar buffersize 69.Op Fl C Ar options 70.Op Fl I Ar options 71.Op Fl i Ar filelist 72.Op Fl l Ar filename 73.Op Fl o Ar output 74.Op Fl P Ar options 75.Op Fl r Ar retries 76.Op Fl s Ar [trans::][community@][server][:port] 77.Op Fl t Ar timeout 78.Op Fl U Ar options 79.Op Fl v Ar version 80.Op Ar OID ... 81.Pp 82.Nm bsnmpset 83.Op Fl adehnK 84.Op Fl A Ar options 85.Op Fl b Ar buffersize 86.Op Fl C Ar options 87.Op Fl I Ar options 88.Op Fl i Ar filelist 89.Op Fl l Ar filename 90.Op Fl o Ar output 91.Op Fl P Ar options 92.Op Fl r Ar retries 93.Op Fl s Ar [trans::][community@][server][:port] 94.Op Fl t Ar timeout 95.Op Fl U Ar options 96.Op Fl v Ar version 97.Ar OID Ns = Ar syntax Ns : Ns Ar value 98.Op Ar OID Ns = Ar syntax Ns : Ns Ar value ... 99.Sh DESCRIPTION 100.Nm , 101.Nm bsnmpwalk 102and 103.Nm bsnmpset 104are simple tools for retrieving management information from and setting 105management information to a Simple Network Management Protocol (SNMP) agent. 106.Pp 107Depending on the options 108.Nm bsnmpget 109constructs either a SNMP GetRequest, GetNextRequest 110or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the 111objects whose values will be retrieved, waits for a response and prints it if 112received successfully. 113.Pp 114.Nm Bsnmpwalk 115queries an agent with ether SNMP GetNextRequest or GetBulkRequest packets, 116asking for values of OID instances that are a part of the object subtree 117rooted at the provided OIDs. 118.Pp 119.Nm Bsnmpset 120constructs a SNMP SetRequest packet, fills in the OIDs (object identifiers), 121syntaxes and values of the objects whose values are to be set and waits for a 122response from server. 123.Sh OPTIONS 124The options are as follows (not all apply to all three programs): 125.Bl -tag -width ".It Fl D Ar options" 126.It Fl A Ar options 127Authentication options to use with SNMPv3 PDUs 128.Bl -tag -width \& 129.It Cm proto=[md5|sha] 130The protocol to use when calculating the PDU message digest. 131.It Cm key=authkey 132A binary localized authentication key to use when calculating the PDU message 133digest. 134.El 135.Pp 136By default SNMPv3 PDUs are sent unauthenticated. 137.It Fl a 138Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU): 139ignore syntax/access type, allow adding of non-leaf objects for GetPdu and 140read-only objects to a SetPDU. 141.It Fl b Ar buffersize 142Tune the size of buffers used to send and receive packets. 143The default size is 10000 bytes which should be enough unless an agent sends 144a really large octetstring. 145The maximum allowed length is 65535 according to the Structure of Management 146Information (SMIv2). 147.It Fl C Ar options 148The context to query with SNMPv3 PDUs. 149.Bl -tag -width \& 150.It Cm context=name 151The context name. 152Default is "" (empty). 153.It Cm context-engine=engine-id 154The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as 155binary octet string. 156By default, this is set to the Engine ID of the SNMP agent. 157.El 158.It Fl D 159Perform SNMP USM Engine Discovery, rather than sending a request for the value 160of a specific object. 161.It Fl d 162Turn on debugging. 163This option will cause the packets sent and received to be dumped to the 164terminal. 165.It Fl e 166Retry on error. 167If an error is returned in the response PDU, resend the request removing the 168variable that caused the error until a valid response is received. 169This is only useful for a GetRequest- and a GetNextRequest-PDU. 170.It Fl h 171Print a short help text with default values for various options. 172.It Fl I Ar options 173Load each MIB description file from the given list to translate symbolic 174object names to their numerical representation and vice versa. 175Use the other options to obtain a non-default behaviour: 176.Bl -tag -width \& 177.It Cm cut=OID 178Specifies the initial OID that was cut by 179.Xr gensnmpdef 1 180when producing the MIB description file. 181The default value is .iso(1).org(3).dod(6) which is what should have been 182used for all the files installed under 183.Pa /usr/share/snmp/defs . 184Use this only if you generated your own files, providing a 185.Fl c 186option to 187.Xr gensnmpdef 1 . 188.It Cm path=filedir 189The directory where files in the list will be searched. 190The default is 191.Pa /usr/share/snmp/defs Ns . 192.It Cm file=filelist 193A comma separated list of files to which the two options above will apply. 194.El 195.Pp 196The file suboption has to come after the other suboptions so that their 197non-default values will be applied to the list of files. 198The order of the other suboptions before each file suboption can be random. 199Suboptions may be separated either by commas or by spaces. 200If using spaces make sure the entire option string is one argument, for 201example using quotes. 202.It Fl i Ar filelist 203List of MIB description files produced by 204.Xr gensnmpdef 1 205which 206.Nm bsnmpget , 207.Nm bsnmpwalk 208or 209.Nm bsnmpset 210will search to translate numerical OIDs to their symbolic object names. 211Multiple files can be provided either giving this option multiple times 212or a comma separated list of file names. 213If a filename begins with a letter the default directory, 214.Pa /usr/share/snmp/defs , 215will be searched. 216.It Fl K 217Calculate and display the localized authentication and privacy keys 218corresponding to a plain text password. 219The password is obtained via the environment. 220Additionally, if one or more OIDs are specified, the calculated 221keys are used when processing the SNMPv3 requests. 222.It Fl l Ar filename 223The path of the posix local (unix domain) socket if local 224transport is used. 225.It Fl M Ar max-repetitions 226The value for the max-repetitions field in a GetBulk PDU. 227Default is 10. 228.It Fl N Ar non-repeaters 229The value for the non-repeaters field in a GetBulk PDU. 230Default is 0. 231.It Fl n 232Only use numerical representations for input and output OIDs and do not 233try to resolve symbolic object names. 234Note that 235.Nm bsnmpget , 236.Nm bsnmpwalk 237and 238.Nm bsnmpset 239will print numerical OIDs anyway if the corresponding string representation 240is not found in the MIB description files. 241.It Fl o Ar [quiet|short|verbose] 242The format used to print the received response. 243Quiet only prints values, short (default) prints an abbreviated OID 244representation and the value. 245In addition to the short output verbose prints the type before the value. 246.It Fl P Ar options 247Privacy options to use with SNMPv3 PDUs 248.Bl -tag -width \& 249.It Cm proto=[aes|des] 250The protocol to use when encrypting/decrypting SNMPv3 PDU data. 251.It Cm key=privkey 252A binary localized privacy key to use when encrypting/decrypting SNMPv3 PDU data. 253.El 254.Pp 255By default plain text SNMPv3 PDUs are sent. 256.It Fl p Ar [get|getnext|getbulk] 257The PDU type to send by 258.Nm bsmpget 259and 260.Nm bsnmpwalk . 261Default is get 262for 263.Nm bsmpget 264and getnext for 265.Nm bsnmpwalk . 266Getbulk allows executing the so called SNMP "bulkwalks" allowing the values of 267multiple columns to be retrieved in a single PDU by 268.Nm bsnmpwalk . 269.It Fl r Ar retries 270Number of resends of request packets before giving up if the agent does 271not respond after the first try. 272Default is 3. 273.It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port] 274Each of the server specification components is optional but at least one 275has to be provided if the 276.Ar s 277option is used. 278The server specification is constructed in the following manner: 279.Bl -tag -width \& 280.It Cm trans:: 281Transport type may be one of udp, stream or dgram. 282If this option is not provided an UDP inet/inet6 socket will be used, which 283is the most common. 284Stream stands for a posix local stream socket and a posix local datagram 285socket will be used if dgram is specified. 286.It Cm community@ 287Specify an SNMP community string to be used when sending packets. 288If the option is skipped the default "public" will be used for 289.Nm 290and 291.Nm bsnmpwalk 292and the default "private" community string will be used for 293.Nm bsnmpset . 294.It Cm server 295This might be either the IP address or the hostname where the agent is 296listening. 297The default is 298.Qq localhost . 299.It Cm port 300The destination port to send the requests to. 301This is useful if the SNMP agent listens on a non-default port. 302Default is given by the 303.Qq snmp 304entry in 305.Pa /etc/services , 306port 161. 307.El 308.It Fl t Ar timeout 309Number of seconds before resending a request packet if the agent does 310not respond. 311The default value is 3 seconds. 312.It Fl U Ar options 313User credentials when sending SNMPv3 PDUs. 314.Bl -tag -width \& 315.It Cm engine=id 316The Engine ID of the SNMP agent represented as a binary octet string. 317.It Cm engine-boots=value 318The value of the snmpEngineBoots of the SNMP agent. 319.It Cm engine-time=value 320The value of the snmpEngineTime of the SNMP agent. 321.Pp 322If any of the above is not specified, SNMP USM Engine Discovery is attempted. 323This is also the default behavior. 324.It Cm name=username 325The USM user name to include in the SNMPv3 PDUs. 326By default, the user name is 327obtained via the environment. 328.El 329.It Fl v Ar version 330The SNMP protocol version to use when sending requests. 331SNMP versions 1, 2 and 3323 are supported. 333If no version option is provided 334.Nm bsnmpget , 335.Nm bsnmpwalk 336and 337.Nm bsnmpset 338will use version 2. 339Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the 340version to 1 is incompatible with sending a GetBulk PDU. 341.It OID 342The object identifier whose value to retrieve. 343At least one OID should be provided for 344.Nm bsnmpget 345to be able to send a request. 346.Pp 347For 348.Nm bsnmpwalk 349this is the root object identifier of the subtree whose values are to be 350retrieved. 351If no OID is provided 352.Nm bsnmpwalk 353will walk the mib2 subtree rooted 354at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) . 355.Pp 356Any of the formats used to print a single variable 357is valid as input OID: 358.Bl -tag -width \& 359.It 1.3.6.1.2.1.25.1.1.0 360.It sysDescr 361.It ifPhysAddress.1 362.It ifRcvAddressStatus.2.6.255.255.255.255.255.255 363.It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff] 364.It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff] 365(requires the 366.Fl o Ar verbose 367option) 368.El 369.Pp 370Square brackets are used to denote an entry's indexes. 371When used in an input OID, the square brackets may have to be 372escaped or the OID has to be quoted to protect it from the shell. 373Note there is no difference between ifName.1 and "ifName[1]". 374.It OID Ns = Ns Ar [syntax Ns :] Ns Ar value 375The object identifier with its syntax type and value that is to be set. 376At least one such string OID=[syntax:]value should be provided to 377.Nm bsnmpset 378to be able to send a request. 379.Bl -tag -width \& 380.It Cm OID 381OID may be input as a string, a string followed by a random number of integers 382(suboids) separated by dots, a sequence of integers separated by dots - that is 383if the 384.Ar n 385option is used - and in such case a syntax is required for every value, 386or a string followed by square brackets (used to denote an entry's indexes) and 387corresponding indexes. 388Any of the formats used to print a single variable by 389.Nm bsnmpset 390is valid as input OID as well: 391.Bl -tag -width \& 392.It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486 393.It sysLocation=OctetString:"@ Home" (with Fl o Ar verbose No option) 394.It sysLocation.0="@ Home" 395.It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff 396.It ifPhysAddress.1="00:02:b3:1d:1c:a3" 397.It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1 398.It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1" 399(with the 400.Fl o Ar verbose 401option) 402.El 403.It Cm syntax 404where the syntax string is one of: 405Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64. 406.It Cm value 407The value to be set - IP address in form of u.u.u.u - for example 4081.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they 409contain any special characters or spaces, all other numeric types do not. 410.El 411.El 412.Sh ENVIRONMENT 413.Nm , 414.Nm bsnmpwalk 415and 416.Nm bsnmpset 417use the following environment variables: 418.Bl -tag -width SNMPAUTH 419.It Ev SNMPAUTH 420Specifies a default SNMP USM authentication protocol. 421.It Ev SNMPPRIV 422Specifies a default SNMP USM privacy protocol. 423.It Ev SNMPUSER 424Specifies a default SNMP USM user name. 425.It Ev SNMPPASSWD 426Specifies the SNMP USM plain text password to use when calculating localized 427authentication and privacy keys. 428If this variable exists in the environment, 429SNMPv3 is the default version to use for outgoing requests. 430.El 431.Sh SEE ALSO 432.Xr gensnmpdef 1 433.Sh AUTHORS 434.An Shteryana Shopova Aq Mt syrinx@FreeBSD.org 435