- (snmpusm.1): added to describe the snmpusm command.
git-svn-id: file:///home/hardaker/lib/sf-bkups/net-snmp-convert-svnrepo/trunk@3009 06827809-a52a-0410-b366-d66718629ded
diff --git a/man/snmpusm.1 b/man/snmpusm.1
new file mode 100644
index 0000000..d819599
--- /dev/null
+++ b/man/snmpusm.1
@@ -0,0 +1,84 @@
+.TH SNMPGET 1 "13 July 1994"
+.UC 4
+.SH NAME
+snmpusm - creates and maintains SNMPv3 user's on a remote entity.
+.SH SYNOPSIS
+snmpusm [ common arguments ] create username [cloneFromUser]
+.br
+snmpusm [ common arguments ] delete username
+.br
+snmpusm [ common arguments ] cloneFrom username cloneFromUser
+.br
+snmpusm [ common arguments ] passwd -O old_passphrase -N new_passphrase [-o] [-a] [-x]
+.SH DESCRIPTION
+Snmpusm is an SNMP application that can be used to do simple maintance
+on a snmp agent's User based Security Module (USM) table. You can
+create, delete, clone, and change the pasword of users configured on a
+running snmp agent.
+.PP
+The SNMPv3 USM specifications (see RFC2574) dictate that users are
+created and maintained by adding and modifying rows to the usmUser MIB
+table. To create a new user you simply create the row using an
+snmpset. User's profiles contain private keys that are never
+transmitted over the wire in clear text (regardless of weather the
+administration requests are in encrypted or not).
+.PP
+The secret key for a user is initially set by cloning another user in
+the table, so that a user inherits the cloned user's secret key. A
+user can only be cloned once, however, after which they must be
+deleted and re-created to be re-cloned. The authentication and
+privacy security types are also inherited during this cloning (E.G.,
+MD5 vs SHA1). To change the secret key for a user, you must know the
+user's old key as well as the new one. The passwd sub-command of the
+snmpusm command, therefore, requires both the new and the old password
+to be suplied.
+.PP
+The ucd-snmp agent comes with a few pre-configured template users
+which you can use to clone new users from after setting the template
+user's pass-phrases in the snmpd.conf file. These users are called
+"templateMD5" and "templateSHA", and are configured to use MD5 and SHA
+respectfully and DES encryption. After cloning from the appropriate
+template, you should immediately change the new users password.
+.SH EXAMPLES
+.PP
+Lets assume for our examples that the following VACM and USM
+configurations lines were in the snmpd.conf file for a ucd-snmp agent,
+which sets up another default user called "initial" with the
+passphrase "setup_password" so that we can perform the initial setup
+of an agent:
+.RS
+# VACM configuration entries
+group v3group any initial
+view all included .1 80
+access v3group "" any auth 0 all all all
+# The new user's access:
+group v3group any wes
+# USM configuration entries
+userSetAuthPass initial * setup_password
+userSetAuthPass templateMD5 * initial_MD5_pass
+.RE
+Note: that the "initial" user's setup should be removed after creating
+a real user that you grant administrative privledges to (like the user
+"wes" we'll be creating in this example.
+.PP
+Note: passwords (passphrases really) must be 8 characters minimum in
+length.
+.IP "snmpusm -v 3 -u initial -n none -l authNoPriv -a MD5 -A setup_password localhost create wes templateMD5"
+Creates a new user, here named "wes" using the user "initial" to do
+it. "wes" is cloned from templateMD5 in the process, so he inherits
+that users pasword.
+.IP "snmpusm -v 3 -u wes -n none -l authNoPriv -a MD5 -A initial_MD5_pass localhost passwd -O initial_MD5_pass -N new_passphrase -a"
+After creating the user "wes" with the same password as the
+"templateMD5" user, we need to change his passphrase for him. This
+command changed it from "initial_MD5_pass", which was inherited from
+the templateMD5 user, to "new_passphrase".
+.IP "snmpget -v 3 -u wes -n none -l authNoPriv -a MD5 -A new_passphrase localhost sysUpTime.0"
+If the above commands were successful, this command should have
+properly performed an authenticated snmpv3 GET request to the agent.
+.PP
+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.
+.PP
+.SH "SEE ALSO"
+snmpd.conf(5), snmp.conf(5)
