DEVEL15-document-fs-setacl-permissions-20070129
[openafs.git] / doc / man-pages / pod1 / fs_setacl.pod
1 =head1 NAME
2
3 fs setacl - Sets the ACL for a directory
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<fs setacl> S<<< B<-dir> <I<directory>>+ >>> S<<< B<-acl> <I<access list entries>>+ >>>
11     [B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>]
12
13 B<fs sa> S<<< B<-d> <I<directory>>+ >>> S<<< B<-a> <I<access list entries>>+ >>>
14     [B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
15
16 B<fs seta> S<<< B<-d> <I<directory>>+ >>> S<<< B<-a> <I<access list entries>>+ >>>
17     [B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
18
19 =for html
20 </div>
21
22 =head1 DESCRIPTION
23
24 The B<fs setacl> command adds the access control list (ACL) entries
25 specified with the B<-acl> argument to the ACL of each directory named by
26 the B<-dir> argument.
27
28 If the B<-dir> argument designates a pathname in DFS filespace (accessed
29 via the AFS/DFS Migration Toolkit Protocol Translator), it can be a file
30 as well as a directory. The ACL must already include an entry for
31 C<mask_obj>, however. For more details, refer to the I<IBM AFS/DFS
32 Migration Toolkit Administration Guide and Reference>.
33
34 Only user and group entries are acceptable values for the B<-acl>
35 argument. Do not place machine entries (IP addresses) directly on an ACL;
36 instead, make the machine entry a group member and place the group on the
37 ACL.
38
39 To completely erase the existing ACL before adding the new entries,
40 provide the B<-clear> flag. To add the specified entries to the C<Negative
41 rights> section of the ACL (deny rights to specified users or groups),
42 provide the B<-negative> flag.
43
44 To display an ACL, use the fs listacl command. To copy an ACL from one
45 directory to another, use the B<fs copyacl> command.
46
47 =head1 CAUTIONS
48
49 If the ACL already grants certain permissions to a user or group, the
50 permissions specified with the B<fs setacl> command replace the existing
51 permissions, rather than being added to them.
52
53 Setting negative permissions is generally unnecessary and not
54 recommended. Simply omitting a user or group from the C<Normal rights>
55 section of the ACL is normally adequate to prevent access. In particular,
56 note that it is futile to deny permissions that are granted to members of
57 the system:anyuser group on the same ACL; the user needs only to issue the
58 B<unlog> command to receive the denied permissions.
59
60 When including the B<-clear> option, be sure to reinstate an entry for
61 each directory's owner that includes at least the C<l> (lookup)
62 permission. Without that permission, it is impossible to resolve the "dot"
63 (C<.>) and "dot dot" (C<..>) shorthand from within the directory. (The
64 directory's owner does implicitly have the C<a> (administer) permission
65 even on a cleared ACL, but must know to use it to add other permissions.)
66
67 =head1 OPTIONS
68
69 =over 4
70
71 =item B<-dir> <I<directory>>+
72
73 Names each AFS directory, or DFS directory or file, for which the set the
74 ACL. Partial pathnames are interpreted relative to the current working
75 directory.
76
77 Specify the read/write path to each directory (or DFS file), to avoid the
78 failure that results from attempting to change a read-only volume. By
79 convention, the read/write path is indicated by placing a period before
80 the cell name at the pathname's second level (for example,
81 F</afs/.abc.com>). For further discussion of the concept of read/write and
82 read-only paths through the filespace, see the B<fs mkmount> reference
83 page.
84
85 =item B<-acl> <I<access list entries>>+
86
87 Defines a list of one or more ACL entries, each a pair that names:
88
89 =over 4
90
91 =item *
92
93 A user name or group name as listed in the Protection Database.
94
95 =item *
96
97 One or more ACL permissions, indicated either by combining the individual
98 letters or by one of the four acceptable shorthand words.
99
100 =back
101
102 in that order, separated by a space (thus every instance of this argument
103 has two parts). The accepted AFS abbreviations and shorthand words, and
104 the meaning of each, are as follows:
105
106 =over 4
107
108 =item a (administer)
109
110 Change the entries on the ACL.
111
112 =item d (delete)
113
114 Remove files and subdirectories from the directory or move them to other
115 directories.
116
117 =item i (insert)
118
119 Add files or subdirectories to the directory by copying, moving or
120 creating.
121
122 =item k (lock)
123
124 Set read locks or write locks on the files in the directory.
125
126 =item l (lookup)
127
128 List the files and subdirectories in the directory, stat the directory
129 itself, and issue the B<fs listacl> command to examine the directory's
130 ACL.
131
132 =item r (read)
133
134 Read the contents of files in the directory; issue the C<ls -l> command to
135 stat the elements in the directory.
136
137 =item w (write)
138
139 Modify the contents of files in the directory, and issue the UNIX B<chmod>
140 command to change their mode bits.
141
142 =item A, B, C, D, E, F, G, H
143
144 Have no default meaning to the AFS server processes, but are made
145 available for applications to use in controlling access to the directory's
146 contents in additional ways. The letters must be uppercase.
147
148 =item all
149
150 Equals all seven permissions (C<rlidwka>).
151
152 =item none
153
154 No permissions. Removes the user/group from the ACL, but does not
155 guarantee they have no permissions if they belong to groups that remain on
156 the ACL.
157
158 =item read
159
160 Equals the C<r> (read) and C<l> (lookup) permissions.
161
162 =item write
163
164 Equals all permissions except C<a> (administer), that is, C<rlidwk>.
165
166 =back
167
168 It is acceptable to mix entries that combine the individual letters with
169 entries that use the shorthand words, but not use both types of notation
170 within an individual pairing of user or group and permissions.
171
172 To learn the proper format and acceptable values for DFS ACL entries, see
173 the I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>.
174
175 =item B<-clear>
176
177 Removes all existing entries on each ACL before adding the entries
178 specified with the B<-acl> argument.
179
180 =item B<-negative>
181
182 Places the specified ACL entries in the C<Negative rights> section of each
183 ACL, explicitly denying the rights to the user or group, even if entries
184 on the accompanying C<Normal rights> section of the ACL grant them
185 permissions.
186
187 This argument is not supported for DFS files or directories, because DFS
188 does not implement negative ACL permissions.
189
190 =item B<-id>
191
192 Places the ACL entries on the Initial Container ACL of each DFS directory,
193 which are the only file system objects for which this flag is supported.
194
195 =item B<-if>
196
197 Places the ACL entries on the Initial Object ACL of each DFS directory,
198 which are the only file system objects for which this flag is supported.
199
200 =item B<-help>
201
202 Prints the online help for this command. All other valid options are
203 ignored.
204
205 =back
206
207 =head1 EXAMPLES
208
209 The following example adds two entries to the C<Normal rights> section of
210 the current working directory's ACL: the first entry grants C<r> (read)
211 and C<l> (lookup) permissions to the group pat:friends, while the other
212 (using the C<write> shorthand) gives all permissions except C<a>
213 (administer) to the user C<smith>.
214
215    % fs setacl -dir . -acl pat:friends rl smith write
216
217    % fs listacl -path .
218    Access list for . is
219    Normal rights:
220       pat:friends rl
221       smith rlidwk
222
223 The following example includes the B<-clear> flag, which removes the
224 existing permissions (as displayed with the B<fs listacl> command) from
225 the current working directory's F<reports> subdirectory and replaces them
226 with a new set.
227
228    % fs listacl -dir reports
229    Access list for reports is
230    Normal rights:
231       system:authuser rl
232       pat:friends rlid
233       smith rlidwk
234       pat rlidwka
235    Negative rights:
236       terry rl
237
238    % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl
239
240    % fs listacl -dir reports
241    Access list for reports is
242    Normal rights:
243       system:anyuser rl
244       smith rlidwk
245       pat rlidwka
246
247 The following example use the B<-dir> and B<-acl> switches because it sets
248 the ACL for more than one directory (both the current working directory
249 and its F<public> subdirectory).
250
251    % fs setacl -dir . public -acl pat:friends rli
252
253    % fs listacl -path . public
254    Access list for . is
255    Normal rights:
256       pat rlidwka
257       pat:friends rli
258    Access list for public is
259    Normal rights:
260       pat rlidwka
261       pat:friends rli
262
263 =head1 PRIVILEGE REQUIRED
264
265 The issuer must have the C<a> (administer) permission on the directory's
266 ACL, a member of the system:administrators group, or, as a special case,
267 must be the UID owner of the top-level directory of the volume containing
268 this directory.  The last provision allows the UID owner of a volume to
269 repair accidental ACL errors without requiring intervention by a member of
270 system:administrators.
271
272 Earlier versions of OpenAFS also extended implicit administer permission
273 to the owner of any directory.  In current versions of OpenAFS, only the
274 owner of the top-level directory of the volume has this special
275 permission.
276
277 =head1 SEE ALSO
278
279 L<fs_copyacl(1)>,
280 L<fs_listacl(1)>,
281 L<fs_mkmount(1)>
282
283 I<IBM AFS/DFS Migration Toolkit Administration Guide and Reference>
284
285 =head1 COPYRIGHT
286
287 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
288
289 This documentation is covered by the IBM Public License Version 1.0.  It was
290 converted from HTML to POD by software written by Chas Williams and Russ
291 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.