Manual Pages for UNIX Operating System command usage for man snmpusm

Net-SNMP                                               SNMPUSM(1)



NAME
     snmpusm - creates and maintains SNMPv3 users  on  a  network
     entity

SYNOPSIS
     snmpusm [COMMON OPTIONS] create USER [CLONEFROM-USER]
     snmpusm [COMMON OPTIONS] delete USER
     snmpusm [COMMON OPTIONS] cloneFrom USER CLONEFROM-USER
     snmpusm [COMMON OPTIONS] [-Ca] [-Cx]  passwd  OLD-PASSPHRASE
     NEW-PASSPHRASE [USER]
     snmpusm [COMMON OPTIONS] <-Ca | -Cx> -Ck passwd  OLD-KEY-OR-
     PASSPHRASE NEW-KEY-OR-PASSPHRASE [USER]
     snmpusm [COMMON OPTIONS] [-Ca] [-Cx] changekey [USER]


DESCRIPTION
     snmpusm is an SNMP application that can be used to do simple
     maintenance  on the users known to an SNMP agent, by manipu-
     lating the agent's User-based Security Module  (USM)  table.
     The  user  needs write access to the usmUserTable MIB table.
     This tool can be used to create, delete, clone,  and  change
     the passphrase of users configured on a running SNMP agent.


OPTIONS
     Common options for all snmpusm commands:

     -CE ENGINE-ID
          Set usmUserEngineID to be used as part of the index  of
          the  usmUserTable.   Default  is  to use the contextEn-
          gineID (set via -E or probed) as the usmUserEngineID.

     -Cp STRING
          Set the usmUserPublic value of the (new)  user  to  the
          specified STRING.

     Options for the passwd and changekey commands:

     -Ca  Change the authentication key.

     -Cx  Change the privacy key.

     -Ck  Allows to  use  localized  key  (must  start  with  0x)
          instead  of  passphrase.   When  this  option  is used,
          either the -Ca or -Cx option (but not both)  must  also
          be used.


CREATING USERS
     An unauthenticated SNMPv3 user can be created using the com-
     mand




V5.4.1              Last change: 22 Oct 2005                    1






Net-SNMP                                               SNMPUSM(1)



          snmpusm [OPTIONS] create USER

     This constructs an (inactive)  entry  in  the  usmUserTable,
     with  no  authentication or privacy settings.  In principle,
     this user should be useable for 'noAuthNoPriv' requests, but
     in  practise the Net-SNMP agent will not allow such an entry
     to be made active.


     In order to activate this entry, it is necessary to  "clone"
     an existing user, using the command

          snmpusm [OPTIONS] cloneFrom USER CLONEFROM-USER

     The USER entry then inherits  the  same  authentication  and
     privacy  settings  (including pass phrases) as the CLONEFROM
     user.


     These two steps can be combined into one, by using the  com-
     mand

          snmpusm [OPTIONS] create USER CLONEFROM-USER


     The two forms of the create  sub-command  require  that  the
     user  being  created  does not already exist.  The cloneFrom
     sub-command requires that the  user  being  cloned  to  does
     already exist.


     Cloning is the only way to specify which authentication  and
     privacy  protocols  to  use for a given user, and it is only
     possible to do this once.  Subsequent  attempts  to  reclone
     onto  the  same  user  will  appear  to succeed, but will be
     silently ignored.  This (somewhat unexpected)  behaviour  is
     mandated  by  the  SNMPv3 USM specifications (RFC 3414).  To
     change the authentication and privacy settings for  a  given
     user, it is necessary to delete and recreate the user entry.
     This is not necessary for simply changing the  pass  phrases
     (see  below).  This means that the agent must be initialized
     with at least one user for each combination  of  authentica-
     tion  and  privacy  protocols.  See the snmpd.conf(5) manual
     page for details of the createUser configuration directive.


DELETING USERS
     A user can be deleted from the usmUserTable using  the  com-
     mand

          snmpusm [OPTIONS] delete USER




V5.4.1              Last change: 22 Oct 2005                    2






Net-SNMP                                               SNMPUSM(1)



CHANGING PASS PHRASES
     User profiles contain private keys that are never  transmit-
     ted  over  the wire in clear text (regardless of whether the
     administration requests are encrypted or not). To change the
     secret key for a user, it is necessary to specify the user's
     old passphrase as well as the new one.  This uses  the  com-
     mand

          snmpusm [OPTIONS]  [-Ca]  [-Cx]  passwd  OLD-PASSPHRASE
          NEW-PASSPHRASE [USER]


     After cloning a new user entry  from  the  appropriate  tem-
     plate,   you   should  immediately  change  the  new  user's
     passphrase.


     If USER is not  specified,  this  command  will  change  the
     passphrase of the (SNMPv3) user issuing the command.  If the
     -Ca or -Cx options are specified, then only the  authentica-
     tion  or privacy keys are changed.  If these options are not
     specified, then both the authentication and privacy keys are
     changed.


          snmpusm [OPTIONS] [-Ca] [-Cx] changekey [USER]


     This command changes the key  in  a  perfect-forward-secrecy
     compliant  way through a diffie-helman exchange.  The remote
     agent must support the SNMP-USM-DH-OBJECTS-MIB for this com-
     mand to work.  The resulting keys are printed to the console
     and may be then set in future command invocations using  the
     --defAuthLocalizedKey  and  --defPrivLocalizedKey options or
     in your snmp.conf file  using  the  defAuthLocalizedKey  and
     defPrivLocalizedKey keywords.


     Note that since these keys are randomly generated based on a
     diffie  helman  exchange,  they are no longer derived from a
     more easily typed password.  They are,  however,  much  more
     secure.


     To change from a localized key back to a password, the  fol-
     lowing variant of the passwd sub-command is used:


          snmpusm [OPTIONS] <-Ca | -Cx>  -Ck  passwd  OLD-KEY-OR-
          PASSPHRASE NEW-KEY-OR-PASSPHRASE [USER]





V5.4.1              Last change: 22 Oct 2005                    3






Net-SNMP                                               SNMPUSM(1)



     Either the -Ca or the -Cx option  must  be  specified.   The
     OLD-KEY-OR-PASSPHRASE and/or NEW-KEY-OR-PASSPHRASE arguments
     can either be a passphrase or a localized key starting  with
     "0x", e.g. as printed out by the changekey sub-command.


EXAMPLES
     Let's assume for our examples that the  following  VACM  and
     USM  configurations  lines were in the snmpd.conf file for a
     Net-SNMP agent.  These lines set up a  default  user  called
     "initial"     with     the     authentication     passphrase
     "setup_passphrase" so that we can perform the initial  setup
     of an agent:

          # VACM configuration entries
          rwuser initial
          # lets add the new user we'll create too:
          rwuser wes
          # USM configuration entries
          createUser initial MD5 setup_passphrase DES

     Note: the "initial" user's setup  should  be  removed  after
     creating   a   real   user  that  you  grant  administrative
     privileges to (like the user "wes" we'll be creating in this
     example.

     Note: passphrases must be 8 characters minimum in length.

  Create a new user
     snmpusm -v3 -u  initial  -n  ""  -l  authNoPriv  -a  MD5  -A
     setup_passphrase localhost create wes initial

          Creates a new user, here named  "wes"  using  the  user
          "initial"  to do it.  "wes" is cloned from "initial" in
          the process, so  he  inherits  that  user's  passphrase
          ("setup_passphrase").

  Change the user's passphrase
     snmpusm  -v  3  -u  wes  -n  ""  -l  authNoPriv  -a  MD5  -A
     setup_passphrase     localhost    passwd    setup_passphrase
     new_passphrase

          After creating the user "wes" with the same  passphrase
          as the "initial" user, we need to change his passphrase
          for  him.   The   above   command   changes   it   from
          "setup_passphrase",  which  was inherited from the ini-
          tial user, to "new_passphrase".

  Test the new user
     snmpget  -v  3  -u  wes  -n  ""  -l  authNoPriv  -a  MD5  -A
     new_passphrase localhost sysUpTime.0




V5.4.1              Last change: 22 Oct 2005                    4






Net-SNMP                                               SNMPUSM(1)



          If the above commands  were  successful,  this  command
          should  have properly performed an authenticated SNMPv3
          GET request to the agent.

     Now, go remove the vacm "group"  snmpd.conf  entry  for  the
     "initial"  user and you have a valid user 'wes' that you can
     use for future transactions instead of initial.


WARNING
     Manipulating the usmUserTable using this command can only be
     done  using  SNMPv3.   This  command  will not work with the
     community-based versions, even if they have write access  to
     the table.


SEE ALSO
     snmpd.conf(5), snmp.conf(5), RFC 3414

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________________________
    |   ATTRIBUTE TYPE   |          ATTRIBUTE VALUE        |
    |____________________|__________________________________|_
    | Availability       |  system/management/snmp/net-snmp|
    |____________________|__________________________________|_
    | Interface Stability|  Volatile                       |
    |____________________|_________________________________|

NOTES
     Source for net-snmp is available on http://opensolaris.org.






















V5.4.1              Last change: 22 Oct 2005                    5