cbe0e4ddfd0eb349e8e38f390fbfa2c4b0878334
[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.
32
33 Only user and group entries are acceptable values for the B<-acl>
34 argument. Do not place machine entries (IP addresses) directly on an ACL;
35 instead, make the machine entry a group member and place the group on the
36 ACL.
37
38 To completely erase the existing ACL before adding the new entries,
39 provide the B<-clear> flag. To add the specified entries to the C<Negative
40 rights> section of the ACL (deny rights to specified users or groups),
41 provide the B<-negative> flag.
42
43 To display an ACL, use the fs listacl command. To copy an ACL from one
44 directory to another, use the B<fs copyacl> command.
45
46 =head1 CAUTIONS
47
48 If the ACL already grants certain permissions to a user or group, the
49 permissions specified with the B<fs setacl> command replace the existing
50 permissions, rather than being added to them.
51
52 Setting negative permissions is generally unnecessary and not
53 recommended. Simply omitting a user or group from the C<Normal rights>
54 section of the ACL is normally adequate to prevent access. In particular,
55 note that it is futile to deny permissions that are granted to members of
56 the system:anyuser group on the same ACL; the user needs only to issue the
57 B<unlog> command to receive the denied permissions.
58
59 When including the B<-clear> option, be sure to reinstate an entry for
60 each directory's owner that includes at least the C<l> (lookup)
61 permission. Without that permission, it is impossible to resolve the "dot"
62 (C<.>) and "dot dot" (C<..>) shorthand from within the directory. (The
63 directory's owner does implicitly have the C<a> (administer) permission
64 even on a cleared ACL, but must know to use it to add other permissions.)
65
66 =head1 OPTIONS
67
68 =over 4
69
70 =item B<-dir> <I<directory>>+
71
72 Names each AFS directory, or DFS directory or file, for which the set the
73 ACL. Partial pathnames are interpreted relative to the current working
74 directory.
75
76 Specify the read/write path to each directory (or DFS file), to avoid the
77 failure that results from attempting to change a read-only volume. By
78 convention, the read/write path is indicated by placing a period before
79 the cell name at the pathname's second level (for example,
80 F</afs/.abc.com>). For further discussion of the concept of read/write and
81 read-only paths through the filespace, see the B<fs mkmount> reference
82 page.
83
84 =item B<-acl> <I<access list entries>>+
85
86 Defines a list of one or more ACL entries, each a pair that names:
87
88 =over 4
89
90 =item *
91
92 A user name or group name as listed in the Protection Database.
93
94 =item *
95
96 One or more ACL permissions, indicated either by combining the individual
97 letters or by one of the four acceptable shorthand words.
98
99 =back
100
101 in that order, separated by a space (thus every instance of this argument
102 has two parts). The accepted AFS abbreviations and shorthand words, and
103 the meaning of each, are as follows:
104
105 =over 4
106
107 =item a (administer)
108
109 Change the entries on the ACL.
110
111 =item d (delete)
112
113 Remove files and subdirectories from the directory or move them to other
114 directories.
115
116 =item i (insert)
117
118 Add files or subdirectories to the directory by copying, moving or
119 creating.
120
121 =item k (lock)
122
123 Set read locks or write locks on the files in the directory.
124
125 =item l (lookup)
126
127 List the files and subdirectories in the directory, stat the directory
128 itself, and issue the B<fs listacl> command to examine the directory's
129 ACL.
130
131 =item r (read)
132
133 Read the contents of files in the directory; issue the C<ls -l> command to
134 stat the elements in the directory.
135
136 =item w (write)
137
138 Modify the contents of files in the directory, and issue the UNIX B<chmod>
139 command to change their mode bits.
140
141 =item A, B, C, D, E, F, G, H
142
143 Have no default meaning to the AFS server processes, but are made
144 available for applications to use in controlling access to the directory's
145 contents in additional ways. The letters must be uppercase.
146
147 =item all
148
149 Equals all seven permissions (C<rlidwka>).
150
151 =item none
152
153 No permissions. Removes the user/group from the ACL, but does not
154 guarantee they have no permissions if they belong to groups that remain on
155 the ACL.
156
157 =item read
158
159 Equals the C<r> (read) and C<l> (lookup) permissions.
160
161 =item write
162
163 Equals all permissions except C<a> (administer), that is, C<rlidwk>.
164
165 =back
166
167 It is acceptable to mix entries that combine the individual letters with
168 entries that use the shorthand words, but not use both types of notation
169 within an individual pairing of user or group and permissions.
170
171 Granting the C<l> (lookup) and C<i> (insert) permissions without
172 granting the C<w> (write) and/or C<r> (read) permissions is a special
173 case, and grants rights approrpriate for "dropbox" directories. See the
174 L<DROPBOXES> section for details.
175
176 If setting ACLs on a pathname in DFS filespace, see the DFS documentation
177 for the proper format and acceptable values for DFS ACL entries.
178
179 =item B<-clear>
180
181 Removes all existing entries on each ACL before adding the entries
182 specified with the B<-acl> argument.
183
184 =item B<-negative>
185
186 Places the specified ACL entries in the C<Negative rights> section of each
187 ACL, explicitly denying the rights to the user or group, even if entries
188 on the accompanying C<Normal rights> section of the ACL grant them
189 permissions.
190
191 This argument is not supported for DFS files or directories, because DFS
192 does not implement negative ACL permissions.
193
194 =item B<-id>
195
196 Places the ACL entries on the Initial Container ACL of each DFS directory,
197 which are the only file system objects for which this flag is supported.
198
199 =item B<-if>
200
201 Places the ACL entries on the Initial Object ACL of each DFS directory,
202 which are the only file system objects for which this flag is supported.
203
204 =item B<-help>
205
206 Prints the online help for this command. All other valid options are
207 ignored.
208
209 =back
210
211 =head1 DROPBOXES
212
213 If an accessing user has the C<l> (read) and C<i> (insert) permissions
214 on a directory, but not the C<w> (write) and/or C<r> (read) permissions,
215 the user is implicitly granted the ability to write and/or read any file
216 they create in that directory, until they close the file. This is to
217 allow "dropbox"-style directories to exist, where users can deposit
218 files, but cannot modify them later nor can they modify or read any
219 files deposited in the directory by other users.
220
221 Note, however, that the dropbox functionality is not perfect. The
222 fileserver does not have knowledge of when a file is opened or closed on
223 the client, and so the fileserver always allows an accessing user to
224 read or write to a file in a "dropbox" directory if they own the file.
225 While the client prevents the user from reading or modifying their
226 deposited file later, this is not enforced on the fileserver, and so
227 should not be relied on for security.
228
229 Additionally, if "dropbox" permissions are granted to C<system:anyuser>,
230 unauthenticated users may deposit files in the directory. If an
231 unauthenticated user deposits a file in the directory, the new file will
232 be owned by the unauthenticated user ID, and is thus potentially
233 modifiable by anyone.
234
235 In an effort to try and reduce accidentally publicizing private data, the
236 fileserver may refuse read requests for "dropbox" files from unauthenticated
237 users. As a result, depositing files as an unauthenticated user may arbitrarily
238 fail if C<system:anyuser> has been granted dropbox permissions. While this
239 should be rare, it is not completely preventable, and so for this reason
240 relying on unauthenticated users to be able to deposit files in a dropbox is
241 B<NOT RECOMMENDED>.
242
243 =head1 EXAMPLES
244
245 The following example adds two entries to the C<Normal rights> section of
246 the current working directory's ACL: the first entry grants C<r> (read)
247 and C<l> (lookup) permissions to the group pat:friends, while the other
248 (using the C<write> shorthand) gives all permissions except C<a>
249 (administer) to the user C<smith>.
250
251    % fs setacl -dir . -acl pat:friends rl smith write
252
253    % fs listacl -path .
254    Access list for . is
255    Normal rights:
256       pat:friends rl
257       smith rlidwk
258
259 The following example includes the B<-clear> flag, which removes the
260 existing permissions (as displayed with the B<fs listacl> command) from
261 the current working directory's F<reports> subdirectory and replaces them
262 with a new set.
263
264    % fs listacl -dir reports
265    Access list for reports is
266    Normal rights:
267       system:authuser rl
268       pat:friends rlid
269       smith rlidwk
270       pat rlidwka
271    Negative rights:
272       terry rl
273
274    % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl
275
276    % fs listacl -dir reports
277    Access list for reports is
278    Normal rights:
279       system:anyuser rl
280       smith rlidwk
281       pat rlidwka
282
283 The following example use the B<-dir> and B<-acl> switches because it sets
284 the ACL for more than one directory (both the current working directory
285 and its F<public> subdirectory).
286
287    % fs setacl -dir . public -acl pat:friends rli
288
289    % fs listacl -path . public
290    Access list for . is
291    Normal rights:
292       pat rlidwka
293       pat:friends rli
294    Access list for public is
295    Normal rights:
296       pat rlidwka
297       pat:friends rli
298
299 =head1 PRIVILEGE REQUIRED
300
301 The issuer must have the C<a> (administer) permission on the directory's
302 ACL, a member of the system:administrators group, or, as a special case,
303 must be the UID owner of the top-level directory of the volume containing
304 this directory.  The last provision allows the UID owner of a volume to
305 repair accidental ACL errors without requiring intervention by a member of
306 system:administrators.
307
308 Earlier versions of OpenAFS also extended implicit administer permission
309 to the owner of any directory.  In current versions of OpenAFS, only the
310 owner of the top-level directory of the volume has this special
311 permission.
312
313 =head1 SEE ALSO
314
315 L<fs_copyacl(1)>,
316 L<fs_listacl(1)>,
317 L<fs_mkmount(1)>
318
319 =head1 COPYRIGHT
320
321 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
322
323 This documentation is covered by the IBM Public License Version 1.0.  It was
324 converted from HTML to POD by software written by Chas Williams and Russ
325 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.