1SNMPUSM(1) Net-SNMP SNMPUSM(1)
2
6 snmpusm - creates and maintains SNMPv3 users on a network entity
7
9 snmpusm [COMMON OPTIONS] create USER [CLONEFROM-USER]
10 snmpusm [COMMON OPTIONS] delete USER
11 snmpusm [COMMON OPTIONS] cloneFrom USER CLONEFROM-USER
12 snmpusm [COMMON OPTIONS] [-Ca] [-Cx] passwd OLD-PASSPHRASE NEW-
13 PASSPHRASE [USER]
14 snmpusm [COMMON OPTIONS] <-Ca | -Cx> -Ck passwd OLD-KEY-OR-PASSPHRASE
15 NEW-KEY-OR-PASSPHRASE [USER]
16 snmpusm [COMMON OPTIONS] [-Ca] [-Cx] changekey [USER]
17
20 snmpusm is an SNMP application that can be used to do simple mainte‐
21 nance on the users known to an SNMP agent, by manipulating the agent's
22 User-based Security Module (USM) table. The user needs write access to
23 the usmUserTable MIB table. This tool can be used to create, delete,
24 clone, and change the passphrase of users configured on a running SNMP
25 agent.
26
29 Common options for all snmpusm commands:
30 -CE ENGINE-ID
32 Set usmUserEngineID to be used as part of the index of the
33 usmUserTable. Default is to use the contextEngineID (set via -E
34 or probed) as the usmUserEngineID.
35 -Cp STRING
37 Set the usmUserPublic value of the (new) user to the specified
38 STRING.
39 Options for the passwd and changekey commands:
41 -Ca Change the authentication key.
43 -Cx Change the privacy key.
45 -Ck Allows to use localized key (must start with 0x) instead of
47 passphrase. When this option is used, either the -Ca or -Cx
48 option (but not both) must also be used.
49
52 An unauthenticated SNMPv3 user can be created using the command
53 snmpusm [OPTIONS] create USER
55 This constructs an (inactive) entry in the usmUserTable, with no
57 authentication or privacy settings. In principle, this user should be
58 useable for 'noAuthNoPriv' requests, but in practise the Net-SNMP agent
59 will not allow such an entry to be made active.
60 In order to activate this entry, it is necessary to "clone" an existing
63 user, using the command
64 snmpusm [OPTIONS] cloneFrom USER CLONEFROM-USER
66 The USER entry then inherits the same authentication and privacy set‐
68 tings (including pass phrases) as the CLONEFROM user.
69 These two steps can be combined into one, by using the command
72 snmpusm [OPTIONS] create USER CLONEFROM-USER
74 The two forms of the create sub-command require that the user being
77 created does not already exist. The cloneFrom sub-command requires
78 that the user being cloned to does already exist.
79 Cloning is the only way to specify which authentication and privacy
82 protocols to use for a given user, and it is only possible to do this
83 once. Subsequent attempts to reclone onto the same user will appear to
84 succeed, but will be silently ignored. This (somewhat unexpected) be‐
85 haviour is mandated by the SNMPv3 USM specifications (RFC 3414). To
86 change the authentication and privacy settings for a given user, it is
87 necessary to delete and recreate the user entry. This is not necessary
88 for simply changing the pass phrases (see below). This means that the
89 agent must be initialized with at least one user for each combination
90 of authentication and privacy protocols. See the snmpd.conf(5) manual
91 page for details of the createUser configuration directive.
92
95 A user can be deleted from the usmUserTable using the command
96 snmpusm [OPTIONS] delete USER
98
101 User profiles contain private keys that are never transmitted over the
102 wire in clear text (regardless of whether the administration requests
103 are encrypted or not). To change the secret key for a user, it is nec‐
104 essary to specify the user's old passphrase as well as the new one.
105 This uses the command
106 snmpusm [OPTIONS] [-Ca] [-Cx] passwd OLD-PASSPHRASE NEW-
108 PASSPHRASE [USER]
109 After cloning a new user entry from the appropriate template, you
112 should immediately change the new user's passphrase.
113 If USER is not specified, this command will change the passphrase of
116 the (SNMPv3) user issuing the command. If the -Ca or -Cx options are
117 specified, then only the authentication or privacy keys are changed.
118 If these options are not specified, then both the authentication and
119 privacy keys are changed.
120 snmpusm [OPTIONS] [-Ca] [-Cx] changekey [USER]
123 This command changes the key in a perfect-forward-secrecy compliant way
126 through a diffie-helman exchange. The remote agent must support the
127 SNMP-USM-DH-OBJECTS-MIB for this command to work. The resulting keys
128 are printed to the console and may be then set in future command invo‐
129 cations using the --defAuthLocalizedKey and --defPrivLocalizedKey
130 options or in your snmp.conf file using the defAuthLocalizedKey and
131 defPrivLocalizedKey keywords.
132 Note that since these keys are randomly generated based on a diffie
135 helman exchange, they are no longer derived from a more easily typed
136 password. They are, however, much more secure.
137 To change from a localized key back to a password, the following vari‐
140 ant of the passwd sub-command is used:
141 snmpusm [OPTIONS] <-Ca | -Cx> -Ck passwd OLD-KEY-OR-PASSPHRASE
144 NEW-KEY-OR-PASSPHRASE [USER]
145 Either the -Ca or the -Cx option must be specified. The OLD-KEY-OR-
148 PASSPHRASE and/or NEW-KEY-OR-PASSPHRASE arguments can either be a
149 passphrase or a localized key starting with "0x", e.g. as printed out
150 by the changekey sub-command.
151
154 Let's assume for our examples that the following VACM and USM configu‐
155 rations lines were in the snmpd.conf file for a Net-SNMP agent. These
156 lines set up a default user called "initial" with the authentication
157 passphrase "setup_passphrase" so that we can perform the initial setup
158 of an agent:
159 # VACM configuration entries
161 rwuser initial
162 # lets add the new user we'll create too:
163 rwuser wes
164 # USM configuration entries
165 createUser initial MD5 setup_passphrase DES
166 Note: the "initial" user's setup should be removed after creating a
168 real user that you grant administrative privileges to (like the user
169 "wes" we'll be creating in this example.
170 Note: passphrases must be 8 characters minimum in length.
172 Create a new user
174 snmpusm -v3 -u initial -n "" -l authNoPriv -a MD5 -A setup_passphrase
175 localhost create wes initial
176 Creates a new user, here named "wes" using the user "initial" to
178 do it. "wes" is cloned from "initial" in the process, so he
179 inherits that user's passphrase ("setup_passphrase").
180 Change the user's passphrase
182 snmpusm -v 3 -u wes -n "" -l authNoPriv -a MD5 -A setup_passphrase
183 localhost passwd setup_passphrase new_passphrase
184 After creating the user "wes" with the same passphrase as the
186 "initial" user, we need to change his passphrase for him. The
187 above command changes it from "setup_passphrase", which was
188 inherited from the initial user, to "new_passphrase".
189 Test the new user
191 snmpget -v 3 -u wes -n "" -l authNoPriv -a MD5 -A new_passphrase local‐
192 host sysUpTime.0
193 If the above commands were successful, this command should have
195 properly performed an authenticated SNMPv3 GET request to the
196 agent.
197 Now, go remove the vacm "group" snmpd.conf entry for the "initial" user
199 and you have a valid user 'wes' that you can use for future transac‐
200 tions instead of initial.
201
204 Manipulating the usmUserTable using this command can only be done using
205 SNMPv3. This command will not work with the community-based versions,
206 even if they have write access to the table.
207
210 snmpd.conf(5), snmp.conf(5), RFC 3414
2114th Berkeley Distribution 22 Oct 2005 SNMPUSM(1)