1SNMPVACM(1)                        Net-SNMP                        SNMPVACM(1)
2
3
4

NAME

6       snmpvacm  -  creates  and  maintains  SNMPv3  View-based Access Control
7       entries on a network entity
8

SYNOPSIS

10       snmpvacm [COMMON  OPTIONS]  AGENT  createSec2Group  MODEL  SECURITYNAME
11       GROUPNAME
12       snmpvacm [COMMON OPTIONS] AGENT deleteSec2Group MODEL SECURITYNAME
13       snmpvacm [COMMON OPTIONS] AGENT createView [-Ce] NAME SUBTREE MASK
14       snmpvacm [COMMON OPTIONS] AGENT deleteView NAME SUBTREE
15       snmpvacm [COMMON OPTIONS]  AGENT createAccess GROUPNAME [CONTEXTPREFIX]
16       MODEL LEVEL CONTEXTMATCH READVIEW WRITEVIEW NOTIFYVIEW
17       snmpvacm [COMMON OPTIONS]  AGENT deleteAccess GROUPNAME [CONTEXTPREFIX]
18       MODEL LEVEL
19       snmpvacm  [COMMON  OPTIONS]  AGENT createAuth GROUPNAME [CONTEXTPREFIX]
20       MODEL LEVEL AUTHTYPE CONTEXTMATCH VIEW
21       snmpvacm [COMMON OPTIONS]  AGENT deleteAuth  GROUPNAME  [CONTEXTPREFIX]
22       MODEL LEVEL AUTHTYPE
23
24

DESCRIPTION

26       snmpvacm  is  an SNMP application that can be used to do simple mainte‐
27       nance on the View-based Control Module (VACM) tables of an SNMP  agent.
28       The  SNMPv3 VACM specifications (see RFC2575) define assorted tables to
29       specify groups of users, MIB views,  and  authorised  access  settings.
30       These snmpvacm commands effectively create or delete rows in the appro‐
31       priate one of these tables, and match the equivalent  configure  direc‐
32       tives which are documented in the snmpd.conf(5) man page.
33
34       A  fuller  explanation of how these operate can be found in the project
35       FAQ.
36

SUB-COMMANDS

38   createSec2Group MODEL SECURITYNAME GROUPNAME
39       Create an entry in the SNMPv3 security name to group table.  This table
40       allows a single access control entry to be applied to a number of users
41       (or 'principals'), and is indexed by the security  model  and  security
42       name values.
43
44       MODEL
45
46              An  integer  representing  the security model, taking one of the
47              following values:
48              1 - reserved for SNMPv1
49              2 - reserved for SNMPv2c
50              3 - User-based Security Model (USM)
51
52
53       SECURITYNAME
54
55              A string representing the security name for a principal  (repre‐
56              sented  in  a security-model-independent format).  For USM-based
57              requests, the security name is the same as the username.
58
59
60       GROUPNAME
61
62              A string identifying the group that this  entry  (i.e.  security
63              name/model pair) should belong to.  This group name will then be
64              referenced in the access table (see createAccess below).
65
66   deleteSec2Group MODEL SECURITYNAME
67       Delete an entry from the SNMPv3 security  name  to  group  table,  thus
68       removing access control settings for the given principal.  The entry to
69       be removed is indexed by  the  MODEL  and  SECURITYNAME  values,  which
70       should  match  those  used in the corresponding createSec2Group command
71       (or equivalent).
72
73
74   createView [-Ce] NAME SUBTREE MASK
75       Create an entry in the SNMPv3 MIB view table.  A MIB view consists of a
76       family of view subtrees which may be individually included in or (occa‐
77       sionally) excluded from the view.  Each view subtree is  defined  by  a
78       combination  of  an  OID  subtree together with a bit string mask.  The
79       view table is indexed by the view name and subtree OID values.
80
81       [-Ce]
82
83              An optional flag to indicate that this view  subtree  should  be
84              excluded  from the named view.  If not specified, the default is
85              to include the subtree in the view.  When  constructing  a  view
86              from  a  mixture of included and excluded subtrees, the excluded
87              subtrees should be defined first -  particularly  if  the  named
88              view is already referenced in one or more access entries.
89
90       NAME
91
92              A  string  identifying  a particular MIB view, of which this OID
93              subtree/mask forms part (possibly the only part).
94
95       SUBTREE
96
97              The OID defining the root of the subtree to add to  (or  exclude
98              from) the named view.
99
100       MASK
101
102              A  bit  mask  indicating which sub-identifiers of the associated
103              subtree OID should be regarded as significant.
104
105
106   deleteView NAME SUBTREE
107       Delete an entry from the SNMPv3 view table, thus removing  the  subtree
108       from  the  given  MIB  view.  Removing the final (or only) subtree will
109       result in the deletion of the view.  The entry to be removed is indexed
110       by  the  NAME  and SUBTREE values, which should match those used in the
111       corresponding createView command (or equivalent).
112
113       When removing subtrees from a mixed view (i.e. containing both included
114       and excluded subtrees), the included subtrees should be removed first.
115
116
117   createAccess  GROUPNAME  [CONTEXTPREFIX]  MODEL LEVEL CONTEXTMATCH READVIEW
118       WRITEVIEW NOTIFYVIEW
119       Create an entry in the SNMPv3 access table,  thus  allowing  a  certain
120       level of access to particular MIB views for the principals in the spec‐
121       ified group (given suitable security model and levels in the  request).
122       The access table is indexed by the group name, context prefix, security
123       model and security level values.
124
125       GROUPNAME
126
127              The name of the group that this access entry applies to (as  set
128              up by a createSec2Group command, or equivalent)
129
130       CONTEXTPREFIX
131
132              A  string  representing a context name (or collection of context
133              names) which this access entry applies to.   The  interpretation
134              of  this  string  depends on the value of the CONTEXTMATCH field
135              (see below).
136
137              If omitted, this will default to the null context "".
138
139       MODEL
140
141              An integer representing the security model, taking  one  of  the
142              following values:
143              1 - reserved for SNMPv1
144              2 - reserved for SNMPv2c
145              3 - User-based Security Model (USM)
146
147       LEVEL
148
149              An  integer  representing the minimal security level, taking one
150              of the following values:
151              1 - noAuthNoPriv
152              2 - authNoPriv
153              3 - authPriv
154
155              This access entry will be applied to requests of this  level  or
156              higher  (where  authPriv  is  higher than authNoPriv which is in
157              turn higher than noAuthNoPriv).
158
159       CONTEXTMATCH
160
161              Indicates how to interpret the  CONTEXTPREFIX  value.   If  this
162              field  has the value '1' (representing 'exact') then the context
163              name of a request must match the CONTEXTPREFIX value exactly for
164              this access entry to be applicable to that request.
165
166              If this field has the value '2' (representing 'prefix') then the
167              initial substring of the context name of a  request  must  match
168              the  CONTEXTPREFIX  value for this access entry to be applicable
169              to that request.  This provides a simple form of wildcarding.
170
171       READVIEW
172
173              The name of the MIB view (as set up by createView or equivalent)
174              defining  the MIB objects for which this request may request the
175              current values.
176
177              If there is no view with this name,  then  read  access  is  not
178              granted.
179
180       WRITEVIEW
181
182              The name of the MIB view (as set up by createView or equivalent)
183              defining the MIB objects for which this request may  potentially
184              SET new values.
185
186              If  there  is  no  view  with this name, then read access is not
187              granted.
188
189       NOTIFYVIEW
190
191              The name of the MIB view (as set up by createView or equivalent)
192              defining  the  MIB objects which may be included in notification
193              request.
194
195              Note that this aspect of access control is  not  currently  sup‐
196              ported.
197
198
199   deleteAccess GROUPNAME [CONTEXTPREFIX] MODEL LEVEL
200       Delete  an entry from the SNMPv3 access table, thus removing the speci‐
201       fied access control settings.  The entry to be removed  is  indexed  by
202       the  group name, context prefix, security model and security level val‐
203       ues, which should match those used in  the  corresponding  createAccess
204       command (or equivalent).
205
206
207   createAuth GROUPNAME [CONTEXTPREFIX] MODEL LEVEL AUTHTYPE CONTEXTMATCH VIEW
208       Create an entry in the Net-SNMP extension to the standard access table,
209       thus allowing a certain type of access to the MIB view for the  princi‐
210       pals  in  the  specified  group.  The interpretation of GROUPNAME, CON‐
211       TEXTPREFIX, MODEL, LEVEL and CONTEXTMATCH are the same as for the  cre‐
212       ateAccess  directive.   The  extension  access  table is indexed by the
213       group name, context prefix, security model, security level and authtype
214       values.
215
216       AUTHTYPE
217
218              The  style  of access that this entry should be applied to.  See
219              snmpd.conf(5) and snmptrapd.conf(5) for details of valid tokens.
220
221       VIEW
222
223              The name of the MIB view (as set up by createView or equivalent)
224              defining  the  MIB  objects  for  which  this style of access is
225              authorized.
226
227
228   deleteAuth GROUPNAME [CONTEXTPREFIX] MODEL LEVEL AUTHTYPE
229       Delete an entry from the extension  access  table,  thus  removing  the
230       specified  access control settings.  The entry to be removed is indexed
231       by the group name, context prefix, security model, security  level  and
232       authtype  values,  which  should  match those used in the corresponding
233       createAuth command (or equivalent).
234
235
236       Note that snmpget REQUIRES  an argument specifying the agent  to  query
237       as described in the .I snmpcmd(1) manual page.
238
239

EXAMPLES

241       Given  a  pre-existing  user dave (which could be set up using the snm‐
242       pusm(1) command), we could configure  full  read-write  access  to  the
243       whole OID tree using the commands:
244
245
246              snmpvacm localhost createSec2Group 3 dave RWGroup
247
248              snmpvacm localhost createView   all .1 80
249
250              snmpvacm localhost createAccess  RWGroup 3 1 1 all all none
251
252       This creates a new security group named "RWGroup" containing the SNMPv3
253       user "dave", a new view "all" containing the full  OID  tree  based  on
254       .iso(1)  ,  and  then  allows  those users in the group "RWGroup" (i.e.
255       "dave") both read- and write-access to the view "all"  (i.e.  the  full
256       OID tree) when using authenticated SNMPv3 requests.
257
258
259       As  a  second example, we could set up read-only access to a portion of
260       the OID tree using the commands:
261
262
263              snmpvacm localhost createSec2Group 3 wes ROGroup
264
265              snmpvacm localhost createView   sysView  system fe
266
267              snmpvacm localhost createAccess  ROGroup 3 0 1 sysView none none
268
269       This creates a new security group named "ROGroup" containing the  (pre-
270       existing) user "wes", a new view "sysView" containing just the OID tree
271       based on .iso(1).org(3).dod(6).inet(1).mgmt(2).mib-2(1).system(1) , and
272       then  allows  those  users  in  the  group "ROGroup" (i.e. "wes") read-
273       access, but not write-access to the view  "sysView"  (i.e.  the  system
274       group).
275
276

EXIT STATUS

278       The following exit values are returned:
279
280       0 - Successful completion
281
282       1 - A usage syntax error (which displays a suitable usage message) or a
283       request timeout.
284
285       2 - An error occurred while executing the command (which also  displays
286       a suitable error message).
287
288

LIMITATIONS

290       This  utility  does  not  support  the  configuration  of new community
291       strings, so is only of use for setting up new access control for SNMPv3
292       requests.   It  can  be  used to amend the access settings for existing
293       community strings, but not to set up new ones.
294
295
296       The use of numeric parameters for secLevel and contextMatch  parameters
297       is  less than intuitive.  These commands do not provide the full flexi‐
298       bility of the equivalent config file directives.
299
300
301       There is (currently) no equivalent to the one-shot configure directives
302       rouser and rwuser.
303
304

SEE ALSO

306       snmpcmd(1), snmpusm(1), snmpd.conf(5), snmp.conf(5), RFC 2575, Net-SNMP
307       project FAQ
308
309
310
311V5.9                              05 Sep 2006                      SNMPVACM(1)
Impressum