userapps/opensource/net-snmp/man/snmpcmd.1.def

   1 .\"/***********************************************************
   2 .\"     Copyright 1988, 1989 by Carnegie Mellon University
   3 .\"
   4 .\"                       All Rights Reserved
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software and its
   7 .\" documentation for any purpose and without fee is hereby granted,
   8 .\" provided that the above copyright notice appear in all copies and that
   9 .\" both that copyright notice and this permission notice appear in
  10 .\" supporting documentation, and that the name of CMU not be
  11 .\" used in advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\"
  14 .\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  15 .\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
  16 .\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  17 .\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  18 .\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  19 .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  20 .\" SOFTWARE.
  21 .\" ******************************************************************/
  22 .TH SNMPCMD 1 "07 Nov 2002" VVERSIONINFO "Net-SNMP"
  23 .UC 4
  24 .SH NAME
  25 snmpcmd - commands to communicate with a network entity using SNMP Requests.
  26 .SH SYNOPSIS
  27 .B snmpcmd
  28 [OPTIONS] AGENT [PARAMETERS]
  29 .SH DESCRIPTION
  30 This manual page describes the common options for the SNMP commands:
  31 .BR snmpbulkget ", " snmpbulkwalk ", "  snmpdelta ", " snmpget ", "
  32 .BR snmpgetnext ", " snmpnetstat ", " snmpset ", " snmpstatus ", "
  33 .BR snmptable ", " snmptest ", " snmptrap ", " snmpusm ", " snmpwalk ".  "
  34 The command line applications use the SNMP protocol to communicate
  35 with an SNMP capable network entity, an agent.  Individual
  36 applications typically (but not necessarily) take additional
  37 parameters that are given after the agent specification.  These
  38 parameters are documented in the manual pages for each application.
  39
  40 .SH OPTIONS
  41 .TP
  42 .BI -a " authProtocol"
  43 Set the authentication protocol (MD5|SHA) used for authenticated SNMPv3
  44 messages.
  45 .TP
  46 .BI -A " authPassword"
  47 Set the authentication pass phrase used for authenticated SNMPv3
  48 messages.
  49 .TP
  50 .BI -c " community"
  51 Set the community string for SNMPv1/v2c transactions.
  52 .TP
  53 .B -d
  54 Dump (in hexadecimal) the sent and received SNMP packets.
  55 .TP
  56 .B -D \fITOKEN[,...]
  57 Turn on debugging output for the given
  58 .IR "TOKEN" "(s)."
  59 Try
  60 .IR ALL
  61 for extremely verbose output.
  62 .TP
  63 .BI -e " engineID"
  64 Set the authoritative (security) engineID used for SNMPv3 REQUEST
  65 messages.  This is the engineID of the agent or proxy (e.g.,
  66 800000020109840301). (will be discovered if not supplied)
  67 .TP
  68 .BI -E " engineID"
  69 Set the context engineID used for SNMPv3 REQUEST messages scopedPdu.
  70 This is the engineID of the agent (e.g., 800000020109840301). (will be
  71 authoritative engineID if not specified)
  72 .TP
  73 .B -h
  74 Display a brief usage message and then exit.
  75 .TP
  76 .B -H
  77 Display a list of configuration file directives understood by the
  78 command and then exit.
  79 .TP
  80 .BI -I " brRh"
  81 Specifies input parsing options. See
  82 .B INPUT OPTIONS
  83 below.
  84 .TP
  85 .BI -l " secLevel"
  86 Set the securityLevel used for SNMPv3 messages
  87 (noAuthNoPriv|authNoPriv|authPriv).  Appropriate pass phrase(s) must
  88 provided when using any level higher than noAuthNoPriv.
  89 .TP
  90 .BI -m " MIBLIST"
  91 Specifies a colon separated list of MIB modules to load for this
  92 application.  This overrides the environment variable MIBS.
  93 .IP
  94 The special keyword
  95 .I ALL
  96 is used to specify all modules in all directories when searching for MIB
  97 files.  Every file whose name does not begin with "." will be parsed as
  98 if it were a MIB file.
  99 .TP
 100 .BI -M " DIRLIST"
 101 Specifies a colon separated list of directories to search for MIBs.
 102 This overrides the environment variable MIBDIRS.
 103 .TP
 104 .BI -n " contextName"
 105 Set the destination contextName used for SNMPv3 messages.  The default
 106 contextName is the empty string "".
 107 .TP
 108 .BI -O " nEebqQfsSvXT"
 109 Specifies output printing options. See
 110 .B OUTPUT OPTIONS
 111 below.
 112 .TP
 113 .BI -P " cdeRuwW"
 114 Specifies MIB parsing options.  See
 115 .B MIB PARSING OPTIONS
 116 below.
 117 .TP
 118 .BI -r " retries"
 119 Specifies the number of retries to be used in the requests. The default
 120 is 5.
 121 .TP
 122 .BI -t " timeout"
 123 Specifies the timeout in seconds between retries. The default is 1.
 124 .TP
 125 .BI -u " secName"
 126 Set the securityName used for authenticated SNMPv3 messages.
 127 .TP
 128 .B -v \fI1\fR | \fI2c\fR | \fI3
 129 Specifies the protocol version to use: 1 (RFCs 1155-1157), 2c (RFCs 1901-1908),
 130 or 3 (RFCs 2571-2574).  The default is version 1.
 131 .TP
 132 .B -V
 133 Display version information for the application and then exit.
 134 .TP
 135 .BI -x " privProtocol"
 136 Set the privacy protocol (DES) used for encrypted SNMPv3 messages.
 137 .TP
 138 .BI -X " privPassword"
 139 Set the privacy pass phrase used for encrypted SNMPv3 messages.
 140 .TP
 141 .BI -Z " boots,time"
 142 Set the engineBoots and engineTime used for authenticated SNMPv3
 143 messages.  This will initialize the local notion of the agents
 144 boots/time with an authenticated value stored in the LCD. (will be
 145 discovered if not supplied)
 146 .PP
 147 The string
 148 .I AGENT
 149 specifies the remote SNMP entity with which to communicate.  The format
 150 of this parameter is defined in the
 151 .B AGENT SPECIFICATION
 152 section below.
 153 .SH AGENT SPECIFICATION
 154 The
 155 .I AGENT
 156 specification takes the form:
 157 .IP
 158 [<transport-specifier>:]<transport-address>
 159 .PP
 160 At its simplest, the
 161 .I AGENT
 162 specification may consist of a hostname, or an IPv4 address in the
 163 standard "dotted quad" notation.  In this case, communication will be
 164 attempted using UDP/IPv4 to port 161 of the given host.  Otherwise,
 165 the <transport-address> part of the specification is parsed according
 166 to the following table:
 167 .RS 4
 168 .TP 28
 169 .BR "<transport-specifier>"
 170 .BR "<transport-address> format"
 171 .IP "udp" 28
 172 hostname[:port]
 173 .I or
 174 IPv4-address[:port]
 175 .IP "tcp" 28
 176 hostname[:port]
 177 .I or
 178 IPv4-address[:port]
 179 .IP "unix" 28
 180 pathname
 181 .IP "ipx" 28
 182 [network]:node[/port]
 183 .TP 28
 184 .IR "" "aal5pvc " or " pvc"
 185 [interface.][VPI.]VCI
 186 .IP "udp6 or udpv6 or udpipv6" 28
 187 hostname[:port]
 188 .I or
 189 IPv6-address:port
 190 .I or
 191  '['IPv6-address']'[:port]
 192 .IP "tcp6 or tcpv6 or tcpipv6"
 193 hostname[:port]
 194 .I or
 195 IPv6-address:port
 196 .I or
 197  '['IPv6-address']'[:port]
 198 .RE
 199 .PP
 200 Note that <transport-specifier> strings are case-insensitive so that,
 201 for example, "tcp" and "TCP" are equivalent.  Here are some examples,
 202 along with their interpretation:
 203 .TP 24
 204 .IR "hostname:161"
 205 perform query using UDP/IPv4 datagrams to
 206 .I hostname
 207 on port
 208 .IR 161 .
 209 The ":161" is redundant here since that is the default SNMP port in
 210 any case.
 211 .TP 24
 212 .IR "udp:hostname"
 213 identical to the previous specification.  The "udp:" is redundant here
 214 since UDP/IPv4 is the default transport.
 215 .TP 24
 216 .IR "TCP:hostname:1161"
 217 connect to
 218 .I hostname
 219 on port
 220 .I 1161
 221 using TCP/IPv4 and perform query over that connection.
 222 .TP 24
 223 .IR "ipx::00D0B7AAE308"
 224 perform query using IPX datagrams to node number
 225 .I 00D0B7AAE308
 226 on the default network, and using the default IPX port of 36879 (900F
 227 hexadecimal), as suggested in RFC 1906.
 228 .TP 24
 229 .IR "ipx:0AE43409:00D0B721C6C0/1161"
 230 perform query using IPX datagrams to port
 231 .I 1161
 232 on node number
 233 .I 00D0B721C6C0
 234 on network number
 235 .IR 0AE43409 .
 236 .TP 24
 237 .IR "unix:/tmp/local-agent"
 238 connect to the Unix domain socket
 239 .IR /tmp/local-agent ,
 240 and perform the query over that connection.
 241 .TP 24
 242 .IR "/tmp/local-agent"
 243 identical to the previous specification, since the Unix domain is the
 244 default transport iff the first character of the <transport-address>
 245 is a '/'.
 246 .TP 24
 247 .IR "AAL5PVC:100"
 248 perform the query using AAL5 PDUs sent on the permanent virtual
 249 circuit with VPI=0 and VCI=100 (decimal) on the first ATM adapter in the
 250 machine.
 251 .TP 24
 252 .IR "PVC:1.10.32"
 253 perform the query using AAL5 PDUs sent on the permanent virtual
 254 circuit with VPI=10 (decimal) and VCI=32 (decimal) on the second ATM
 255 adapter in the machine.  Note that "PVC" is a synonym for "AAL5PVC".
 256 .TP 24
 257 .IR "udp6:hostname:10161"
 258 perform the query using UDP/IPv6 datagrams to port
 259 .I 10161
 260 on
 261 .I hostname
 262 (which will be looked up as an AAAA record).
 263 .TP 24
 264 .IR "UDP6:[fe80::2d0:b7ff:fe21:c6c0]"
 265 perform the query using UDP/IPv6 datagrams to port 161 at address
 266 .IR fe80::2d0:b7ff:fe21:c6c0 .
 267 .TP 24
 268 .IR "tcpipv6:[::1]:1611"
 269 connect to port 1611 on the local host
 270 .IR "" ( ::1
 271 in IPv6 parlance) using TCP/IPv6 and perform query over that connection.
 272 .PP
 273 Note that not all the transport domains listed above will always be
 274 available; for instance, hosts with no IPv6 support will not be able
 275 to use udp6 transport addresses, and attempts to do so will result in
 276 the error "Unknown host".  Likewise, since AAL5 PVC support is only
 277 currently available on Linux, it will fail with the same error on
 278 other platforms.
 279 .SH "MIB PARSING OPTIONS"
 280 The Net-SNMP MIB parser mostly adheres to the Structure of Management
 281 Information (SMI).  As that specification has changed through time, and
 282 in recognition of the (ahem) diversity in compliance expressed in MIB
 283 files, additional options provide more flexibility in reading MIB files.
 284 .TP
 285 .B "-Pw"
 286 Show some warning messages in resolving the MIB files.
 287 Can be also set with the configuration token "mibWarningLevel".
 288 .TP
 289 .B "-PW"
 290 Show additional warning messages.
 291 Can be also set with the configuration token "mibWarningLevel".
 292 .TP
 293 .B "-Pe"
 294 Do not show MIB errors.
 295 Can be also set with the configuration token "showMibErrors".
 296 .TP
 297 .B "-Pc"
 298 Allow ASN.1 comment to extend to the end of the MIB source line.
 299 This overcomes some problems with manually maintained MIB files.
 300 Can be also set with the configuration token "strictCommentTerm".
 301 .TP
 302 .B "-Pd"
 303 Collect the DESCRIPTION information into the parsed hierarchy.
 304 This increases the memory used by the size of each DESCRIPTION clause.
 305 .TP
 306 .B "-Pu"
 307 Allow underline characters in symbols.
 308 Can be also set with the configuration token "mibAllowUnderline".
 309 .TP
 310 .B "-PR"
 311 Replace MIB objects using the last read MIB file.
 312 .B WARNING:
 313 Setting this option may result in an incorrect hierarchy.
 314 Can be also set with the configuration token "mibReplaceWithLatest".
 315 .PP
 316 .SH "OUTPUT OPTIONS"
 317 Output display can be controlled by passing various parameters to the
 318 .B -O
 319 flag.  The following examples should demonstrate this.
 320 .PP
 321 The default output looks as follows:
 322 .br
 323 snmpget -c public -v 1 localhost system.sysUpTime.0
 324 .br
 325 SNMPv2-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63
 326 .TP
 327 .B -Oq
 328 Removes the equal sign and type information:
 329 .br
 330 system.sysUpTime.0 1:15:09:27.63
 331 .TP
 332 .TP
 333 .B -OQ
 334 Removes the equal sign and type information:
 335 .br
 336 system.sysUpTime.0 = 1:15:09:27.63
 337 .TP
 338 .B -Of
 339 Gives you the complete OID:
 340 .br
 341  .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63
 342 .TP
 343 .B -Os
 344 Deletes all but the last symbolic part of the OID:
 345 .br
 346 sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63
 347 .TP
 348 .B -OS
 349 A variation on
 350 .B -Os
 351 that adds the name of the MIB that defined the object:
 352 .br
 353 SNMPv2-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63
 354 .br
 355 (from release 5.0, this is now the default output format)
 356 .TP
 357 .B -Ou
 358 Prints the OID in the UCD-style (inherited from the original CMU code)
 359 removing a series of "standard" prefixes (if relevant).
 360 .br
 361 system.sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63
 362 .TP
 363 .B -On
 364 Prints the OID numerically:
 365 .br
 366  .1.3.6.1.2.1.1.3.0 = Timeticks: (14096763) 1 day, 15:09:27.63
 367 .TP
 368 .B -Oe
 369 Removes the symbolic labels from enumerations:
 370 .br
 371 snmpget -c public -v 1 localhost ip.ipForwarding.0
 372 .br
 373 ip.ipForwarding.0 = INTEGER: forwarding(1)
 374 .br
 375 snmpget -c public -v 1 -Oe localhost ip.ipForwarding.0
 376 .br
 377 ip.ipForwarding.0 = INTEGER: 1
 378 .TP
 379 .B -Ob
 380 When OIDs contain a index to a table,
 381 they are broken into the displayable pieces and shown to you.  For
 382 example the OID vacmSecurityModel.0.3.119.101.115 is nicely broken
 383 down by default and the string hidden in the OID is shown to you as
 384 vacmSecurityModel.0."wes".
 385 The
 386 .B -Ob
 387 option disables this feature and displays it as
 388 vacmSecurityModel.0.3.119.101.115 again.
 389 .TP
 390 .B -OE
 391 This modifies the index strings to include a \\ to escape the quotes,
 392 to allow them to be reused in shell commands, such as
 393 vacmSecurityModel.0.\\"wes\\"
 394 .TP
 395 .B -OX
 396 This modifies the output of index OIDs, to look more "program like".
 397 If you take an entry from the IPV6-MIB::ipv6RouteTable, it is indexed with
 398 an IPv6 address and two integers, and if you are used to IPv6 addresses
 399 you will know that decimal OIDs are not the preferred notation. Compare:
 400 .br
 401 snmpgetnext -OS host IPV6-MIB:ipv6RouteTable
 402 .br
 403 IPV6-MIB::ipv6RouteIfIndex.63.254.1.0.255.0.0.0.0.0.0.0.0.0.0.0.64.1 = INTEGER: 2
 404 .br
 405 snmpgetnext -OSX host IPV6-MIB:ipv6RouteTable
 406 .br
 407 IPV6-MIB::ipv6RouteIfIndex[3ffe:100:ff00:0:0:0:0:0][64][1] = INTEGER: 2
 408 .TP
 409 .B -Oa
 410 If a string-valued object definition does not include a Display Hint,
 411 then the library attempts to determine whether it is an ascii or
 412 binary string, and displays the value accordingly.
 413 This flag bypasses this check, and displays all strings as ASCII.
 414 Note that this does not affect objects that do have a Display Hint.
 415 .TP
 416 .B -Ox
 417 This works similarly to '-Oa', but displays strings as Hex.
 418 .TP
 419 .B -OT
 420 If hexadecimal code is printed, this will also print any printable
 421 characters after the hexadecimal codes.
 422 .TP
 423 .B -Ov
 424 Output only the variable value, not the OID:
 425 .br
 426 snmpget -c public -v 1 -Ov localhost ip.ipForwarding.0
 427 .br
 428 INTEGER: forwarding(1)
 429 .TP
 430 .B -OU
 431 Don't print the UNITS suffix at the end of the value.
 432 .TP
 433 .B -Ot
 434 Output timeticks values as raw numbers:
 435 .br
 436 system.sysUpTime.0 = 14096763
 437 .PP
 438 Note that most of these options can be turned on or off by default by
 439 tuning the snmp.conf file.  See the
 440 .I snmp.conf(5)
 441 manual page for details.
 442 .SH "INPUT OPTIONS"
 443 The
 444 .B -I
 445 flag specifies various options that control how your input to
 446 the program is parsed.  By default, all input parsing methods are
 447 used: First the OID is parsed regularly, then
 448 .B -IR
 449 is used, then
 450 .B -Ib
 451 is used, unless one of the following flags is specified which will
 452 force it to only use one method.
 453 .TP
 454 .B -IR
 455 The
 456 .B -IR
 457 flag specifies random access lookup, so that if the entire OID path is
 458 not specified, it will search for a node in the MIB tree with the given
 459 name.  Normally, you'd have to specify the vacmSecurityModel OID above
 460 as .iso.org.dod.internet.snmpV2.snmpModules.snmpVacmMIB.vacmMIBObjects.vacmSecurityToGroupTable.vacmSecurityToGroupEntry.vacmSecurityModel.0."wes",
 461 but the use of the
 462 .B -IR
 463 flag allows you to shorten that to just vacmSecurityModel.0."wes".
 464 (Though this OID really needs to be quoted - 'vacmSecurityModel.0."wes"' - to
 465 prevent the shell from swallowing the double quotes).
 466 .IP
 467 Additionally, see the
 468 .B RANDOM ACCESS MIBS
 469 section below.
 470 .TP
 471 .B -Ib
 472 The
 473 .B -Ib
 474 flag indicates that the expression you gave it is actually a regular
 475 expression that should be used to search for the best match possible in
 476 the MIB tree.  This would allow you to specify the node
 477 vacmSecurityModel MIB node as something as generic as vacmsecuritymodel
 478 (since case insensitive searches are done) or vacm.*model.  Note that
 479 multiple matches are obviously possible (.* matches everything), and the
 480 best result is currently calculated as the one that matches the closest
 481 to the beginning of the node name and the highest in the tree.  A
 482 current side effect of this option is that you can't specify indexes or
 483 multiple nodes, since the '.' is treated as part of the regular
 484 expression.
 485 .TP
 486 .B -Iu
 487 Use the traditional UCD-style input approach of assuming that OIDs
 488 are rooted at the 'mib-2' point in the tree (unless they start with
 489 an explicit '.')   If random access lookup is in effect (which is
 490 the default for most commands), then this will only affect OIDs
 491 specified with a leading numberic subidentifier (and no initial '.')
 492 Thus an input of "snmpcmd ... 1" would refer to 'iso' (from v5.0
 493 onwards) while "snmpcmd -Iu ... 1" would refer to 'system'.
 494 .TP
 495 .B -Ir
 496 By default, indices into tables and values to be assigned to objects
 497 are checked against range and type specified in the MIB.  The
 498 .B -Ir
 499 flag disables this check.  This flag is mostly useful when you are
 500 testing an agent.  For normal operation it is useful to get your
 501 requests checked before they are sent to the remote agent (the
 502 diagnostic that the library can provide is also much more precise).
 503 .TP
 504 .B -Ih
 505 By default, the library will use DISPLAY-HINT information when assigning values.
 506 This flag disables this behaviour. The result is that in stead of
 507 .br
 508 snmpset localhost HOST-RESOURCES-MIB::hrSystemDate.0 = 2002-12-10,2:4:6.8
 509 .br
 510 you will have to write
 511 .br
 512 snmpset localhost HOST-RESOURCES-MIB::hrSystemData.0 x "07 D2 0C 0A 02 04 06 08"
 513 .SH "RANDOM ACCESS MIBS"
 514 In previous releases of the UCD-SNMP package (and if using the
 515 .B -Iu
 516 option), an object identifier such as system.sysDescr.0 will be
 517 lookup in a single "well known" place, built into the SNMP library (or
 518 specified by the P@REFIX environment variable).  The standard place
 519 is: .iso.org.dod.internet.mgmt.mib-2.  The identifier may alternatively be
 520 a complete object identifier, this is designated by a leading "dot"
 521 if using UCD-input style, and is the first thing tried otherwise.
 522 To simplify the specification of object identifiers the library
 523 supports random access to the identifiers in the MIBs. This is
 524 requested by the
 525 .B -IR
 526 option to the SNMP applications.  Additionally,
 527 .B -Os
 528 prints OIDs in this manner.  Using this, system.sysDescr.0 may
 529 also be entered as sysDescr.0.  To search only a single MIB for the
 530 identifier (if it appears in more than one), specify it as
 531 SNMPv2-MIB::sysDescr.0. (use
 532 .B -OS
 533 to print output OIDs in this manner, though this is the default as
 534 from v5.0). This notation will also ensure
 535 that the specified MIB is loaded, i.e. it need not be mentioned in the
 536 .B -m
 537 option (or MIBS environment variable).
 538 .SH "ENVIRONMENT VARIABLES"
 539 .IP P@REFIX
 540 The standard prefix for object identifiers (if using UCD-style output).
 541 Defaults to .iso.org.dod.internet.mgmt.mib-2
 542 .IP MIBS
 543 The list of MIBs to load. Defaults to
 544 SNMPv2-TC:SNMPv2-MIB:IF-MIB:IP-MIB:TCP-MIB:UDP-MIB:SNMP-VACM-MIB.
 545 Overridden by the
 546 .B -m
 547 option.
 548 .IP MIBDIRS
 549 The list of directories to search for MIBs. Defaults to DATADIR/snmp/mibs.
 550 Overridden by the
 551 .B -M
 552 option.
 553 .SH FILES
 554 .IP SYSCONFDIR/snmp/snmpd.conf
 555 Agent configuration file. See
 556 .IR snmpd.conf(5) .
 557 .IP SYSCONFDIR/snmp/snmp.conf
 558 .IP ~/.snmp/snmp.conf
 559 Application configuration files. See
 560 .IR snmp.conf(5) .
 561 .SH "SEE ALSO"
 562 snmpget(1), snmpgetnext(1), snmpset(1),
 563 snmpbulkget(1), snmpbulkwalk(1), snmpwalk(1),
 564 snmptable(1), snmpnetstat(1), snmpdelta(1), snmptrap(1), snmpinform(1),
 565 snmpusm(1), snmpstatus(1), snmptest(1),
 566 snmp.conf(5).
 567