initial-html-documentation-20010606
[openafs.git] / doc / html / UserGuide / auusg007.htm
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
2 <HTML><HEAD>
3 <TITLE>User Guide</TITLE>
4 <!-- Begin Header Records  ========================================== -->
5 <!-- /tmp/idwt3629/auusg000.scr converted by idb2h R4.2 (359) ID      -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 14:38:44                -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 14:38:42">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 14:38:42">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 14:38:42">
10 </HEAD><BODY>
11 <!-- (C) IBM Corporation 2000. All Rights Reserved    --> 
12 <BODY bgcolor="ffffff"> 
13 <!-- End Header Records  ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>User Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg006.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auusg008.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
17 <HR><H1><A NAME="HDRWQ44" HREF="auusg002.htm#ToC_79">Protecting Your Directories and Files</A></H1>
18 <P>This chapter explains how to protect AFS files and
19 directories by defining permissions on an access control list.
20 <HR><H2><A NAME="HDRWQ45" HREF="auusg002.htm#ToC_80">Access Control Lists</A></H2>
21 <A NAME="IDX924"></A>
22 <A NAME="IDX925"></A>
23 <A NAME="IDX926"></A>
24 <A NAME="IDX927"></A>
25 <A NAME="IDX928"></A>
26 <P>AFS augments and refines the standard UNIX scheme for controlling access to
27 files and directories. Instead of using mode bits to define access
28 permissions for individual files, as UNIX does, AFS stores an <I>access
29 control list</I> (<I>ACL</I>) with each directory. It defines
30 which users and groups can access the directory and the files it contains, and
31 in what manner. An ACL can store up to about 20 entries, each of which
32 pairs a user or group and a set of permissions. AFS defines seven
33 permissions rather than the three that UNIX uses.
34 <P>Another refinement to the standard UNIX protection scheme is that users can
35 define their own protection <I>groups</I> and then place the groups on
36 ACLs as though they were individual users. A group can include both
37 users and machines. Each user who belongs to a group inherits all of
38 the permissions granted to the group on the ACL. Similarly, all users
39 who are logged into a machine that belongs to a group inherits all of the
40 permissions granted to the group. You can create groups to place on
41 ACLs and also use groups that other users have created. To learn more
42 about group creation, see <A HREF="auusg008.htm#HDRWQ60">Using Groups</A>.
43 <P>In addition, AFS defines two system groups called
44 <B>system:anyuser</B> and <B>system:authuser</B>.
45 By placing them on ACLs, you can grant access to large numbers of users at
46 once. See <A HREF="#HDRWQ50">Using the System Groups on ACLs</A>.
47 <P>Although AFS uses ACLs to protect files and directories, it also uses the
48 UNIX mode bits to a limited extent. See <A HREF="#HDRWQ59">How AFS Uses the UNIX Mode Bits</A>.
49 <P><H3><A NAME="Header_81" HREF="auusg002.htm#ToC_81">Directory Level Access Control</A></H3>
50 <P>As noted, AFS associates an ACL with each directory, and it applies to
51 all of the files stored in the directory. Files do not have separate
52 ACLs. Defining access at the directory level has several
53 consequences:
54 <UL>
55 <P><LI>The permissions on a directory's ACL apply to all of the files in the
56 directory. When you move a file to a different directory, you
57 effectively change its permissions to those on its new directory's
58 ACL. Changing a directory's ACL changes the protection on all the
59 files in it.
60 <P><LI>When you create a subdirectory, it inherits the current ACL of its parent
61 directory. You can then set the subdirectory's ACL to be different
62 from its parent's. However, do not make the ACL on the parent
63 directory more restrictive than on a subdirectory, because that can prevent
64 users from accessing the subdirectory even when they have the necessary
65 permissions on its ACL. Specifically, a user must have the <B>l</B>
66 (<B>lookup</B>) permission (defined in <A HREF="#HDRWQ46">The AFS ACL Permissions</A>) on the parent directory to reach its subdirectories.
67 <A NAME="IDX929"></A>
68 <A NAME="IDX930"></A>
69 </UL>
70 <P>As a general rule, it makes sense to grant fairly liberal access to your
71 home directory. If you need to protect certain files more closely,
72 place them in subdirectories that have more restrictive ACLs.
73 <HR><H2><A NAME="HDRWQ46" HREF="auusg002.htm#ToC_82">The AFS ACL Permissions</A></H2>
74 <A NAME="IDX931"></A>
75 <A NAME="IDX932"></A>
76 <A NAME="IDX933"></A>
77 <P>There are seven standard AFS ACL permissions. Functionally, they
78 fall into two groups: one that applies to the directory itself and one
79 that applies to the files.
80 <P><H3><A NAME="HDRWQ47" HREF="auusg002.htm#ToC_83">The Four Directory Permissions</A></H3>
81 <P>The four permissions in this group are meaningful with
82 respect to the directory itself. For example, the <B>i</B>
83 (<B>insert</B>) permission does not control addition of data to a file,
84 but rather creation of a new file or subdirectory.
85 <DL>
86 <P><DT><B>The l (lookup) permission
87 </B><DD>This permission functions as something of a gate keeper for access to the
88 directory and its files, because a user must have it in order to exercise any
89 other permissions. In particular, a user must have this permission to
90 access anything in the directory's subdirectories.
91 <A NAME="IDX934"></A>
92 <A NAME="IDX935"></A>
93 <P>This permission enables a user to issue the following commands:
94 <UL>
95 <P><LI>The <B>ls</B> command to list the names of the files and
96 subdirectories in the directory
97 <P><LI>The <B>ls -ld</B> command to obtain complete status information for
98 the directory element itself
99 <P><LI>The <B>fs listacl</B> command to examine the directory's ACL
100 </UL>
101 <P>This permission does not enable a user to read the contents of a file in
102 the directory or to issue the <B>ls -l</B> or <B>fs listacl</B>
103 commands with a filename as the argument. Those operations require the
104 <B>r</B> (<B>read</B>) permission, which is described in <A HREF="#HDRWQ48">The Three File Permissions</A>.
105 <P>Similarly, this permission does not enable a user to issue the
106 <B>ls</B>, <B>ls -l</B>, <B>ls -ld</B>, or <B>fs listacl</B>
107 commands against a subdirectory of the directory. Those operations
108 require the <B>l</B> permission on the ACL of the subdirectory
109 itself.
110 <P><DT><B>The i (insert) permission
111 </B><DD>This permission enables a user to add new files to the directory, either
112 by creating or copying, and to create new subdirectories. It does not
113 extend into any subdirectories, which are protected by their own ACLs.
114 <A NAME="IDX936"></A>
115 <A NAME="IDX937"></A>
116 <P><DT><B>The d (delete) permission
117 </B><DD>This permission enables a user to remove files and subdirectories from the
118 directory or move them into other directories (assuming that the user has the
119 <B>i</B> permission on the ACL of the other directories).
120 <A NAME="IDX938"></A>
121 <A NAME="IDX939"></A>
122 <P><DT><B>The a (administer) permission
123 </B><DD>This permission enables a user to change the directory's ACL.
124 Members of the <B>system:administrators</B> group implicitly have
125 this permission on every directory (that is, even if that group does not
126 appear on the ACL). Similarly, the owner of a directory implicitly has
127 this permission on its ACL and those of all directories below it.
128 <A NAME="IDX940"></A>
129 <A NAME="IDX941"></A>
130 </DL>
131 <P><H3><A NAME="HDRWQ48" HREF="auusg002.htm#ToC_84">The Three File Permissions</A></H3>
132 <P>The three permissions in this group are meaningful with
133 respect to files in a directory, rather than the directory itself or its
134 subdirectories.
135 <DL>
136 <P><DT><B>The r (read) permission
137 </B><DD>This permission enables a user to read the contents of files in the
138 directory and to issue the <B>ls -l</B> command to stat the file
139 elements.
140 <A NAME="IDX942"></A>
141 <A NAME="IDX943"></A>
142 <P><DT><B>The w (write) permission
143 </B><DD>This permission enables a user to modify the contents of files in the
144 directory and to issue the <B>chmod</B> command to change their UNIX mode
145 bits.
146 <A NAME="IDX944"></A>
147 <A NAME="IDX945"></A>
148 <P><DT><B>The k (lock) permission
149 </B><DD>This permission enables a user to run programs that issue system calls to
150 lock files in the directory. 
151 <A NAME="IDX946"></A>
152 <A NAME="IDX947"></A>
153 </DL>
154 <P><H3><A NAME="Header_85" HREF="auusg002.htm#ToC_85">The Eight Auxiliary Permissions</A></H3>
155 <A NAME="IDX948"></A>
156 <A NAME="IDX949"></A>
157 <P>AFS provides eight additional permissions that do not have a defined
158 meaning. They are denoted by the uppercase letters <B>A</B>,
159 <B>B</B>, <B>C</B>, <B>D</B>, <B>E</B>, <B>F</B>,
160 <B>G</B>, and <B>H</B>.
161 <P>Your system administrator can choose to write application programs that
162 assign a meaning to one or more of the permissions, and then place them on
163 ACLs to control file access by those programs. Use the <B>fs
164 listacl</B> and <B>fs setacl</B> commands to display and set the
165 auxiliary permissions on ACLs just like the standard seven.
166 <P><H3><A NAME="Header_86" HREF="auusg002.htm#ToC_86">Shorthand Notation for Sets of Permissions</A></H3>
167 <A NAME="IDX950"></A>
168 <A NAME="IDX951"></A>
169 <A NAME="IDX952"></A>
170 <P>You can combine the seven permissions in any way in an ACL entry, but
171 certain combinations are more useful than others. Four of the more
172 common combinations have corresponding shorthand forms. When using the
173 <B>fs setacl</B> command to define ACL entries, you can provide either one
174 or more of the individual letters that represent the permissions, or one of
175 the following shorthand forms:
176 <DL>
177 <P><DT><B>all
178 </B><DD>Represents all seven standard permissions (<B>rlidwka</B>)
179 <A NAME="IDX953"></A>
180 <P><DT><B>none
181 </B><DD>Removes the entry from the ACL, leaving the user or group with no
182 permission 
183 <A NAME="IDX954"></A>
184 <P><DT><B>read
185 </B><DD>Represents the <B>r</B> (<B>read</B>) and <B>l</B>
186 (<B>lookup</B>) permissions
187 <A NAME="IDX955"></A>
188 <P><DT><B>write
189 </B><DD>Represents all permissions except <B>a</B>
190 (<B>administer</B>): <B>rlidwk</B>
191 <A NAME="IDX956"></A>
192 </DL>
193 <P><H3><A NAME="HDRWQ49" HREF="auusg002.htm#ToC_87">About Normal and Negative Permissions</A></H3>
194 <A NAME="IDX957"></A>
195 <A NAME="IDX958"></A>
196 <A NAME="IDX959"></A>
197 <A NAME="IDX960"></A>
198 <A NAME="IDX961"></A>
199 <A NAME="IDX962"></A>
200 <A NAME="IDX963"></A>
201 <P>ACLs enable you both to grant and to deny access to a directory and the
202 files in it. To grant access, use the <B>fs setacl</B> command to
203 create an ACL entry that associates a set of permissions with a user or group,
204 as described in <A HREF="#HDRWQ54">Changing an ACL</A>. When you use the <B>fs listacl</B> command to
205 display an ACL (as described in <A HREF="#HDRWQ52">Displaying an ACL</A>), such entries appear underneath the following header, which
206 uses the term <I>rights</I> to refer to permissions:
207 <PRE>   Normal rights
208 </PRE>
209 <P>There are two ways to deny access:
210 <A NAME="IDX964"></A>
211 <OL TYPE=1>
212 <P><LI>The recommended method is simply to omit an entry for the user or group
213 from the ACL, or to omit the appropriate permissions from an entry. Use
214 the <B>fs setacl</B> command to remove or edit an existing entry.
215 In most cases, this method is enough to prevent access of certain kinds or by
216 certain users. You must take care, however, not to grant the undesired
217 permissions to any groups to which such users belong.
218 <P><LI>The more explicit method for denying access is to place an entry on the
219 <I>negative permissions</I> section of an ACL, by including the
220 <B>-negative</B> flag to the <B>fs setacl</B> command. For
221 instructions, see <A HREF="#HDRWQ56">To Add, Remove, or Edit Negative ACL Permissions</A>. The <B>fs listacl</B> command displays the
222 negative permissions section of an ACL underneath the following header: 
223 <PRE>   Negative rights
224 </PRE>
225 <P>When determining what type of access to grant to a user, AFS first examines
226 all of the entries in the normal permissions section of the ACL. It
227 then subtracts any permissions associated with the user (or with groups to
228 which the user belongs) on the negative permissions section of the ACL.
229 Therefore, negative permissions always cancel out normal permissions.
230 <P>Negative permissions can be confusing, because they reverse the usual
231 meaning of the <B>fs setacl</B> command. In particular, combining
232 the <B>none</B> shorthand and the <B>-negative</B> flag is a double
233 negative: by removing an entry from the negative permissions section of
234 the ACL, you enable a user once again to obtain permissions via entries in the
235 normal permissions section. Combining the <B>all</B> shorthand with
236 the <B>-negative</B> flag explicitly denies all permissions.
237 <P>It is useless to create an entry in the negative permissions section if an
238 entry in the normal permissions section grants the denied permissions to the
239 <B>system:anyuser</B> group. In this case, users can obtain
240 the permissions simply by using the <B>unlog</B> command to discard their
241 tokens. When they do so, AFS recognizes them as the
242 <B>anonymous</B> user, who belongs to the <B>system:anyuser</B>
243 group but does not match the entries on the negative permissions section of
244 the ACL.
245 </OL>
246 <P><H3><A NAME="Header_88" HREF="auusg002.htm#ToC_88">Setting DFS ACLs</A></H3>
247 <P>If your machine is configured to access a DCE cell's DFS filespace
248 via the AFS/DFS Migration Toolkit, then you can use the AFS <B>fs
249 listacl</B> and <B>fs setacl</B> commands to display and set the ACLs on
250 DFS directories and files that you own. However, DFS uses a slightly
251 different set of permissions and a different syntax for ACL entries.
252 See the DFS documentation or ask your system administrator.
253 <HR><H2><A NAME="HDRWQ50" HREF="auusg002.htm#ToC_89">Using the System Groups on ACLs</A></H2>
254 <P>
255 <A NAME="IDX965"></A>
256 <A NAME="IDX966"></A>
257 <A NAME="IDX967"></A>
258 <A NAME="IDX968"></A>
259 AFS defines two <I>system groups</I> that grant access to a large number
260 of users at once when placed on an ACL. However, you cannot control the
261 membership of these groups, so consider carefully what kind of permissions you
262 wish to give them. (You do control the membership of the groups you
263 own; see <A HREF="auusg008.htm#HDRWQ60">Using Groups</A>.)
264 <DL>
265 <P><DT><B>system:anyuser
266 </B><DD>Includes anyone who can access the cell's file tree, including users
267 who have tokens in the local cell, users who have logged in on a local AFS
268 client machine but have not obtained tokens (such as the local superuser
269 <B>root</B>), and users who have connected to a local machine from outside
270 the cell. Creating an ACL entry for this group is the only way to
271 extend access to AFS users from foreign cells, unless your system
272 administrator creates local authentication accounts for them.
273 <A NAME="IDX969"></A>
274 <P><DT><B>system:authuser
275 </B><DD>Includes all users who have a valid AFS token obtained from the local
276 cell's AFS authentication service.
277 </DL>
278 <P>The third system group, <B>system:administrators</B>, includes a
279 small group of administrators who have extensive permissions in the
280 cell. You do not generally need to put this group on your ACLs, because
281 its members always have the <B>a</B> (<B>administer</B>) permission on
282 every ACL, even if the group does not appear on it.
283 <P><H3><A NAME="Header_90" HREF="auusg002.htm#ToC_90">Enabling Access to Subdirectories</A></H3>
284 <A NAME="IDX970"></A>
285 <A NAME="IDX971"></A>
286 <P>A user must have the <B>l</B> permission on a directory to access its
287 subdirectories in any way. Even if users have extensive permissions on
288 a subdirectory, they cannot access it if the parent directory's ACL does
289 not grant the <B>l</B> permission.
290 <P>You can grant the <B>l</B> permission in one of three ways: grant
291 it to a system group (<B>system:anyuser</B> or
292 <B>system:authuser</B>), grant it to individual users, or grant it
293 to one or more groups of users defined by you or other users (see <A HREF="auusg008.htm#HDRWQ60">Using Groups</A>). Granting the <B>l</B> permission to the
294 <B>system:anyuser</B> group is the easiest option and is generally
295 secure because the permission only enables users to list the contents of the
296 directory, not to read the files in it. If you want to enable only
297 locally authenticated users to list a directory's contents, substitute
298 the <B>system:authuser</B> group for the
299 <B>system:anyuser</B> group. Your system administrator has
300 possibly already created an entry on your home directory's ACL that
301 grants the <B>r</B> and <B>l</B> permissions to the
302 <B>system:anyuser</B> group.
303 <P><H3><A NAME="Header_91" HREF="auusg002.htm#ToC_91">Extending Access to Service Processes</A></H3>
304 <A NAME="IDX972"></A>
305 <P>It is sometimes necessary to grant more extensive permissions to the
306 <B>system:anyuser</B> group so that processes that provide printing
307 and mail delivery service can work correctly. For example, printing
308 processes sometimes need the <B>r</B> permission in addition to the
309 <B>l</B> permission. A mail delivery process possibly needs the
310 <B>i</B> permission to place new messages in your mail directory.
311 Your system administrator has probably already created the necessary ACL
312 entries. If you notice an ACL entry for which the purpose is unclear,
313 check with your system administrator before removing it.
314 <P><H3><A NAME="HDRWQ51" HREF="auusg002.htm#ToC_92">Extending Access to Users from Foreign Cells</A></H3>
315 <P>
316 <A NAME="IDX973"></A>
317  The only way to grant access to users from foreign cells who do not have an
318 account in your cell is to put the <B>system:anyuser</B> group on an
319 ACL. Remember, however, that such an entry extends access to everyone
320 who can reach your cell, not just the AFS users from foreign cells that you
321 have in mind.
322 <HR><H2><A NAME="HDRWQ52" HREF="auusg002.htm#ToC_93">Displaying an ACL</A></H2>
323 <A NAME="IDX974"></A>
324 <A NAME="IDX975"></A>
325 <A NAME="IDX976"></A>
326 <P>To display the ACL associated with a file or directory, issue the <B>fs
327 listacl</B> command.
328 <P><B>Note for AFS/DFS Migration Toolkit users:</B> If the machine
329 on which you issue the <B>fs listacl</B> command is configured to access a
330 DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use
331 the command to display the ACL on DFS files and directories. To display
332 a DFS directory's Initial Container or Initial Object ACL instead of the
333 regular one, include the <B>fs listacl</B> command's <B>-id</B>
334 or <B>-if</B> flag. For more information, ask your system
335 administrator. The <B>fs</B> command interpreter ignores the
336 <B>-id</B> and <B>-if</B> flags if you include them when displaying an
337 AFS ACL.
338 <P><H3><A NAME="HDRWQ53" HREF="auusg002.htm#ToC_94">To display an ACL</A></H3>
339 <OL TYPE=1>
340 <P><LI>Issue the <B>fs listacl</B> command. 
341 <A NAME="IDX977"></A>
342 <A NAME="IDX978"></A>
343 <PRE>   % <B>fs listacl</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
344 </PRE>
345 <P>where
346 <DL>
347 <P><DT><B>la
348 </B><DD>Is an acceptable alias for <B>listacl</B> (and <B>lista</B> is the
349 shortest acceptable abbreviation).
350 <P><DT><B><VAR>dir/file path</VAR>
351 </B><DD>Names one or more files or directories for which to display the
352 ACL. For a file, the output displays the ACL on its directory.
353 If you omit this argument, the output is for the current working
354 directory. Partial pathnames are interpreted relative to the current
355 working directory. You can also use the following notation on its own
356 or as part of a pathname:
357 <DL>
358 <P><DT><B>.
359 </B><DD>(A single period). Specifies the current working directory.
360 <P><DT><B>..
361 </B><DD>(Two periods). Specifies the current working directory's
362 parent directory.
363 <P><DT><B>*
364 </B><DD>(The asterisk). Specifies each file and subdirectory in the current
365 working directory. The ACL displayed for a file is always the same as
366 for its directory, but the ACL for each subdirectory can differ.
367 </DL>
368 </DL>
369 </OL>
370 <P>The output for each file or directory specified as <VAR>dir/file path</VAR>
371 begins with the following header to identify it:
372 <PRE>   Access list for  <VAR>dir/file&nbsp;path</VAR> is
373 </PRE>
374 <P>The <TT>Normal rights</TT> header appears on the next line, followed by
375 lines that each pair a user or group name and a set of permissions. The
376 permissions appear as the single letters defined in <A HREF="#HDRWQ46">The AFS ACL Permissions</A>, and always in the order <B>rlidwka</B>. If there
377 are any negative permissions, the <TT>Negative rights</TT> header appears
378 next, followed by pairs of negative permissions.
379 <P>If the following error message appears instead of an ACL, you do not have
380 the permissions needed to display an ACL. To specify a directory name
381 as the <VAR>dir/file path</VAR> argument, you must have the <B>l</B>
382 (<B>lookup</B>) permission on the ACL. To specify a filename, you
383 must also have the <B>r</B> (<B>read</B>) permission on its
384 directory's ACL.
385 <PRE>   fs: You don't have the required access permissions on '<VAR>dir/file&nbsp;path</VAR>'
386 </PRE>
387 <P><H3><A NAME="Header_95" HREF="auusg002.htm#ToC_95">Example: Displaying the ACL on One Directory</A></H3>
388 <A NAME="IDX979"></A>
389 <P>The following example displays the ACL on user <B>terry</B>'s home
390 directory in the ABC Corporation cell:
391 <PRE>   % <B>fs la /afs/abc.com/usr/terry</B>
392    Access list for /afs/abc.com/usr/terry is
393    Normal rights:
394       system:authuser rl
395       pat rlw
396       terry rlidwka
397    Negative rights:
398       terry:other-dept rl
399       jones rl
400 </PRE>
401 <P>where <B>pat</B>, <B>terry</B>, and <B>jones</B> are individual
402 users, <B>system:authuser</B> is a system group, and
403 <B>terry:other-dept</B> is a group that <B>terry</B>
404 owns. The list of normal permissions grants all permissions to
405 <B>terry</B>, the <B>rlw</B> permissions to <B>pat</B>, and the
406 <B>rl</B> permissions to the members of the
407 <B>system:authuser</B> group.
408 <P>The list of negative permissions denies the <B>rl</B> permissions to
409 <B>jones</B> and the members of the <B>terry:other-dept</B>
410 group. These entries effectively prevent them from accessing
411 <B>terry</B>'s home directory in any way; they cancel out the
412 <B>rl</B> permissions extended to the <B>system:authuser</B>
413 group, which is the only entry on the normal permissions section of the ACL
414 that possibly applies to them.
415 <P><H3><A NAME="Header_96" HREF="auusg002.htm#ToC_96">Example:  Displaying the ACLs on Multiple Directories</A></H3>
416 <A NAME="IDX980"></A>
417 <P>The following example illustrates how you can specify pathnames in
418 different ways, and the appearance of the output for multiple
419 directories. It displays the ACL for three directories: the
420 current working directory (which is a subdirectory of user
421 <B>terry</B>'s home directory), the home directory for user
422 <B>pat</B>, and another subdirectory of <B>terry</B>'s home
423 directory called <B>plans</B>.
424 <PRE>   % <B>fs listacl  .  /afs/abc.com/usr/pat  ../plans</B>
425    Access list for . is
426    Normal rights:
427       system:anyuser rl
428       pat:dept rliw
429    Access list for /afs/abc.com/usr/pat is
430    Normal rights:
431       system:anyuser rl
432       pat rlidwka
433       terry rliw 
434    Access list for ../plans is
435    Normal rights:
436       terry rlidwka
437       pat rlidw
438 </PRE>
439 <HR><H2><A NAME="HDRWQ54" HREF="auusg002.htm#ToC_97">Changing an ACL</A></H2>
440 <A NAME="IDX981"></A>
441 <A NAME="IDX982"></A>
442 <A NAME="IDX983"></A>
443 <A NAME="IDX984"></A>
444 <P>To add, remove, or edit ACL entries, use the <B>fs setacl</B>
445 command. By default, the command manipulates entries on the normal
446 permissions section of the ACL. To manipulate entries on the negative
447 permissions section, include the <B>-negative</B> flag as instructed in <A HREF="#HDRWQ56">To Add, Remove, or Edit Negative ACL Permissions</A>.
448 <P>You can change any ACL on which you already have the <B>a</B>
449 permission. You always have the <B>a</B> permission on the ACL of
450 every directory that you own, even if you accidentally remove that permission
451 from the ACL. (The <B>ls -ld</B> command reports a directory's
452 owner.) Your system administrator normally designates you as the owner
453 of your home directory and its subdirectories, and you possibly own other
454 directories also.
455 <P>If an ACL entry already exists for the user or group you specify, then the
456 new permissions completely replace the existing permissions rather than being
457 added to them. In other words, when issuing the <B>fs setacl</B>
458 command, you must include all permissions that you want to grant to a user or
459 group.
460 <P><B>Note for AFS/DFS Migration Toolkit users:</B> If the machine
461 on which you issue the <B>fs setacl</B> command is configured to access a
462 DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use
463 the command to set the ACL on DFS files and directories. To set a DFS
464 directory's Initial Container or Initial Object ACL instead of the
465 regular one, include the <B>fs setacl</B> command's <B>-id</B> or
466 <B>-if</B> flag. For more information, ask your system
467 administrator. The <B>fs</B> command interpreter ignores the
468 <B>-id</B> and <B>-if</B> flags if you include them when setting an
469 AFS ACL.
470 <P><H3><A NAME="HDRWQ55" HREF="auusg002.htm#ToC_98">To Add, Remove, or Edit Normal ACL Permissions</A></H3>
471 <A NAME="IDX985"></A>
472 <A NAME="IDX986"></A>
473 <A NAME="IDX987"></A>
474 <A NAME="IDX988"></A>
475 <A NAME="IDX989"></A>
476 <A NAME="IDX990"></A>
477 <A NAME="IDX991"></A>
478 <P>Issue the <B>fs setacl</B> command to edit entries in the normal
479 permissions section of the ACL. To remove an entry, specify the
480 <B>none</B> shorthand as the permissions. If an ACL entry already
481 exists for a user or group, the permissions you specify completely replace
482 those in the existing entry.
483 <A NAME="IDX992"></A>
484 <A NAME="IDX993"></A>
485 <PRE>   % <B>fs setacl  -dir</B> &lt;<VAR>directory</VAR>><SUP>+</SUP> <B>-acl</B> &lt;<VAR>access&nbsp;list&nbsp;entries</VAR>><SUP>+</SUP>
486 </PRE>
487 <P>where
488 <DL>
489 <P><DT><B>sa
490 </B><DD>Is an acceptable alias for <B>setacl</B> (and <B>seta</B> is the
491 shortest acceptable abbreviation).
492 <P><DT><B>-dir
493 </B><DD>Names one or more directories to which to apply the ACL entries defined by
494 the <B>-acl</B> argument. Partial pathnames are interpreted
495 relative to the current working directory. You can also use the
496 following notation on its own or as part of a pathname:
497 <DL>
498 <P><DT><B>.
499 </B><DD>(A single period). If used by itself, sets the ACL on the current
500 working directory.
501 <P><DT><B>..
502 </B><DD>(Two periods). If used by itself, sets the ACL on the current
503 working directory's parent directory.
504 <P><DT><B>*
505 </B><DD>(The asterisk). Sets the ACL on each of the subdirectories in the
506 current working directory. You must precede it with the <B>-dir</B>
507 switch, since it potentially designates multiple directories. The
508 <B>fs</B> command interpreter generates the following error message for
509 each file in the directory:
510 <PRE>   fs: '<VAR>filename</VAR>': Not a directory
511 </PRE>
512 </DL>
513 <P>If you specify only one directory (or file) name, you can omit the
514 <B>-dir</B> and <B>-acl</B> switches. For more on omitting
515 switches, see <A HREF="auusg011.htm#HDRWQ86">Appendix B,  AFS Command Syntax and Online Help</A>.
516 <P><DT><B>-acl
517 </B><DD>Specifies one or more ACL entries, each of which pairs a user or group
518 name and a set of permissions. Separate the pairs, and the two parts of
519 each pair, with one or more spaces. 
520 <P>To define the permissions, provide either:
521 <UL>
522 <P><LI>One or more of the letters that represent the standard or auxiliary
523 permissions (<B>rlidwka</B> and <B>ABCDEFGH</B>), in any order
524 <P><LI>One of the four shorthand notations:
525 <UL>
526 <P><LI><B>all</B> (equals <B>rlidwka</B>)
527 <P><LI><B>none</B> (removes the entry)
528 <P><LI><B>read</B> (equals <B>rl</B>)
529 <P><LI><B>write</B> (equals <B>rlidwk</B>)
530 </UL>
531 </UL>
532 <P>On a single command line, you can combine user and group entries.
533 Also, you can both combine individual letters and use the shorthand notations,
534 but not within a single pair.
535 </DL>
536 <P><H3><A NAME="Header_99" HREF="auusg002.htm#ToC_99">Example: Adding a Single ACL Entry</A></H3>
537 <A NAME="IDX994"></A>
538 <P>Either of the following example commands grants user <B>pat</B> the
539 <B>r</B> and <B>l</B> permissions on the ACL of the <B>notes</B>
540 subdirectory of the current working directory. They illustrate how it
541 is possible to omit the <B>-dir</B> and <B>-acl</B> switches when you
542 name only one directory.
543 <PRE>   % <B>fs sa notes pat rl</B>
544    % <B>fs sa pat read</B>
545 </PRE>
546 <P><H3><A NAME="Header_100" HREF="auusg002.htm#ToC_100">Example: Setting Several ACL Entries on One Directory</A></H3>
547 <P>The following example edits the ACL for the current working
548 directory. It removes the entry for the <B>system:anyuser</B>
549 group, and adds two entries: one grants all permissions except
550 <B>a</B> to the members of the <B>terry:colleagues</B> group and
551 the other grants the <B>r</B> and <B>l</B> permissions to the
552 <B>system:authuser</B> group.
553 <PRE>   % <B>fs sa  -dir . -acl  system:anyuser none  terry:colleagues write</B>  \
554             <B>system:authuser rl</B>
555 </PRE>
556 <P><H3><A NAME="HDRWQ56" HREF="auusg002.htm#ToC_101">To Add, Remove, or Edit Negative ACL Permissions</A></H3>
557 <A NAME="IDX995"></A>
558 <A NAME="IDX996"></A>
559 <A NAME="IDX997"></A>
560 <A NAME="IDX998"></A>
561 <A NAME="IDX999"></A>
562 <A NAME="IDX1000"></A>
563 <P>Issue the <B>fs setacl</B> command with the <B>-negative</B> flag
564 to edit entries in the negative permissions section of the ACL. To
565 remove an entry, specify the <B>none</B> shorthand as the
566 permissions. If an ACL entry already exists for a user or group, the
567 permissions you specify completely replace those in the existing entry.
568 <A NAME="IDX1001"></A>
569 <A NAME="IDX1002"></A>
570 <PRE>   % <B>fs setacl  -dir</B> &lt;<VAR>directory</VAR>><SUP>+</SUP> <B>-acl</B> &lt;<VAR>access&nbsp;list&nbsp;entries</VAR>><SUP>+</SUP>  <B>-negative</B> 
571 </PRE>
572 <P>where
573 <DL>
574 <P><DT><B>sa
575 </B><DD>Is an acceptable alias for <B>setacl</B> (and <B>seta</B> is the
576 shortest acceptable abbreviation).
577 <P><DT><B>-dir
578 </B><DD>Names one or more directories to which to apply the negative ACL entries
579 defined by the <B>-acl</B> argument. For a detailed description of
580 acceptable values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>.
581 <P><DT><B>-acl
582 </B><DD>Specifies one or more ACL entries, each of which pairs a user or group
583 name and a set of permissions. Separate the pairs, and the two parts of
584 each pair, with one or more spaces. For a detailed description of
585 acceptable values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>. Keep in mind that the usual meaning of each
586 permission is reversed.
587 <P><DT><B>-negative
588 </B><DD>Places the entries defined by the <B>-acl</B> argument on the negative
589 permissions section of the ACL for each directory named by the <B>-dir</B>
590 argument.
591 </DL>
592 <P><H3><A NAME="Header_102" HREF="auusg002.htm#ToC_102">Example:  Setting an Entry in the Negative Permissions Section</A></H3>
593 <A NAME="IDX1003"></A>
594 <P>User <B>terry</B> has granted all access permissions except
595 <B>a</B> to the group <B>terry:team</B> on her <B>plans</B>
596 subdirectory.
597 <PRE>   % <B>cd /afs/abc.com/usr/terry</B>
598    % <B>fs listacl plans</B>
599    Access control list for plans is
600    Normal rights:
601       system:anyuser rl
602       terry:team rlidwk
603       terry  rlidwka
604 </PRE>
605 <P>However, <B>terry</B> notices that one of the members of the group,
606 user <B>pat</B>, has been making inappropriate changes to files. To
607 prevent this without removing <B>pat</B> from the group or changing the
608 permissions for the <B>terry:team</B> group, <B>terry</B>
609 creates an entry on the negative permissions section of the ACL that denies
610 the <B>w</B> and <B>d</B> permissions to <B>pat</B>:
611 <PRE>   % <B>fs setacl plans pat wd -negative</B>
612    % <B>fs listacl plans</B>
613    Access control list for plans is
614    Normal rights:
615       system:anyuser rl
616       terry:team rlidwk
617       terry: rlidwka
618    Negative rights:
619       pat wd
620 </PRE>
621 <P><H3><A NAME="Header_103" HREF="auusg002.htm#ToC_103">Example: Restoring Access by Removing an Entry from the Negative Permissions Section</A></H3>
622 <P>In the previous example, user <B>terry</B> put <B>pat</B> on
623 the negative permissions section of ACL for the <B>plans</B>
624 subdirectory. But the result has been inconvenient and <B>pat</B>
625 has promised not to change files any more. To enable <B>pat</B> to
626 exercise all permissions granted to the members of the
627 <B>terry:team</B> group, <B>terry</B> removes the entry for
628 <B>pat</B> from the negative permissions section of the ACL.
629 <PRE>   % <B>fs setacl plans pat  none -negative</B>
630    % <B>fs listacl plans</B>
631    Access control list for plans is
632    Normal rights:
633       system:anyuser rl
634       terry:team rlidwk
635       terry  rlidwka
636 </PRE>
637 <HR><H2><A NAME="HDRWQ57" HREF="auusg002.htm#ToC_104">Completely Replacing an ACL</A></H2>
638 <A NAME="IDX1004"></A>
639 <A NAME="IDX1005"></A>
640 <A NAME="IDX1006"></A>
641 <A NAME="IDX1007"></A>
642 <A NAME="IDX1008"></A>
643 <A NAME="IDX1009"></A>
644 <A NAME="IDX1010"></A>
645 <P>It is sometimes simplest to clear an ACL completely before defining new
646 permissions on it, for instance if the mix of normal and negative permissions
647 makes it difficult to understand how their interaction affects access to the
648 directory. To clear an ACL completely while you define new entries,
649 include the <B>-clear</B> flag on the <B>fs setacl</B> command.
650 When you include this flag, you can create entries on either the normal
651 permissions or the negative permissions section of the ACL, but not on both at
652 once.
653 <P>Remember to create an entry for yourself. As the owner of the
654 directory, you always have the <B>a</B> (<B>administer</B>) permission
655 required to replace a deleted entry, but the effects the effects of a missing
656 ACL entry can be confusing enough to make it difficult to realize that the
657 problem is a missing entry. In particular, the lack of the <B>l</B>
658 (<B>lookup</B>) permission prevents you from using any shorthand notation
659 in pathnames (such as a period for the current working directory or two
660 periods for the parent directory).
661 <P><H3><A NAME="Header_105" HREF="auusg002.htm#ToC_105">To Replace an ACL Completely</A></H3>
662 <P>Issue the <B>fs setacl</B> command with the <B>-clear</B> flag
663 to clear the ACL completely before setting either normal or negative
664 permissions. Because you need to grant the owner of the directory all
665 permissions, it is better in most cases to set normal permissions at this
666 point.
667 <A NAME="IDX1011"></A>
668 <PRE>   % <B>fs setacl  -dir</B> &lt;<VAR>directory</VAR>><SUP>+</SUP> <B>-acl</B> &lt;<VAR>access&nbsp;list&nbsp;entries</VAR>><SUP>+</SUP> <B>-clear</B>  [<B>-negative</B>]
669 </PRE>
670 <P>where
671 <DL>
672 <P><DT><B>sa
673 </B><DD>Is an acceptable alias for <B>setacl</B> (and <B>seta</B> is the
674 shortest acceptable abbreviation).
675 <P><DT><B>-dir
676 </B><DD>Names one or more directories to which to apply the ACL entries defined by
677 the <B>-acl</B> argument. For a detailed description of acceptable
678 values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>.
679 <P><DT><B>-acl
680 </B><DD>Specifies one or more ACL entries, each of which pairs a user or group
681 name and a set of permissions. Separate the pairs, and the two parts of
682 each pair, with one or more spaces. Remember to grant all permissions
683 to the owner of the directory. For a detailed description of acceptable
684 values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>.
685 <P><DT><B>-clear
686 </B><DD>Removes all entries from each ACL before creating the entries indicated by
687 the <B>-acl</B> argument.
688 <P><DT><B>-negative
689 </B><DD>Places the entries defined by the <B>-acl</B> argument on the negative
690 permissions section of each ACL.
691 </DL>
692 <P><H3><A NAME="Header_106" HREF="auusg002.htm#ToC_106">Example:  Replacing an ACL</A></H3>
693 <A NAME="IDX1012"></A>
694 <P>The following example clears the ACL on the current working directory and
695 creates entries that grant all permissions to user <B>terry</B> and all
696 permissions except <B>a</B> to user <B>pat</B>.
697 <PRE>   % <B>fs setacl . terry all pat write -clear</B>
698    % <B>fs listacl .</B>
699    Access control list for . is
700    Normal rights:
701      terry rlidwka
702      pat rlidwk
703 </PRE>
704 <HR><H2><A NAME="HDRWQ58" HREF="auusg002.htm#ToC_107">Copying ACLs Between Directories</A></H2>
705 <A NAME="IDX1013"></A>
706 <A NAME="IDX1014"></A>
707 <A NAME="IDX1015"></A>
708 <A NAME="IDX1016"></A>
709 <P>The <B>fs copyacl</B> command copies a source directory's ACL to
710 one or more destination directories. It does not affect the source ACL
711 at all, but changes each destination ACL as follows:
712 <UL>
713 <P><LI>If an entry on the source ACL does not exist on the destination ACL, the
714 command copies it to the destination ACL.
715 <P><LI>If an entry on the destination ACL does not also exist on the source ACL,
716 the command does not remove it unless you include the <B>-clear</B> flag,
717 which overwrites the destination ACL completely.
718 <P><LI>If an entry is on both ACLs, the command changes the destination ACL entry
719 to match the source ACL entry.
720 </UL>
721 <P>To copy an ACL, you must have the <B>l</B> permission on the source ACL
722 and the <B>a</B> permission on each destination ACL. If you
723 identify the source directory by naming a file in it, you must also have the
724 <B>r</B> permission on the source ACL. To display the permissions
725 you have on the two directories, use the <B>fs listacl</B> command as
726 described in <A HREF="#HDRWQ52">Displaying an ACL</A>.
727 <P><B>Note for AFS/DFS Migration Toolkit users:</B> If the machine
728 on which you issue the <B>fs copyacl</B> command is configured for access
729 to a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can
730 use the command to copy ACLs between DFS files and directories also.
731 The command includes <B>-id</B> and <B>-if</B> flags for altering a
732 DFS directory's Initial Container and Initial Object ACLs as well as its
733 regular ACL; for details, ask your system administrator. You
734 cannot copy ACLs between AFS and DFS directories, because they use different
735 ACL formats. The <B>fs</B> command interpreter ignores the
736 <B>-id</B> and <B>-if</B> flags if you include them when copying AFS
737 ACLs.
738 <P><H3><A NAME="Header_108" HREF="auusg002.htm#ToC_108">To Copy an ACL Between Directories</A></H3>
739 <A NAME="IDX1017"></A>
740 <A NAME="IDX1018"></A>
741 <P>Issue the <B>fs copyacl</B> command to copy a source ACL to the ACL on
742 one or more destination directories.
743 <PRE>   % <B>fs copyacl -fromdir</B> &lt;<VAR>source&nbsp;directory</VAR>> <B>-todir</B> &lt;<VAR>destination&nbsp;directory</VAR>><SUP>+</SUP>  \
744                 [<B>-clear</B>]
745 </PRE>
746 <P>where
747 <DL>
748 <P><DT><B>co
749 </B><DD>Is the shortest acceptable abbreviation for <B>copyacl</B>.
750 <P><DT><B>-fromdir
751 </B><DD>Names the source directory from which to copy the ACL. Partial
752 pathnames are interpreted relative to the current working directory. If
753 this argument names a file, the ACL is copied from its directory.
754 <P><DT><B>-todir
755 </B><DD>Names each destination directory to which to copy the source ACL.
756 Partial pathnames are interpreted relative to the current working
757 directory. Filenames are not acceptable.
758 <P><DT><B>-clear
759 </B><DD>Completely overwrites each destination directory's ACL with the
760 source ACL.
761 </DL>
762 <P><H3><A NAME="Header_109" HREF="auusg002.htm#ToC_109">Example:  Copying an ACL from One Directory to Another</A></H3>
763 <A NAME="IDX1019"></A>
764 <P>In this example, user <B>terry</B> copies the ACL from her home
765 directory (the current working directory) to its <B>plans</B>
766 subdirectory. She begins by displaying both ACLs.
767 <PRE>   % <B>fs listacl . plans</B>
768    Access list for . is
769    Normal rights:
770       terry rlidwka
771       pat rlidwk
772       jones rl
773    Access list for plans is
774    Normal rights:
775       terry rlidwka
776       pat rl
777       smith rl   
778      
779   % <B>fs copyacl -from . -to plans</B>
780    
781    % <B>fs listacl . plans</B>
782    Access list for . is
783    Normal rights:
784       terry rlidwka
785       pat rlidwk
786       jones rl
787    Access list for plans is
788    Normal rights:
789       terry rlidwka
790       pat rlidwk
791       jones rl
792       smith rl   
793 </PRE>
794 <HR><H2><A NAME="HDRWQ59" HREF="auusg002.htm#ToC_110">How AFS Uses the UNIX Mode Bits</A></H2>
795 <A NAME="IDX1020"></A>
796 <A NAME="IDX1021"></A>
797 <P>Although AFS protects data primarily with ACLs rather than mode bits, it
798 does not ignore the mode bits entirely. An explanation of how mode bits
799 work in the UNIX file system is outside the scope of this document, and the
800 following discussion assumes you understand them; if necessary, see your
801 UNIX documentation. Also, the following discussion does not cover the
802 setuid, setgid or sticky bits. If you need to understand how those bits
803 work on AFS files, see the <I>IBM AFS Administration Guide</I> or ask your
804 system administrator.
805 <P>AFS uses the UNIX mode bits in the following way:
806 <UL>
807 <P><LI>It uses the initial bit to distinguish files and directories. This
808 is the bit that appears first in the output from the <B>ls -l</B> command
809 and shows the hyphen (<TT>-</TT>) for a file or the letter <TT>d</TT> for
810 a directory.
811 <P><LI>It does not use any of the mode bits on a directory. The AFS ACL
812 alone controls directory access.
813 <P><LI>For a file, the owner (first) set of bits interacts with the ACL entries
814 that apply to the file in the following way. AFS does not use the group
815 or world (second and third sets) of mode bits at all.
816 <UL>
817 <P><LI>If the first <B>r</B> mode bit is not set, no one (including the
818 owner) can read the file, no matter what permissions they have on the
819 ACL. If the bit is set, users also need the <B>r</B> and
820 <B>l</B> permissions on the ACL of the file's directory to read the
821 file.
822 <P><LI>If the first <B>w</B> mode bit is not set, no one (including the
823 owner) can modify the file. If the <B>w</B> bit is set, users also
824 need the <B>w</B> and <B>l</B> permissions on the ACL of the
825 file's directory to modify the file.
826 <P><LI>There is no ACL permission directly corresponding to the <B>x</B> mode
827 bit, but to execute a file stored in AFS, the user must also have the
828 <B>r</B> and <B>l</B> permissions on the ACL of the file's
829 directory.
830 </UL>
831 </UL>
832 <P>When you issue the UNIX <B>chmod</B> command on an AFS file or
833 directory, AFS changes the bits appropriately. To change a file's
834 mode bits, you must have the AFS <B>w</B> permission on the ACL of the
835 file's directory. To change a directory's mode bits, you must
836 have the <B>d</B>, <B>i</B>, and <B>l</B> permissions on its
837 ACL.
838 <A NAME="IDX1022"></A>
839 <A NAME="IDX1023"></A>
840 <P><H3><A NAME="Header_111" HREF="auusg002.htm#ToC_111">Example:  Disabling Write Access for a File</A></H3>
841 <P><B></B>
842 <A NAME="IDX1024"></A>
843 <P>Suppose <B>terry</B> is chairing a committee that is writing a
844 proposal. As each section is approved, she turns off write access to
845 that file to prevent further changes. For example, the following
846 <B>chmod</B> command turns off the <B>w</B> mode bits on the file
847 <B>proposal.chap2</B>. This makes it impossible for anyone
848 to change the file, no matter what permissions are granted on the directory
849 ACL.
850 <PRE>   % <B>chmod -w proposal.chap2</B>
851    % <B>ls -l</B>
852    -rw-r--r--  1 terry     573 Nov 10 09:57 conclusion
853    -r--r--r--  1 terry     573 Nov 15 10:34 intro
854    -r--r--r--  1 terry     573 Dec  1 15:07 proposal.chap2
855    -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap3
856    -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap4
857 </PRE>
858 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auusg002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auusg006.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auusg008.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auusg013.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P> 
859 <!-- Begin Footer Records  ========================================== -->
860 <P><HR><B> 
861 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved 
862 </B> 
863 <!-- End Footer Records  ============================================ -->
864 <A NAME="Bot_Of_Page"></A>
865 </BODY></HTML>