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

   1 .TH SNMPUSM 1 "08 Feb 2002" VVERSIONINFO "Net-SNMP"
   2 .UC 4
   3 .SH NAME
   4 snmpusm - creates and maintains SNMPv3 users on a remote entity.
   5 .SH SYNOPSIS
   6 .B snmpusm
   7 [COMMON OPTIONS]
   8 .B create
   9 USER [CLONEFROM-USER]
  10 .br
  11 .B snmpusm
  12 [COMMON OPTIONS]
  13 .B delete
  14 USER
  15 .br
  16 .B snmpusm
  17 [COMMON OPTIONS]
  18 .B cloneFrom
  19 USER CLONEFROM-USER
  20 .br
  21 .B snmpusm
  22 [COMMON OPTIONS] [-Co] [-Ca] [-Cx]
  23 .B passwd
  24 OLD-PASSPHRASE NEW-PASSPHRASE
  25
  26 .SH DESCRIPTION
  27 .B snmpusm
  28 is an SNMP application that can be used to do simple maintenance on a
  29 SNMP agent's User-based Security Module (USM) table.  You can create,
  30 delete, clone, and change the passphrase of users configured on a
  31 running SNMP agent.
  32 .PP
  33 The SNMPv3 USM specifications (see RFC2574) dictate that users are
  34 created and maintained by adding and modifying rows to the
  35 usmUserTable MIB table.  To create a new user you simply create the
  36 row using
  37 .BR snmpset .
  38 User's profiles contain private keys that are never
  39 transmitted over the wire in clear text (regardless of whether the
  40 administration requests are encrypted or not).
  41 .PP
  42 The secret key for a user is initially set by cloning another user in
  43 the table, so that a new user inherits the cloned user's secret key.
  44 A user can only be cloned once, however, after which they must be
  45 deleted and re-created to be re-cloned.  The authentication and
  46 privacy security types are also inherited during this cloning (e.g.,
  47 MD5 vs. SHA1).  To change the secret key for a user, you must know the
  48 user's old passphrase as well as the new one.  The
  49 .B passwd
  50 sub-command of the
  51 .B snmpusm
  52 command, therefore, requires both the new and the old
  53 pass-phrases to be supplied.  After cloning from the appropriate
  54 template, you should immediately change the new users passphrase.
  55 .PP
  56 The Net-SNMP agent must first be initialized so that at least one user
  57 is setup in it before you can use this command to clone new ones.  See the
  58 .I snmpd.conf(5)
  59 manual page on the
  60 .B createUser
  61 configuration parameter.
  62 .SH EXAMPLES
  63 .PP
  64 Let's assume for our examples that the following VACM and USM
  65 configurations lines were in the snmpd.conf file for a Net-SNMP agent.
  66 These lines set up a default user called "initial" with the
  67 authentication passphrase "setup_passphrase" so that we can perform
  68 the initial setup of an agent:
  69 .PP
  70 .RS
  71 .nf
  72 # VACM configuration entries
  73 rwuser initial
  74 # lets add the new user we'll create too:
  75 rwuser wes
  76 # USM configuration entries
  77 createUser initial MD5 setup_passphrase DES
  78 .fi
  79 .RE
  80 .PP
  81 Note: the "initial" user's setup should be removed after creating a
  82 real user that you grant administrative privileges to (like the user
  83 "wes" we'll be creating in this example.
  84 .PP
  85 Note: passphrases must be 8 characters
  86 .I minimum
  87 in length.
  88 .SS Create a new user
  89 .PP
  90 snmpusm -v3 -u initial -n "" -l authNoPriv -a MD5 -A setup_passphrase
  91 localhost create wes initial
  92 .IP
  93 Creates a new user, here named "wes" using the user "initial" to do
  94 it.  "wes" is cloned from "initial" in the process, so he inherits
  95 that user's passphrase ("setup_passphrase").
  96 .SS Change the user's passphrase
  97 .PP
  98 snmpusm -v 3 -u wes -n "" -l authNoPriv -a MD5 -A setup_passphrase
  99 localhost passwd setup_passphrase new_passphrase
 100 .IP
 101 After creating the user "wes" with the same passphrase as the
 102 "initial" user, we need to change his passphrase for him.  The above
 103 command changes it from "setup_passphrase", which was inherited from
 104 the initial user, to "new_passphrase".
 105 .SS Test the new user
 106 .PP
 107 snmpget -v 3 -u wes -n "" -l authNoPriv -a MD5 -A new_passphrase
 108 localhost sysUpTime.0
 109 .IP
 110 If the above commands were successful, this command should have
 111 properly performed an authenticated SNMPv3 GET request to the agent.
 112 .PP
 113 Now, go remove the vacm "group" snmpd.conf entry for the "initial"
 114 user and you have a valid user 'wes' that you can use for future
 115 transactions instead of initial.
 116 .SH "SEE ALSO"
 117 snmpd.conf(5), snmp.conf(5), RFC 2574