usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1

   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
 102 and
 103 .Nm bsnmpset
 104 are simple tools for retrieving management information from and setting
 105 management information to a Simple Network Management Protocol (SNMP) agent.
 106 .Pp
 107 Depending on the options
 108 .Nm bsnmpget
 109 constructs either a SNMP GetRequest, GetNextRequest
 110 or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the
 111 objects whose values will be retrieved, waits for a response and prints it if
 112 received successfully.
 113 .Pp
 114 .Nm Bsnmpwalk
 115 queries an agent with ether SNMP 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.
 118 .Pp
 119 .Nm Bsnmpset
 120 constructs a SNMP 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.
 123 .Sh OPTIONS
 124 The 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
 127 Authentication options to use with SNMPv3 PDUs
 128 .Bl -tag -width \&
 129 .It Cm proto=[md5|sha]
 130 The protocol to use when calculating the PDU message digest.
 131 .It Cm key=authkey
 132 A binary localized authentication key to use when calculating the PDU message
 133 digest.
 134 .El
 135 .Pp
 136 By default SNMPv3 PDUs are sent unauthenticated.
 137 .It Fl a
 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
 146 Information (SMIv2).
 147 .It Fl C Ar options
 148 The context to query with SNMPv3 PDUs.
 149 .Bl -tag -width \&
 150 .It Cm context=name
 151 The context name.
 152 Default is "" (empty).
 153 .It Cm context-engine=engine-id
 154 The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as
 155 binary octet string.
 156 By default, this is set to the Engine ID of the SNMP agent.
 157 .El
 158 .It Fl D
 159 Perform SNMP USM Engine Discovery, rather than sending a request for the value
 160 of a specific object.
 161 .It Fl d
 162 Turn on debugging.
 163 This option will cause the packets sent and received to be dumped to the
 164 terminal.
 165 .It Fl e
 166 Retry on error.
 167 If an error is returned in the response PDU, resend the request removing the
 168 variable that caused the error until a valid response is received.
 169 This is only useful for a GetRequest- and a GetNextRequest-PDU.
 170 .It Fl h
 171 Print a short help text with default values for various options.
 172 .It Fl I Ar options
 173 Load each MIB description file from the given list to translate symbolic
 174 object names to their numerical representation and vice versa.
 175 Use the other options to obtain a non-default behaviour:
 176 .Bl -tag -width \&
 177 .It Cm cut=OID
 178 Specifies the initial OID that was cut by
 179 .Xr gensnmpdef 1
 180 when producing the MIB description file.
 181 The default value is .iso(1).org(3).dod(6) which is what should have been
 182 used for all the files installed under
 183 .Pa /usr/share/snmp/defs .
 184 Use this only if you generated your own files, providing a
 185 .Fl c
 186 option to
 187 .Xr gensnmpdef 1 .
 188 .It Cm path=filedir
 189 The directory where files in the list will be searched.
 190 The default is
 191 .Pa /usr/share/snmp/defs Ns .
 192 .It Cm file=filelist
 193 A comma separated list of files to which the two options above will apply.
 194 .El
 195 .Pp
 196 The file suboption has to come after the other suboptions so that their
 197 non-default values will be applied to the list of files.
 198 The order of the other suboptions before each file suboption can be random.
 199 Suboptions may be separated either by commas or by spaces.
 200 If using spaces make sure the entire option string is one argument, for
 201 example using quotes.
 202 .It Fl i Ar filelist
 203 List of MIB description files produced by
 204 .Xr gensnmpdef 1
 205 which
 206 .Nm bsnmpget ,
 207 .Nm bsnmpwalk
 208 or
 209 .Nm bsnmpset
 210 will search to translate numerical OIDs to their symbolic object names.
 211 Multiple files can be provided either giving this option multiple times
 212 or a comma separated list of file names.
 213 If a filename begins with a letter the default directory,
 214 .Pa /usr/share/snmp/defs ,
 215 will be searched.
 216 .It Fl K
 217 Calculate and display the localized authentication and privacy keys
 218 corresponding to a plain text password.
 219 The password is obtained via the environment.
 220 Additionally, if one or more OIDs are specified, the calculated
 221 keys are used when processing the SNMPv3 requests.
 222 .It Fl l Ar filename
 223 The path of the posix local (unix domain) socket if local
 224 transport is used.
 225 .It Fl M Ar max-repetitions
 226 The value for the max-repetitions field in a GetBulk PDU.
 227 Default is 10.
 228 .It Fl N Ar non-repeaters
 229 The value for the non-repeaters field in a GetBulk PDU.
 230 Default is 0.
 231 .It Fl n
 232 Only use numerical representations for input and output OIDs and do not
 233 try to resolve symbolic object names.
 234 Note that
 235 .Nm bsnmpget ,
 236 .Nm bsnmpwalk
 237 and
 238 .Nm bsnmpset
 239 will print numerical OIDs anyway if the corresponding string representation
 240 is not found in the MIB description files.
 241 .It Fl o Ar [quiet|short|verbose]
 242 The format used to print the received response.
 243 Quiet only prints values, short (default) prints an abbreviated OID
 244 representation and the value.
 245 In addition to the short output verbose prints the type before the value.
 246 .It Fl P Ar options
 247 Privacy options to use with SNMPv3 PDUs
 248 .Bl -tag -width \&
 249 .It Cm proto=[aes|des]
 250 The protocol to use when encrypting/decrypting SNMPv3 PDU data.
 251 .It Cm key=privkey
 252 A binary localized privacy key to use when encrypting/decrypting SNMPv3 PDU data.
 253 .El
 254 .Pp
 255 By default plain text SNMPv3 PDUs are sent.
 256 .It Fl p Ar [get|getnext|getbulk]
 257 The PDU type to send by
 258 .Nm bsmpget
 259 and
 260 .Nm bsnmpwalk .
 261 Default is get
 262 for
 263 .Nm bsmpget
 264 and getnext for
 265 .Nm bsnmpwalk .
 266 Getbulk allows executing the so called SNMP "bulkwalks" allowing the values of
 267 multiple columns to be retrieved in a single PDU by
 268 .Nm bsnmpwalk .
 269 .It Fl r Ar retries
 270 Number of resends of request packets before giving up if the agent does
 271 not respond after the first try.
 272 Default is 3.
 273 .It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port]
 274 Each of the server specification components is optional but at least one
 275 has to be provided if the
 276 .Ar s
 277 option is used.
 278 The server specification is constructed in the following manner:
 279 .Bl -tag -width \&
 280 .It Cm trans::
 281 Transport type may be one of udp, stream or dgram.
 282 If this option is not provided an UDP inet/inet6 socket will be used, which
 283 is the most common.
 284 Stream stands for a posix local stream socket and a posix local datagram
 285 socket will be used if dgram is specified.
 286 .It Cm community@
 287 Specify an SNMP community string to be used when sending packets.
 288 If the option is skipped the default "public" will be used for
 289 .Nm
 290 and
 291 .Nm bsnmpwalk
 292 and the default "private" community string will be used for
 293 .Nm bsnmpset .
 294 .It Cm server
 295 This might be either the IP address or the hostname where the agent is
 296 listening.
 297 The default is
 298 .Qq localhost .
 299 .It Cm port
 300 The destination port to send the requests to.
 301 This is useful if the SNMP agent listens on a non-default port.
 302 Default is given by the
 303 .Qq snmp
 304 entry in
 305 .Pa /etc/services ,
 306 port 161.
 307 .El
 308 .It Fl t Ar timeout
 309 Number of seconds before resending a request packet if the agent does
 310 not respond.
 311 The default value is 3 seconds.
 312 .It Fl U Ar options
 313 User credentials when sending SNMPv3 PDUs.
 314 .Bl -tag -width \&
 315 .It Cm engine=id
 316 The Engine ID of the SNMP agent represented as a binary octet string.
 317 .It Cm engine-boots=value
 318 The value of the snmpEngineBoots of the SNMP agent.
 319 .It Cm engine-time=value
 320 The value of the snmpEngineTime of the SNMP agent.
 321 .Pp
 322 If any of the above is not specified, SNMP USM Engine Discovery is attempted.
 323 This is also the default behavior.
 324 .It Cm name=username
 325 The USM user name to include in the SNMPv3 PDUs.
 326 By default, the user name is
 327 obtained via the environment.
 328 .El
 329 .It Fl v Ar version
 330 The SNMP protocol version to use when sending requests.
 331 SNMP versions 1, 2 and
 332 3 are supported.
 333 If no version option is provided
 334 .Nm bsnmpget ,
 335 .Nm bsnmpwalk
 336 and
 337 .Nm bsnmpset
 338 will use version 2.
 339 Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the
 340 version to 1 is incompatible with sending a GetBulk PDU.
 341 .It OID
 342 The object identifier whose value to retrieve.
 343 At least one OID should be provided for
 344 .Nm bsnmpget
 345 to be able to send a request.
 346 .Pp
 347 For
 348 .Nm bsnmpwalk
 349 this is the root object identifier of the subtree whose values are to be
 350 retrieved.
 351 If no OID is provided
 352 .Nm bsnmpwalk
 353 will walk the mib2 subtree rooted
 354 at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) .
 355 .Pp
 356 Any of the formats used to print a single variable
 357 is 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
 367 option)
 368 .El
 369 .Pp
 370 Square brackets are used to denote an entry's indexes.
 371 When used in an input OID, the square brackets may have to be
 372 escaped or the OID has to be quoted to protect it from the shell.
 373 Note there is no difference between ifName.1 and "ifName[1]".
 374 .It OID Ns = Ns Ar [syntax Ns :] Ns Ar value
 375 The object identifier with its syntax type and value that is to be set.
 376 At least one such string OID=[syntax:]value should be provided to
 377 .Nm bsnmpset
 378 to be able to send a request.
 379 .Bl -tag -width \&
 380 .It Cm OID
 381 OID 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
 383 if the
 384 .Ar n
 385 option is used - and in such case a syntax is required for every value,
 386 or a string followed by square brackets (used to denote an entry's indexes) and
 387 corresponding indexes.
 388 Any of the formats used to print a single variable by
 389 .Nm bsnmpset
 390 is 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
 401 option)
 402 .El
 403 .It Cm syntax
 404 where the syntax string is one of:
 405 Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64.
 406 .It Cm value
 407 The value to be set - IP address in form of u.u.u.u - for example
 408 1.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they
 409 contain any special characters or spaces, all other numeric types do not.
 410 .El
 411 .El
 412 .Sh ENVIRONMENT
 413 .Nm ,
 414 .Nm bsnmpwalk
 415 and
 416 .Nm bsnmpset
 417 use the following environment variables:
 418 .Bl -tag -width SNMPAUTH
 419 .It Ev SNMPAUTH
 420 Specifies a default SNMP USM authentication protocol.
 421 .It Ev SNMPPRIV
 422 Specifies a default SNMP USM privacy protocol.
 423 .It Ev SNMPUSER
 424 Specifies a default SNMP USM user name.
 425 .It Ev SNMPPASSWD
 426 Specifies the SNMP USM plain text password to use when calculating localized
 427 authentication and privacy keys.
 428 If this variable exists in the environment,
 429 SNMPv3 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