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