Provided by: snmp_5.4.3~dfsg-2.2ubuntu1_i386 bug

NAME

       snmpcmd - options and behaviour common to most of the Net-SNMP command-
       line tools

SYNOPSIS

       snmpcmd [OPTIONS] AGENT [PARAMETERS]

DESCRIPTION

       This manual page describes the common options for  the  SNMP  commands:
       snmpbulkget,    snmpbulkwalk,    snmpdelta,    snmpget,    snmpgetnext,
       snmpnetstat,  snmpset,  snmpstatus,  snmptable,  snmptest,  snmptrap,
       snmpdf,  snmpusm  ,  snmpwalk  .  The command line applications use the
       SNMP protocol to communicate with an SNMP capable  network  entity,  an
       agent.   Individual  applications  typically (but not necessarily) take
       additional parameters that are given  after  the  agent  specification.
       These   parameters   are  documented  in  the  manual  pages  for  each
       application.

OPTIONS

       -3[MmKk]  0xHEXKEY
              Sets the keys to be used for SNMPv3 transactions.  These options
              allow  you  to set the master authentication and encryption keys
              (-3m and -3M respectively) or set the  localized  authentication
              and encryption keys (-3k and -3K respectively).  SNMPv3 keys can
              be either passed in by hand using these flags, or by the use  of
              keys  generated  from  passwords  using  the  -A  and  -X  flags
              discussed below.  For further details on SNMPv3 and its usage of
              keying  information,  see  the  Net-SNMP  tutorial  web  site  (
              http://www.Net-SNMP.org/tutorial-5/commands/ ).   Overrides  the
              defAuthMasterKey       (-3m),       defPrivMasterKey      (-3M),
              defAuthLocalizedKey (-3k) or defPrivLocalizedKey  (-3K)  tokens,
              respectively, in the snmp.conf file, see snmp.conf(5).

       -a authProtocol
              Set   the   authentication   protocol  (MD5  or  SHA)  used  for
              authenticated SNMPv3 messages. Overrides the  defAuthType  token
              in the snmp.conf file.

       -A authPassword
              Set the authentication pass phrase used for authenticated SNMPv3
              messages.   Overrides  the  defAuthPassphrase   token   in   the
              snmp.conf  file.  It  is insecure to specify pass phrases on the
              command line, see snmp.conf(5).

       -c community
              Set the community string for SNMPv1/v2c transactions.  Overrides
              the defCommunity token in the snmp.conf file.

       -d     Dump (in hexadecimal) the raw SNMP packets sent and received.

       -D TOKEN[,...]
              Turn  on  debugging  output for the given TOKEN(s).  Try ALL for
              extremely verbose output.

       -e engineID
              Set  the  authoritative  (security)  engineID  used  for  SNMPv3
              REQUEST  messages,  given  as  a  hexadecimal string (optionally
              prefixed by "0x").  It is typically  not  necessary  to  specify
              this engine ID, as it will usually be discovered automatically.

       -E engineID
              Set  the  context  engineID  used  for  SNMPv3  REQUEST messages
              scopedPdu, given as a hexadecimal  string.   If  not  specified,
              this will default to the authoritative engineID.

       -h, --help
              Display a brief usage message and then exit.

       -H     Display  a  list  of configuration file directives understood by
              the command and then exit.

       -I [brRhu]
              Specifies input parsing options. See INPUT OPTIONS below.

       -l secLevel
              Set    the    securityLevel    used    for    SNMPv3    messages
              (noAuthNoPriv|authNoPriv|authPriv).   Appropriate pass phrase(s)
              must provided when using any  level  higher  than  noAuthNoPriv.
              Overrides the defSecurityLevel token in the snmp.conf file.

       -L [eEfFoOsS]
              Specifies output logging options. See LOGGING OPTIONS below.

       -m MIBLIST
              Specifies  a  colon separated list of MIB modules (not files) to
              load for this application.  This  overrides  (or  augments)  the
              environment variable MIBS, the snmp.conf directive mibs, and the
              list of MIBs hardcoded into the Net-SNMP library.

              If MIBLIST has a leading '-' or  '+'  character,  then  the  MIB
              modules  listed  are  loaded  in  addition  to the default list,
              coming before or after this list respectively.   Otherwise,  the
              specified MIBs are loaded instead of this default list.

              The  special  keyword ALL is used to load all MIB modules in the
              MIB directory search list.  Every file whose name does not begin
              with "." will be parsed as if it were a MIB file.

       -M DIRLIST
              Specifies  a  colon  separated list of directories to search for
              MIBs.  This overrides (or  augments)  the  environment  variable
              MIBDIRS,  the  snmp.conf  directive  mibdirs,  and  the  default
              directory    hardcoded     into     the     Net-SNMP     library
              (/usr/share/snmp/mibs).

              If  DIRLIST  has  a leading '-' or '+' character, then the given
              directories are added to the default list, being searched before
              or  after the directories on this list respectively.  Otherwise,
              the specified directories are searched instead of  this  default
              list.

              Note  that the directories appearing later in the list have have
              precedence over  earlier  ones.   To  avoid  searching  any  MIB
              directories,  set  the MIBDIRS environment variable to the empty
              string ("").

              Note that MIBs  specified  using  the  -m  option  or  the  mibs
              configuration   directive   will  be  loaded  from  one  of  the
              directories listed by  the  -M  option  (or  equivalents).   The
              mibfile  directive  takes a full path to the specified MIB file,
              so this does not need to be in the MIB directory search list.

       -n contextName
              Set the contextName  used  for  SNMPv3  messages.   The  default
              contextName  is  the  empty string "".  Overrides the defContext
              token in the snmp.conf file.

       -O [abeEfnqQsStTuUvxX]
              Specifies output printing options. See OUTPUT OPTIONS below.

       -P [cdeRuwW]
              Specifies MIB parsing options.  See MIB PARSING OPTIONS below.

       -r retries
              Specifies the number of retries to be used in the requests.  The
              default is 5.

       -t timeout
              Specifies the timeout in seconds between retries. The default is
              1.

       -u secName
              Set the securityName used  for  authenticated  SNMPv3  messages.
              Overrides the defSecurityName token in the snmp.conf file.

       -v 1 | 2c | 3
              Specifies  the  protocol  version to use: 1 (RFCs 1155-1157), 2c
              (RFCs  1901-1908),  or  3  (RFCs  2571-2574).   The  default  is
              typically  version  3.   Overrides  the  defVersion token in the
              snmp.conf file.

       -V, --version
              Display version information for the application and then exit.

       -x privProtocol
              Set the privacy protocol (DES or AES) used for encrypted  SNMPv3
              messages.   Overrides  the  defPrivType  token  in the snmp.conf
              file. This option is only valid if  the  Net-SNMP  software  was
              build to use OpenSSL.

       -X privPassword
              Set  the privacy pass phrase used for encrypted SNMPv3 messages.
              Overrides the defPrivPassphrase token in the snmp.conf file.  It
              is  insecure  to  specify  pass phrases on the command line, see
              snmp.conf(5).

       -Z boots,time
              Set the engineBoots and engineTime used for authenticated SNMPv3
              messages.   This  will initialize the local notion of the agents
              boots/time with an authenticated value stored in the LCD.  It is
              typically  not necessary to specify this option, as these values
              will usually be discovered automatically.

       -Yname="value"

       --name="value"
              Allows to specify any token ("name") supported in the  snmp.conf
              file  and sets its value to "value". Overrides the corresponding
              token in the snmp.conf file. See snmp.conf(5) for the full  list
              of tokens.

AGENT SPECIFICATION

       The string AGENT in the SYNOPSIS above specifies the remote SNMP entity
       with which to communicate.  This specification takes the form:

              [<transport-specifier>:]<transport-address>

       At its simplest, the AGENT specification may consist of a hostname,  or
       an  IPv4 address in the standard "dotted quad" notation.  In this case,
       communication will be attempted using UDP/IPv4 to port 161 of the given
       host.   Otherwise, the <transport-address> part of the specification is
       parsed according to the following table:

           <transport-specifier>       <transport-address> format

           udp                         hostname[:port] or IPv4-address[:port]

           tcp                         hostname[:port] or IPv4-address[:port]

           unix                        pathname

           ipx                         [network]:node[/port]

           aal5pvc or pvc              [interface.][VPI.]VCI

           udp6 or udpv6 or udpipv6    hostname[:port] or IPv6-address:port or
                                        '['IPv6-address']'[:port]

           tcp6 or tcpv6 or tcpipv6    hostname[:port] or IPv6-address:port or
                                        '['IPv6-address']'[:port]

       Note that <transport-specifier> strings are case-insensitive  so  that,
       for  example,  "tcp" and "TCP" are equivalent.  Here are some examples,
       along with their interpretation:

       hostname:161            perform  query  using  UDP/IPv4  datagrams   to
                               hostname  on port 161.  The ":161" is redundant
                               here since that is the default SNMP port in any
                               case.

       udp:hostname            identical  to  the previous specification.  The
                               "udp:" is redundant here since UDP/IPv4 is  the
                               default transport.

       TCP:hostname:1161       connect to hostname on port 1161 using TCP/IPv4
                               and perform query over that connection.

       ipx::00D0B7AAE308       perform  query  using  IPX  datagrams  to  node
                               number 00D0B7AAE308 on the default network, and
                               using the  default  IPX  port  of  36879  (900F
                               hexadecimal), as suggested in RFC 1906.

       ipx:0AE43409:00D0B721C6C0/1161
                               perform  query using IPX datagrams to port 1161
                               on node number 00D0B721C6C0 on  network  number
                               0AE43409.

       unix:/tmp/local-agent   connect  to  the Unix domain socket /tmp/local-
                               agent,  and  perform  the   query   over   that
                               connection.

       /tmp/local-agent        identical  to the previous specification, since
                               the Unix domain is the  default  transport  iff
                               the  first character of the <transport-address>
                               is a '/'.

       AAL5PVC:100             perform the query using AAL5 PDUs sent  on  the
                               permanent   virtual   circuit  with  VPI=0  and
                               VCI=100 (decimal) on the first ATM  adapter  in
                               the machine.

       PVC:1.10.32             perform  the  query using AAL5 PDUs sent on the
                               permanent virtual circuit with VPI=10 (decimal)
                               and  VCI=32 (decimal) on the second ATM adapter
                               in the machine.  Note that "PVC" is  a  synonym
                               for "AAL5PVC".

       udp6:hostname:10161     perform  the  query using UDP/IPv6 datagrams to
                               port 10161 on hostname (which will be looked up
                               as an AAAA record).

       UDP6:[fe80::2d0:b7ff:fe21:c6c0]
                               perform  the  query using UDP/IPv6 datagrams to
                               port 161 at address fe80::2d0:b7ff:fe21:c6c0.

       tcpipv6:[::1]:1611      connect to port 1611 on the local host (::1  in
                               IPv6 parlance) using TCP/IPv6 and perform query
                               over that connection.

       Note that not all the transport domains listed  above  will  always  be
       available; for instance, hosts with no IPv6 support will not be able to
       use udp6 transport addresses, and attempts to do so will result in  the
       error  "Unknown  host".   Likewise,  since  AAL5  PVC  support  is only
       currently available on Linux, it will fail with the same error on other
       platforms.

MIB PARSING OPTIONS

       The  Net-SNMP  MIB parser mostly adheres to the Structure of Management
       Information (SMI).  As that specification has changed through time, and
       in  recognition  of the (ahem) diversity in compliance expressed in MIB
       files, additional options  provide  more  flexibility  in  reading  MIB
       files.

       -Pc    Toggles  whether  ASN.1 comments should extend to the end of the
              MIB source line.  Strictly speaking, a second appearance of "--"
              should  terminate  the  comment, but this breaks some MIB files.
              The default behaviour (to interpret comments correctly) can also
              be    set    with    the    (misnamed)    configuration    token
              strictCommentTerm.

       -Pd    Disables the loading of MIB object DESCRIPTIONs when parsing MIB
              files.   This  reduces  the amount of memory used by the running
              application.

       -Pe    Toggles whether to show  errors  encountered  when  parsing  MIB
              files.   These  include  references  to IMPORTed modules and MIB
              objects that cannot be located in the MIB directory search list.
              The  default  behaviour  can  also be set with the configuration
              token showMibErrors.

       -PR    If the same MIB object (parent name and sub-identifier)  appears
              multiple  times  in  the list of MIB definitions loaded, use the
              last version to be read in.  By default, the first version  will
              be  used, and any duplicates discarded.  This behaviour can also
              be set with the configuration token mibReplaceWithLatest.

              Such ordering is normally only relevant if  there  are  two  MIB
              files  with  conflicting object definitions for the same OID (or
              different revisions of the same basic MIB object).

       -Pu    Toggles whether to allow the underline character in  MIB  object
              names  and  other symbols.  Strictly speaking, this is not valid
              SMI syntax, but some vendor MIB files define  such  names.   The
              default  behaviour  can also be set with the configuration token
              mibAllowUnderline.

       -Pw    Show various warning messages in parsing MIB files and  building
              the   overall   OID  tree.   This  can  also  be  set  with  the
              configuration directive mibWarningLevel 1

       -PW    Show  some  additional  warning  messages,  mostly  relating  to
              parsing  individual  MIB objects.  This can also be set with the
              configuration directive mibWarningLevel 2

OUTPUT OPTIONS

       The format of the output from SNMP commands  can  be  controlled  using
       various  parameters  of  the -O flag.  The effects of these sub-options
       can be seen by comparison with the  following  default  output  (unless
       otherwise specified):
              $ snmpget -c public -v 1 localhost sysUpTime.0
              SNMPv2-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

       -Oa    Display  string  values  as  ASCII  strings  (unless  there is a
              DISPLAY-HINT defined for  the  corresponding  MIB  object).   By
              default,  the library attempts to determine whether the value is
              a printable or binary string, and displays it accordingly.

              This option does not affect objects that do have a Display Hint.

       -Ob    Display  table  indexes  numerically,  rather  than  trying   to
              interpret the instance subidentifiers as string or OID values:
                  $ snmpgetnext -c public -v 1 localhost vacmSecurityModel
                  SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0."wes" = xxx
                  $ snmpgetnext -c public -v 1 -Ob localhost vacmSecurityModel
                  SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0.3.119.101.115 = xxx

       -Oe    Removes the symbolic labels from enumeration values:
                  $ snmpget -c public -v 1 localhost ipForwarding.0
                  IP-MIB::ipForwarding.0 = INTEGER: forwarding(1)
                  $ snmpget -c public -v 1 -Oe localhost ipForwarding.0
                  IP-MIB::ipForwarding.0 = INTEGER: 1

       -OE    Modifies index strings to escape the quote characters:
                  $ snmpgetnext -c public -v 1 localhost vacmSecurityModel
                  SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0."wes" = xxx
                  $ snmpgetnext -c public -v 1 -OE localhost vacmSecurityModel
                  SNMP-VIEW-BASED-ACM-MIB::vacmSecurityModel.0.\"wes\" = xxx

              This allows the output to be reused in shell commands.

       -Of    Include the full list of MIB objects when displaying an OID:
                  .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.0 =
                             Timeticks: (14096763) 1 day, 15:09:27.63

       -On    Displays the OID numerically:
                  .1.3.6.1.2.1.1.3.0    =   Timeticks:   (14096763)   1   day,
              15:09:27.63

       -Oq    Removes the equal sign  and  type  information  when  displaying
              varbind values:
                  SNMPv2-MIB::sysUpTime.0 1:15:09:27.63

       -OQ    Removes the type information when displaying varbind values:
                  SNMPv2-MIB::sysUpTime.0 = 1:15:09:27.63

       -Os    Display  the  MIB  object  name  (plus  any  instance  or  other
              subidentifiers):
                  sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

       -OS    Display the name of the MIB, as well as the object name:
                  SNMPv2-MIB::sysUpTime.0  =  Timeticks:  (14096763)  1   day,
              15:09:27.63

              This is the default OID output format.

       -Ot    Display TimeTicks values as raw numbers:
                  SNMPv2-MIB::sysUpTime.0 = 14096763

       -OT    If  values  are  printed  as  Hex  strings,  display a printable
              version as well.

       -Ou    Display the OID in the traditional UCD-style (inherited from the
              original  CMU code).  That means removing a series of "standard"
              prefixes from the OID, and displaying the remaining list of  MIB
              object names (plus any other subidentifiers):
                  system.sysUpTime.0    =   Timeticks:   (14096763)   1   day,
              15:09:27.63

       -OU    Do not print the UNITS suffix at the end of the value.

       -Ov    Display the varbind value only, not the OID:
                  $ snmpget -c public -v 1 -Ov localhost ipForwarding.0
                  INTEGER: forwarding(1)

       -Ox    Display string values as Hex strings (unless there is a DISPLAY-
              HINT defined for the corresponding MIB object).  By default, the
              library attempts to determine whether the value is  a  printable
              or binary string, and displays it accordingly.

              This option does not affect objects that do have a Display Hint.

       -OX    Display table indexes in a more "program like" output, imitating
              a traditional array-style index format:
                  $ snmpgetnext -c public -v 1 localhost ipv6RouteTable
                  IPv6-MIB::ipv6RouteIfIndex.63.254.1.0.255.0.0.0.0.0.0.0.0.0.0.0.64.1 = INTEGER: 2
                  $ snmpgetnext -c public -v 1 -OX localhost ipv6RouteTable
                  IPv6-MIB::ipv6RouteIfIndex[3ffe:100:ff00:0:0:0:0:0][64][1] = INTEGER: 2

       Most of these options can also be configured via configuration  tokens.
       See the snmp.conf(5) manual page for details.

LOGGING OPTIONS

       The  mechanism  and destination to use for logging of warning and error
       messages can be controlled by passing  various  parameters  to  the  -L
       flag.

       -Le    Log messages to the standard error stream.

       -Lf FILE
              Log messages to the specified file.

       -Lo    Log messages to the standard output stream.

       -Ls FACILITY
              Log  messages  via syslog, using the specified facility ('d' for
              LOG_DAEMON, 'u' for LOG_USER, or '0'-'7' for LOG_LOCAL0  through
              LOG_LOCAL7).

       There  are  also  "upper case" versions of each of these options, which
       allow the corresponding logging mechanism to be restricted  to  certain
       priorities of message.  Using standard error logging as an example:

       -LE pri
              will log messages of priority 'pri' and above to standard error.

       -LE p1-p2
              will   log   messages   with  priority  between  'p1'  and  'p2'
              (inclusive) to standard error.

       For -LF and -LS the priority specification comes  before  the  file  or
       facility token.  The priorities recognised are:

              0 or !  for LOG_EMERG,
              1 or a for LOG_ALERT,
              2 or c for LOG_CRIT,
              3 or e for LOG_ERR,
              4 or w for LOG_WARNING,
              5 or n for LOG_NOTICE,
              6 or i for LOG_INFO, and
              7 or d for LOG_DEBUG.

       Normal output is (or will be!) logged at a priority level of LOG_NOTICE

INPUT OPTIONS

       The  interpretation of input object names and the values to be assigned
       can be controlled using various parameters of the -I flag.  The default
       behaviour will be described at the end of this section.

       -Ib    specifies  that  the  given name should be regarded as a regular
              expression, to match (case-insensitively) against  object  names
              in  the MIB tree.  The "best" match will be used - calculated as
              the one that matches the closest to the beginning  of  the  node
              name  and  the highest in the tree.  For example, the MIB object
              vacmSecurityModel   could   be   matched   by   the   expression
              vacmsecuritymodel   (full   name,   but   different   case),  or
              vacm.*model (regexp pattern).

              Note that '.' is  a  special  character  in  regular  expression
              patterns,    so   the   expression   cannot   specify   instance
              subidentifiers or more than one object  name.   A  "best  match"
              expression will only be applied against single MIB object names.
              For example, the expression sys*ontact.0  would  not  match  the
              instance   sysContact.0   (although   sys*ontact   would   match
              sysContact).  Similarly, specifying a MIB module name  will  not
              succeed (so SNMPv2-MIB::sys.*ontact would not match either).

       -Ih    disables  the  use  of  DISPLAY-HINT  information when assigning
              values.  This would then require providing the raw value:
                  snmpset ... HOST-RESOURCES-MIB::hrSystemDate.0
                                  x "07 D2 0C 0A 02 04 06 08"
              instead of a formatted version:
                  snmpset ... HOST-RESOURCES-MIB::hrSystemDate.0
                                  = 2002-12-10,2:4:6.8

       -Ir    disables checking table indexes and the  value  to  be  assigned
              against  the  relevant  MIB  definitions.  This will (hopefully)
              result in the remote agent reporting an invalid request,  rather
              than  checking  (and  rejecting)  this  before it is sent to the
              remote agent.

              Local checks are more efficient (and  the  diagnostics  provided
              also  tend  to be more precise), but disabling this behaviour is
              particularly useful when testing the remote agent.

       -IR    enables "random  access"  lookup  of  MIB  names.   Rather  than
              providing  a  full  OID  path  to  the  desired  MIB  object (or
              qualifying this object with an explicit MIB  module  name),  the
              MIB  tree  will  be searched for the matching object name.  Thus
              .iso.org.dod.internet.mib-2.system.sysDescr.0                (or
              SNMPv2-MIB::sysDescr.0) can be specified simply as sysDescr.0.

              Warning:
                     Since  MIB  object  names  are  not globally unique, this
                     approach may return a different MIB object  depending  on
                     which MIB files have been loaded.

              The  MIB-MODULE::objectName syntax has the advantage of uniquely
              identifying a particular MIB object, as well as  being  slightly
              more efficient (and automatically loading the necessary MIB file
              if necessary).

       -Is SUFFIX
              adds the specified suffix to  each  textual  OID  given  on  the
              command  line.   This  can  be used to retrieve multiple objects
              from the same row of a  table,  by  specifying  a  common  index
              value.

       -IS PREFIX
              adds  the  specified  prefix  to  each  textual OID given on the
              command line.  This can be  used  to  specify  an  explicit  MIB
              module  name  for  all objects being retrieved (or for incurably
              lazy typists).

       -Iu    enables the traditional UCD-style approach to interpreting input
              OIDs.  This assumes that OIDs are rooted at the 'mib-2' point in
              the tree (unless they start with an explicit '.'  or  include  a
              MIB  module  name).   So  the  sysDescr  instance above would be
              referenced as system.sysDescr.0.

       Object names specified with a leading '.'  are  always  interpreted  as
       "fully  qualified"  OIDs,  listing the sequence of MIB objects from the
       root of the MIB tree.  Such objects and those qualified by an  explicit
       MIB module name are unaffected by the -Ib, -IR and -Iu flags.

       Otherwise,  if  none  of  the  above  input  options are specified, the
       default behaviour for a "relative" OID is to try and interpret it as an
       (implicitly)  fully  qualified  OID,  then apply "random access" lookup
       (-IR), followed by "best match" pattern matching (-Ib).

ENVIRONMENT VARIABLES

       PREFIX The standard prefix for object identifiers (when using UCD-style
              output).  Defaults to .iso.org.dod.internet.mgmt.mib-2

       MIBS   The  list  of MIBs to load. Defaults to SNMPv2-TC:SNMPv2-MIB:IF-
              MIB:IP-MIB:TCP-MIB:UDP-MIB:SNMP-VACM-MIB.  Overridden by the  -m
              option.

       MIBDIRS
              The  list  of  directories  to  search  for  MIBs.  Defaults  to
              /usr/share/snmp/mibs.  Overridden by the -M option.

FILES

       /etc/snmp/snmpd.conf
              Agent configuration file. See snmpd.conf(5).

       /etc/snmp/snmp.conf

       ~/.snmp/snmp.conf
              Application configuration files. See snmp.conf(5).

SEE ALSO

       snmpget(1),      snmpgetnext(1),      snmpset(1),       snmpbulkget(1),
       snmpbulkwalk(1),     snmpwalk(1),     snmptable(1),     snmpnetstat(1),
       snmpdelta(1), snmptrap(1),  snmpinform(1),  snmpusm(1),  snmpstatus(1),
       snmptest(1), snmp.conf(5).