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