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 September 17, 2007 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 Managment Protocol (SNMP) agent. 106.Pp 107Depending on the options 108.Nm bsnmpget 109constructs either a SMNP GetRequest, GetNextRequest 110or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the 111objects whose values will be retrived, waits for a response and prints it if 112received successfully. 113.Pp 114.Nm Bsnmpwalk 115queries an agent with SMNP GetNextRequest 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 SMNP SetRequest packet, fills in the OIDs (object identifiers), 121syntaxes and values of the objects whose values are to be set and waits for a 122responce from server. 123.Sh OPTIONS 124.Pp 125The options are as follows (not all apply to all three programs): 126.Bl -tag -width ".It Fl D Ar options" 127.It Fl A Ar options 128Authentication options to use with SNMPv3 PDUs 129.Bl -tag -width 130.It Cm proto=[md5|sha] 131The protocol to use when calculating the PDU message digest. 132.It Cm key=authkey 133A binary localized authentication key to use when calculating the PDU message 134digest. 135.El 136.Pp 137By default SNMPv3 PDUs are sent unauthenticated. 138.It Fl a 139Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU): 140ingore syntax/access type, allow adding of non-leaf objects for GetPdu and 141read-only objects to a SetPDU. 142.It Fl b Ar buffersize 143Tune the size of buffers used to send and receive packets. 144The default size is 10000 bytes which should be enough unless an agent sends 145a really large octetstring. 146The maximum allowed length is 65535 according to the Structure of Management 147Information (SMIv2). 148.It Fl C Ar options 149The context to query with SNMPv3 PDUs. 150.Bl -tag -width 151.It Cm context=name 152The context name. Default 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. By default, this is set to the Engine ID of the SNMP agent. 156.El 157.It Fl D 158Perform SNMP USM Engine Discovery, rather than sending a request for the value 159of a specific object. 160.It Fl d 161Turn on debugging. 162This option will cause the packets sent and received to be dumped to the 163terminal. 164.It Fl e 165Retry on error. 166If an error is returned in the response PDU, resend the request removing the 167variable that caused the error until a valid response is received. 168This is only usefull for a GetRequest- and a GetNextRequest-PDU. 169.It Fl h 170Print a short help text with default values for various options. 171.It Fl I Ar options 172Load each MIB description file from the given list to translate symbolic 173object names to their numerical representation and vice versa. 174Use the other options to obtain a non-default behaviour: 175.Bl -tag -width 176.It Cm cut=OID 177Specifies the initial OID that was cut by 178.Xr gensnmpdef 1 179when producing the MIB description file. 180The default value is .iso(1).org(3).dod(6) which is what should have been 181used for all the files installed under /usr/share/snmp/defs/ . 182Use this only if you generated your own files, providing a '-c' option to 183.Xr gensnmpdef 1 . 184.It Cm path=filedir 185The directory where files in the list will be searched. 186The default is 187.Pa /usr/share/snmp/defs/ . 188.It Cm file=filelist 189A comma separated list of files to which the two options above will apply. 190.El 191.Pp 192The file suboption has to come after the other suboptions so that their 193non-default values will be applied to the list of files. 194The order of the other suboptions before each file suboption can be random. 195Suboptions may be separated either by commas or by spaces. 196If using spaces make sure the entire option string is one argument, for 197example using quotes. 198.It Fl i Ar filelist 199List of MIB description files produced by 200.Xr gensnmpdef 1 which 201.Nm bsnmpget , 202.Nm bsnmpwalk 203or 204.Nm bsnmpset 205will search to translate numerical OIDs to their symbolic object names. 206Multiple files can be provided either giving this option multiple times 207or a comma separated list of file names. 208If a filename begins with a letter the default directory, 209/usr/share/snmp/defs/ , 210will be searched. 211.It Fl K 212Calculate and display the localized authentication and privacy keys 213corresponding to a plain text password. The password is obtain via the 214environment. Additionally, if one or more OIDs are specified, the calculated 215keys are used when processing the SNMPv3 requests. 216.It Fl l Ar filename 217The path of the posix local (unix domain) socket if local 218transport is used. 219.It Fl M Ar max-repetitions 220The value for the max-repetitions field in a GetBulk PDU. 221Default is 1. 222.It Fl N Ar non-repeaters 223The value for the non-repeaters field in a GetBulk PDU. 224Default is 0. 225.It Fl n 226Only use numerical representations for input and output OIDs and do not 227try to resolve symbolic object names. 228Note that 229.Nm bsnmpget , 230.Nm bsnmpwalk 231and 232.Nm bsnmpset 233will print numerical OIDs anyway if the corresponding string representation 234is not found in the MIB description files. 235.It Fl o Ar [quiet|short|verbose] 236The format used to print the received response. 237Quiet only prints values, short (default) prints an abbreviated OID 238representation and the value. 239In addition to the short output verbose prints the type before the value. 240.It Fl P Ar options 241Privacy options to use with SNMPv3 PDUs 242.Bl -tag -width 243.It Cm proto=[aes|des] 244The protocol to use when encypting/decrypting SNMPv3 PDU data. 245.It Cm key=privkey 246A binary localized privacy key to use when encypting/decrypting SNMPv3 PDU data. 247.El 248.Pp 249By default plain text SNMPv3 PDUs are sent. 250.It Fl p Ar [get|getnext|getbulk] 251The PDU type to send by 252.Nm bsmpget . 253Default is get. 254.It Fl r Ar retries 255Number of resends of request packets before giving up if the agent does 256not respond after the first try. 257Default is 3. 258.It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port] 259Each of the server specification components is optional but at least one 260has to be provided if '-s' option is used. 261The server specification is constructed in the following manner: 262.Bl -tag -width 263.It Cm trans:: 264Transport type may be one of udp, stream or dgram. 265If this option is not provided an udp inet/inet6 socket will be used, which 266is the most common. 267Stream stands for a posix local stream socket and a posix local datagram 268socket will be used if dgram is specified. 269.It Cm community@ 270Specify an SNMP community string to be used when sending packets. 271If the option is skipped the default "public" will be used for 272.Nm 273and 274.Nm bsnmpwalk 275and the default "private" community string will be used for 276.Nm bsnmpset . 277.It Cm server 278This might be either the IP address or the hostname where the agent is 279listening. 280The default is 'localhost'. 281.It Cm port 282The destination port to send the requests to. 283This is useful if the SNMP agent listens on a non-default port. 284Default is given by the 'snmp' entry in /etc/services, port 161. 285.El 286.It Fl t Ar timeout 287Number of seconds before resending a request packet if the agent does 288not respond. 289The default value is 3 seconds. 290.It Fl U Ar options 291User credentials when sending SNMPv3 PDUs. 292.Bl -tag -width 293.It Cm engine=id 294The Engine ID of the SNMP agent represented as a binary octet string. 295.It Cm engine-boots=value 296The value of the snmpEngineBoots of the SNMP agent. 297.It Cm engine-time=value 298The value of the snmpEngineTime of the SNMP agent. 299.Pp 300If any of the above is not specified, SNMP USM Engine Discovery is attempted. 301This is also the default behavior. 302.It Cm name=username 303The USM user name to include in the SNMPv3 PDUs. By default, the user name is 304obtain via the environment 305.El 306.It Fl v Ar version 307The SNMP protocol version to use when sending requests. SNMP versions 1, 2 and 3083 are supported. 309If no version option is provided 310.Nm bsnmpget , 311.Nm bsnmpwalk 312and 313.Nm bsnmpset 314will use version 2. 315Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the 316version to 1 is incompatiable with sending a GetBulk PDU. 317.It OID 318The object identifier whose value to retrive. 319At least one OID should be provided for 320.Nm bsnmpget 321to be able to send a request. 322.Pp 323For 324.Nm bsnmpwalk 325this is the root object identifier of the subtree whose values are to be 326retrived. 327If no OID is provided 328.Nm bsnmpwalk 329will walk the mib2 subtree rooted 330at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) . 331.Pp 332Any of the formats used to print a single variable 333is valid as input OID: 334.Bl -tag -width 335.It 1.3.6.1.2.1.25.1.1.0 336.It sysDescr 337.It ifPhysAddress.1 338.It ifRcvAddressStatus.2.6.255.255.255.255.255.255 339.It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff] 340.It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff] 341(requires '-o verbose' option) 342.El 343.Pp 344Square brackets are used to denote an entry's indexes. 345When used in an input OID, the square brackets may have to be 346escaped or the OID has to be quoted to protect it from the shell. 347Note there is no difference between ifName.1 and "ifName[1]". 348.It OID Ns = Ns Ar [syntax Ns :] Ns Ar value 349The object identifier with its syntax type and value that is to be set. 350At least one such string OID=[syntax:]value should be provided to 351.Nm bsnmpset 352to be able to send a request. 353.Bl -tag -width 354.It Cm OID 355OID may be input as a string, a string followed by a random number of integers 356(suboids) separated by dots, a sequence of integers separated by dots - that is 357if '-n' options is used - and in such case a syntax is required for every value, 358or a string followed by square brackets (used to denote an entry's indexes) and 359corresponding indexes. 360Any of formats used to print a single variable by 361.Nm bsnmpset is 362valid for inpit OID as well: 363.Bl -tag -width 364.It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486 365.It sysLocation=OctetString:"@ Home" (with '-o verbose' option) 366.It sysLocation.0="@ Home" 367.It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff 368.It ifPhysAddress.1="00:02:b3:1d:1c:a3" 369.It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1 370.It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1" 371(with '-o verbose' option) 372.El 373.It Cm syntax 374where syntax string is one of : 375Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64. 376.It Cm value 377The value to be set - IP address in form of u.u.u.u - for example 3781.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they 379contain any special characters or spaces, all other numeric types don't. 380.El 381.Sh ENVIRONMENT 382.Nm , 383.Nm bsnmpwalk 384and 385.Nm bsnmpset 386use the following environment variables: 387.Bl -tag -width SNMPAUTH 388.It Ev SNMPAUTH 389Specifies a default SNMP USM authentication protocol. 390.It Ev SNMPPRIV 391Specifies a default SNMP USM privacy protocol. 392.It Ev SNMPUSER 393Specifies a default SNMP USM user name. 394.It Ev SNMPPASSWD 395Specifies the SNMP USM plain text password to use when calculating localized 396authentication and privacy keys. If this variable exists in the environment, 397SMNPv3 is the default version to use for outgoing requests. 398.Sh SEE ALSO 399.Xr gensnmpdef 1 400.Sh AUTHORS 401.An Shteryana Shopova Aq syrinx@FreeBSD.org 402