snmpcmd



SNMPCMD(1)                         Net-SNMP                         SNMPCMD(1)




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, snmpnet-
       stat, snmpset, snmpstatus, snmptable, snmptest, snmptrap,  snmpdf, snm-
       pusm  , snmpwalk .  The command line applications use the SNMP protocol
       to communicate with an SNMP capable network entity, an agent.  Individ-
       ual applications typically (but not necessarily) take additional param-
       eters 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  dis-
              cussed  below.   For further details on SNMPv3 and it’s usage of
              keying  information,  see  the  Net-SNMP  tutorial  web  site  (
              http://www.Net-SNMP.org/tutorial-5/commands/    ).     See   the
              snmp.conf manual page on the defAuthMasterKey and related tokens
              for more information as well.

       -a authProtocol
              Set the authentication protocol (MD5|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 sent and received SNMP packets.

       -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.   It  is  typically  not necessary to specify
              this, as it will usually be discovered automatically.

       -E engineID
              Set the context engineID used for SNMPv3 REQUEST messages scope-
              dPdu.   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  (noAuthNo-
              Priv|authNoPriv|authPriv).  Appropriate pass phrase(s) must pro-
              vided  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 the environment vari-
              able MIBS.

              The special keyword ALL is used to specify all  modules  in  all
              directories when searching for MIB files.  Every file whose name
              does not begin with "." will be parsed as if it were a MIB file.

              If  the  MIBLIST  has a leading ’+’, then the listed MIB modules
              are loaded in addition to MIB modules specified in the  environ-
              ment variable MIBS.

              If  a  mibfile  token is specified in the snmp.conf file, the -m
              MIB option overrides the mibfile token.

       -M DIRLIST
              Specifies a colon separated list of directories  to  search  for
              MIBs.  This overrides the environment variable MIBDIRS.

              If  DIRLIST  has  a  leading ’+’, then the given directories are
              added to the list of MIB directories.  Without the leading  ’+’,
              the  given  directory list overrides the list specified with the
              environment variable MIBDIRS. Note that the  directories  listed
              at  the  end of the list have precedence over directories at the
              beginning of the list.

              If no value is specified for the environment  variable  MIBDIRS,
              then  the  command  will  still  search a default mib directory,
              after it searches  the  MIB  directories  specified  on  the  -M
              option.   The  default  directory  is  /usr/share/snmp/mibs.  To
              avoid having a default mib directory searched, set  the  MIBDIRS
              environment  variable  to "".  Even if the default MIB directory
              is searched, the directories specified in  the  -M  option  have
              precedence in the search order over the default directory.

              If  the  -M  option is specified and either a mibfile or mibdirs
              token is also specified in the snmp.conf file,  the  directories
              in  the  -M option have precedence in the MIB search order, over
              the directories set with both the mibdirs token and the  mibfile
              token.

       -n contextName
              Set  the  destination contextName used for SNMPv3 messages.  The
              default contextName is the empty string "".  Overrides the  def-
              Context 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 typi-
              cally version 3. This option 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) used for encrypted SNMPv3 mes-
              sages.

       -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.



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 host-
                               name 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  num-
                               ber  00D0B7AAE308  on  the default network, and
                               using the default IPX port of 36879 (900F  hex-
                               adecimal), 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  connec-
                               tion.

       /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 cur-
       rently 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.

       -Pw    Show  some  warning messages in resolving the MIB files.  Can be
              also set with the configuration token "mibWarningLevel".

       -PW    Show additional warning messages.  Can be also set with the con-
              figuration token "mibWarningLevel".

       -Pe    Show  MIB  errors.  Can be also set with the configuration token
              "showMibErrors".  An example of an error that would be shown  is
              if an imported module is not found during MIB parsing.

       -Pc    Allow  ASN.1 comment to extend to the end of the MIB source line
              (i.e. disallow the use of "--"  to  terminate  comments).   This
              overcomes some problems with manually maintained MIB files.  Can
              be also set with the configuration token "strictCommentTerm".

       -Pd    Toggles the default of whether or not to save  the  DESCRIPTIONs
              of  the  MIB objects when parsing.  Since the default is to save
              the DESCRIPTIONS, specifying -Pd will cause the DESCRIPTIONs not
              to be saved during MIB parsing.  For example:

              snmptranslate -Td -OS -IR system.sysDescr.0

              will show a description, while

              snmptranslate -Td -OS -IR -Pd system.sysDescr.0

              will  not show a description.  Collecting the DESCRIPTION infor-
              mation into the parsed hierarchy increases the  memory  used  by
              the size of each DESCRIPTION clause.

       -Pu    Allow underline characters in symbols.  Can be also set with the
              configuration token "mibAllowUnderline".

       -PR    Replace MIB objects using the last read MIB  file.   The  parser
              will  replace  MIB  objects  in its hierarchy whenever it sees a
              sub-identifier and name match.  WARNING: Setting this option may
              result in an incorrect hierarchy.  Can be also set with the con-
              figuration token "mibReplaceWithLatest".



OUTPUT OPTIONS

       Output display can be controlled by passing various parameters  to  the
       -O flag.  The following examples should demonstrate this.

       The default output looks as follows:
       snmpget -c public -v 1 localhost system.sysUpTime.0
       SNMPv2-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

       -Oq    Removes the equal sign and type information:
              system.sysUpTime.0 1:15:09:27.63

       -OQ    Removes the type information:
              system.sysUpTime.0 = 1:15:09:27.63

       -Of    Gives you the complete OID:
               .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.0   =  Timet-
              icks: (14096763) 1 day, 15:09:27.63

       -Os    Deletes all but the last symbolic part of the OID:
              sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

       -OS    A variation on -Os that adds the name of the  MIB  that  defined
              the object:
              SNMPv2-MIB::sysUpTime.0   =   Timeticks:   (14096763)   1   day,
              15:09:27.63
              (from release 5.0, this is now the default output format)

       -Ou    Prints the OID in the UCD-style (inherited from the original CMU
              code),  That  means removing a series of "standard" prefixes, if
              relevant, and breaking down the OID into the displayable pieces.
              For example, the OID vacmSecruityModel.0.3.119.101.115 is broken
              down by default and the string hidden in the OID is shown.   The
              result  would  look  like:  vacmSecurityModel.0."test".  The -Ob
              option disables this feature.
              system.sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63

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

       -Oe    Removes the symbolic labels from enumerations:
              snmpget -c public -v 1 localhost ip.ipForwarding.0
              ip.ipForwarding.0 = INTEGER: forwarding(1)
              snmpget -c public -v 1 -Oe localhost ip.ipForwarding.0
              ip.ipForwarding.0 = INTEGER: 1

       -Ob    When OIDs contain a index to a table, they are broken  into  the
              displayable  pieces and shown to you.  For example the OID vacm-
              SecurityModel.0.3.119.101.115 is nicely broken down  by  default
              and  the string hidden in the OID is shown to you as vacmSecuri-
              tyModel.0."wes".  The -Ob option disables this feature and  dis-
              plays it as vacmSecurityModel.0.3.119.101.115 again.

       -OE    This  modifies  the  index  strings to include a \ to escape the
              quotes, to allow them to be reused in shell  commands,  such  as
              vacmSecurityModel.0.\"wes\"

       -OX    This  modifies  the  output of index OIDs, to look more "program
              like".  Square brackets are placed around each  index,  and  the
              DISPLAY-HINT information and string conversions are used to for-
              mat   each   index.    If   you   take   an   entry   from   the
              IPV6-MIB::ipv6RouteTable, it is indexed with an IPv6 address and
              two integers, and if you are used to  IPv6  addresses  you  will
              know that decimal OIDs are not the preferred notation. Compare:
              snmpgetnext -OS host IPV6-MIB: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 -OSX host IPV6-MIB:ipv6RouteTable
              IPV6-MIB::ipv6RouteIfIndex[3ffe:100:ff00:0:0:0:0:0][64][1]     =
              INTEGER: 2

       -Oa    If  a string-valued object definition does not include a Display
              Hint, then the library attempts to determine whether  it  is  an
              ascii  or  binary  string,  and  displays the value accordingly.
              This flag bypasses this  check,  and  displays  all  strings  as
              ASCII.   Note  that  this does not affect objects that do have a
              Display Hint.

       -Ox    This works similarly to ’-Oa’, but displays strings as Hex.

       -OT    If hexadecimal code is printed, this will also print any  print-
              able characters after the hexadecimal codes.

       -Ov    Output only the variable value, not the OID:
              snmpget -c public -v 1 -Ov localhost ip.ipForwarding.0
              INTEGER: forwarding(1)

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

       -Ot    Output timeticks values as raw numbers:
              system.sysUpTime.0 = 14096763

       Note  that  most of these options can be turned on or off by default by
       tuning the snmp.conf  file.   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’  (inclu-
              sive) 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  -I  flag  specifies various options that control how your input to
       the program is parsed.  By default, all input parsing methods are used:
       First  the OID is parsed regularly, then -IR is used, then -Ib is used,
       unless one of the following flags is specified which will force  it  to
       only use one method.

       -IR    The  -IR  flag  specifies  random  access lookup, so that if the
              entire OID path is not specified, it will search for a  node  in
              the  MIB  tree with the given name.  Normally, you would have to
              specify the vacmSecurityModel OID above  as  .iso.org.dod.inter-
              net.snmpV2.snmpModules.snmpVacmMIB.vacmMIBObjects.vacmSecurity-
              ToGroupTable.vacmSecurityToGroupEntry.vacmSecurityModel.0."wes",
              but  the  use of the -IR flag allows you to shorten that to just
              vacmSecurityModel.0."wes".  (Though this OID really needs to  be
              quoted - ’vacmSecurityModel.0."wes"’ - to prevent the shell from
              swallowing the double quotes).

              Additionally, see the RANDOM ACCESS MIBS section below.

       -Ib    The -Ib flag indicates that the expression you gave it is  actu-
              ally  a regular expression that should be used to search for the
              best match possible in the MIB tree.  This would  allow  you  to
              specify  the  node  vacmSecurityModel  MIB  node as something as
              generic as vacmsecuritymodel (since  case  insensitive  searches
              are  done) or vacm.*model.  Note that multiple matches are obvi-
              ously possible (.* matches everything), and the best  result  is
              currently  calculated as the one that matches the closest to the
              beginning of the node name and the highest in the tree.  A  cur-
              rent  side  effect  of  this  option  is that you cannot specify
              indexes or multiple nodes, since the ’.’ is treated as  part  of
              the regular expression.

       -Iu    Use  the  traditional  UCD-style input approach of assuming that
              OIDs are rooted at the ’mib-2’ point in the  tree  (unless  they
              start  with  an  explicit  ’.’)    If random access lookup is in
              effect (which is the default for most commands), then this  will
              only affect OIDs specified with a leading numberic subidentifier
              (and no initial ’.’)  Thus an input of  "snmpcmd  ...  1"  would
              refer  to  ’iso’  (from  v5.0 onwards) while "snmpcmd -Iu ... 1"
              would refer to ’system’.

       -Ir    By default, indices into tables and values  to  be  assigned  to
              objects are checked against range and type specified in the MIB.
              The -Ir flag disables this check.  This flag  is  mostly  useful
              when  you are testing an agent.  For normal operation it is use-
              ful to get your requests checked before they  are  sent  to  the
              remote  agent  (the  diagnostic  that the library can provide is
              also much more precise).

       -Ih    By default, the library will use DISPLAY-HINT  information  when
              assigning values.  This flag disables this behaviour. The result
              is that instead of
              snmpset    localhost    HOST-RESOURCES-MIB::hrSystemDate.0     =
              2002-12-10,2:4:6.8
              you will have to write
              snmpset localhost HOST-RESOURCES-MIB::hrSystemData.0 x "07 D2 0C
              0A 02 04 06 08"

       -Is SUFFIX
              Add the specified suffix to each textual OID given on  the  com-
              mand  line.   It  is useful to specify a common index value when
              you want to retrieve multiple objects from the same row of a ta-
              ble.

       -IS PREFIX
              Add  the  specified prefix to each textual OID given on the com-
              mand line.  Useful to specify an explicit MIB  module  name  for
              all objects being retrieved (or for incurably lazy typists)



RANDOM ACCESS MIBS

       In  previous  releases  of  the  UCD-SNMP package (and if using the -Iu
       option), an object identifier such as system.sysDescr.0 will be  lookup
       in  a single "well known" place, built into the SNMP library (or speci-
       fied by the PREFIX  environment  variable).   The  standard  place  is:
       .iso.org.dod.internet.mgmt.mib-2.   The identifier may alternatively be
       a complete object identifier, this is designated by a leading "dot"  if
       using UCD-input style, and is the first thing tried otherwise.  To sim-
       plify the specification of object identifiers the library supports ran-
       dom access to the identifiers in the MIBs. This is requested by the -IR
       option to the SNMP applications.  Additionally, -Os prints OIDs in this
       manner.   Using  this,  system.sysDescr.0 may also be entered as sysDe-
       scr.0.  To search only a single MIB for the identifier (if  it  appears
       in  more  than  one), specify it as SNMPv2-MIB::sysDescr.0. (use -OS to
       print output OIDs in this manner, though this is the  default  as  from
       v5.0). This notation will also ensure that the specified MIB is loaded,
       i.e. it need not be mentioned in the -m  option  (or  MIBS  environment
       variable).



ENVIRONMENT VARIABLES

       PREFIX The  standard  prefix for object identifiers (if 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),  snmpbulk-
       walk(1),  snmpwalk(1),  snmptable(1),   snmpnetstat(1),   snmpdelta(1),
       snmptrap(1),  snmpinform(1),  snmpusm(1),  snmpstatus(1),  snmptest(1),
       snmp.conf(5).




4th Berkeley Distribution         09 Jan 2004                       SNMPCMD(1)

Man(1) output converted with man2html