File: auusg007.htm

package info (click to toggle)
openafs 1.4.2-6etch3
links: PTS
area: main
in suites: etch
size: 42,324 kB
ctags: 55,614
sloc: ansic: 397,846; sh: 10,033; makefile: 9,203; perl: 7,679; java: 5,633; asm: 1,276; yacc: 983; lex: 318; tcl: 249; objc: 137; csh: 123
file content (865 lines) | stat: -rw-r--r-- 44,035 bytes
parent folder | download | duplicates (5)
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
<HTML><HEAD>
<TITLE>User Guide</TITLE>
<!-- Begin Header Records  ========================================== -->
<!-- /tmp/idwt3629/auusg000.scr converted by idb2h R4.2 (359) ID      -->
<!-- Workbench Version (AIX) on 2 Oct 2000 at 14:38:44                -->
<META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 14:38:42">
<META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 14:38:42">
<META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 14:38:42">
</HEAD><BODY>
<!-- (C) IBM Corporation 2000. All Rights Reserved    --> 
<BODY bgcolor="ffffff"> 
<!-- End Header Records  ============================================ -->
<A NAME="Top_Of_Page"></A>
<H1>User Guide</H1>
<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> 
<HR><H1><A NAME="HDRWQ44" HREF="auusg002.htm#ToC_79">Protecting Your Directories and Files</A></H1>
<P>This chapter explains how to protect AFS files and
directories by defining permissions on an access control list.
<HR><H2><A NAME="HDRWQ45" HREF="auusg002.htm#ToC_80">Access Control Lists</A></H2>
<A NAME="IDX924"></A>
<A NAME="IDX925"></A>
<A NAME="IDX926"></A>
<A NAME="IDX927"></A>
<A NAME="IDX928"></A>
<P>AFS augments and refines the standard UNIX scheme for controlling access to
files and directories. Instead of using mode bits to define access
permissions for individual files, as UNIX does, AFS stores an <I>access
control list</I> (<I>ACL</I>) with each directory. It defines
which users and groups can access the directory and the files it contains, and
in what manner. An ACL can store up to about 20 entries, each of which
pairs a user or group and a set of permissions. AFS defines seven
permissions rather than the three that UNIX uses.
<P>Another refinement to the standard UNIX protection scheme is that users can
define their own protection <I>groups</I> and then place the groups on
ACLs as though they were individual users. A group can include both
users and machines. Each user who belongs to a group inherits all of
the permissions granted to the group on the ACL. Similarly, all users
who are logged into a machine that belongs to a group inherits all of the
permissions granted to the group. You can create groups to place on
ACLs and also use groups that other users have created. To learn more
about group creation, see <A HREF="auusg008.htm#HDRWQ60">Using Groups</A>.
<P>In addition, AFS defines two system groups called
<B>system:anyuser</B> and <B>system:authuser</B>.
By placing them on ACLs, you can grant access to large numbers of users at
once. See <A HREF="#HDRWQ50">Using the System Groups on ACLs</A>.
<P>Although AFS uses ACLs to protect files and directories, it also uses the
UNIX mode bits to a limited extent. See <A HREF="#HDRWQ59">How AFS Uses the UNIX Mode Bits</A>.
<P><H3><A NAME="Header_81" HREF="auusg002.htm#ToC_81">Directory Level Access Control</A></H3>
<P>As noted, AFS associates an ACL with each directory, and it applies to
all of the files stored in the directory. Files do not have separate
ACLs. Defining access at the directory level has several
consequences:
<UL>
<P><LI>The permissions on a directory's ACL apply to all of the files in the
directory. When you move a file to a different directory, you
effectively change its permissions to those on its new directory's
ACL. Changing a directory's ACL changes the protection on all the
files in it.
<P><LI>When you create a subdirectory, it inherits the current ACL of its parent
directory. You can then set the subdirectory's ACL to be different
from its parent's. However, do not make the ACL on the parent
directory more restrictive than on a subdirectory, because that can prevent
users from accessing the subdirectory even when they have the necessary
permissions on its ACL. Specifically, a user must have the <B>l</B>
(<B>lookup</B>) permission (defined in <A HREF="#HDRWQ46">The AFS ACL Permissions</A>) on the parent directory to reach its subdirectories.
<A NAME="IDX929"></A>
<A NAME="IDX930"></A>
</UL>
<P>As a general rule, it makes sense to grant fairly liberal access to your
home directory. If you need to protect certain files more closely,
place them in subdirectories that have more restrictive ACLs.
<HR><H2><A NAME="HDRWQ46" HREF="auusg002.htm#ToC_82">The AFS ACL Permissions</A></H2>
<A NAME="IDX931"></A>
<A NAME="IDX932"></A>
<A NAME="IDX933"></A>
<P>There are seven standard AFS ACL permissions. Functionally, they
fall into two groups: one that applies to the directory itself and one
that applies to the files.
<P><H3><A NAME="HDRWQ47" HREF="auusg002.htm#ToC_83">The Four Directory Permissions</A></H3>
<P>The four permissions in this group are meaningful with
respect to the directory itself. For example, the <B>i</B>
(<B>insert</B>) permission does not control addition of data to a file,
but rather creation of a new file or subdirectory.
<DL>
<P><DT><B>The l (lookup) permission
</B><DD>This permission functions as something of a gate keeper for access to the
directory and its files, because a user must have it in order to exercise any
other permissions. In particular, a user must have this permission to
access anything in the directory's subdirectories.
<A NAME="IDX934"></A>
<A NAME="IDX935"></A>
<P>This permission enables a user to issue the following commands:
<UL>
<P><LI>The <B>ls</B> command to list the names of the files and
subdirectories in the directory
<P><LI>The <B>ls -ld</B> command to obtain complete status information for
the directory element itself
<P><LI>The <B>fs listacl</B> command to examine the directory's ACL
</UL>
<P>This permission does not enable a user to read the contents of a file in
the directory or to issue the <B>ls -l</B> or <B>fs listacl</B>
commands with a filename as the argument. Those operations require the
<B>r</B> (<B>read</B>) permission, which is described in <A HREF="#HDRWQ48">The Three File Permissions</A>.
<P>Similarly, this permission does not enable a user to issue the
<B>ls</B>, <B>ls -l</B>, <B>ls -ld</B>, or <B>fs listacl</B>
commands against a subdirectory of the directory. Those operations
require the <B>l</B> permission on the ACL of the subdirectory
itself.
<P><DT><B>The i (insert) permission
</B><DD>This permission enables a user to add new files to the directory, either
by creating or copying, and to create new subdirectories. It does not
extend into any subdirectories, which are protected by their own ACLs.
<A NAME="IDX936"></A>
<A NAME="IDX937"></A>
<P><DT><B>The d (delete) permission
</B><DD>This permission enables a user to remove files and subdirectories from the
directory or move them into other directories (assuming that the user has the
<B>i</B> permission on the ACL of the other directories).
<A NAME="IDX938"></A>
<A NAME="IDX939"></A>
<P><DT><B>The a (administer) permission
</B><DD>This permission enables a user to change the directory's ACL.
Members of the <B>system:administrators</B> group implicitly have
this permission on every directory (that is, even if that group does not
appear on the ACL). Similarly, the owner of a directory implicitly has
this permission on its ACL and those of all directories below it.
<A NAME="IDX940"></A>
<A NAME="IDX941"></A>
</DL>
<P><H3><A NAME="HDRWQ48" HREF="auusg002.htm#ToC_84">The Three File Permissions</A></H3>
<P>The three permissions in this group are meaningful with
respect to files in a directory, rather than the directory itself or its
subdirectories.
<DL>
<P><DT><B>The r (read) permission
</B><DD>This permission enables a user to read the contents of files in the
directory and to issue the <B>ls -l</B> command to stat the file
elements.
<A NAME="IDX942"></A>
<A NAME="IDX943"></A>
<P><DT><B>The w (write) permission
</B><DD>This permission enables a user to modify the contents of files in the
directory and to issue the <B>chmod</B> command to change their UNIX mode
bits.
<A NAME="IDX944"></A>
<A NAME="IDX945"></A>
<P><DT><B>The k (lock) permission
</B><DD>This permission enables a user to run programs that issue system calls to
lock files in the directory. 
<A NAME="IDX946"></A>
<A NAME="IDX947"></A>
</DL>
<P><H3><A NAME="Header_85" HREF="auusg002.htm#ToC_85">The Eight Auxiliary Permissions</A></H3>
<A NAME="IDX948"></A>
<A NAME="IDX949"></A>
<P>AFS provides eight additional permissions that do not have a defined
meaning. They are denoted by the uppercase letters <B>A</B>,
<B>B</B>, <B>C</B>, <B>D</B>, <B>E</B>, <B>F</B>,
<B>G</B>, and <B>H</B>.
<P>Your system administrator can choose to write application programs that
assign a meaning to one or more of the permissions, and then place them on
ACLs to control file access by those programs. Use the <B>fs
listacl</B> and <B>fs setacl</B> commands to display and set the
auxiliary permissions on ACLs just like the standard seven.
<P><H3><A NAME="Header_86" HREF="auusg002.htm#ToC_86">Shorthand Notation for Sets of Permissions</A></H3>
<A NAME="IDX950"></A>
<A NAME="IDX951"></A>
<A NAME="IDX952"></A>
<P>You can combine the seven permissions in any way in an ACL entry, but
certain combinations are more useful than others. Four of the more
common combinations have corresponding shorthand forms. When using the
<B>fs setacl</B> command to define ACL entries, you can provide either one
or more of the individual letters that represent the permissions, or one of
the following shorthand forms:
<DL>
<P><DT><B>all
</B><DD>Represents all seven standard permissions (<B>rlidwka</B>)
<A NAME="IDX953"></A>
<P><DT><B>none
</B><DD>Removes the entry from the ACL, leaving the user or group with no
permission 
<A NAME="IDX954"></A>
<P><DT><B>read
</B><DD>Represents the <B>r</B> (<B>read</B>) and <B>l</B>
(<B>lookup</B>) permissions
<A NAME="IDX955"></A>
<P><DT><B>write
</B><DD>Represents all permissions except <B>a</B>
(<B>administer</B>): <B>rlidwk</B>
<A NAME="IDX956"></A>
</DL>
<P><H3><A NAME="HDRWQ49" HREF="auusg002.htm#ToC_87">About Normal and Negative Permissions</A></H3>
<A NAME="IDX957"></A>
<A NAME="IDX958"></A>
<A NAME="IDX959"></A>
<A NAME="IDX960"></A>
<A NAME="IDX961"></A>
<A NAME="IDX962"></A>
<A NAME="IDX963"></A>
<P>ACLs enable you both to grant and to deny access to a directory and the
files in it. To grant access, use the <B>fs setacl</B> command to
create an ACL entry that associates a set of permissions with a user or group,
as described in <A HREF="#HDRWQ54">Changing an ACL</A>. When you use the <B>fs listacl</B> command to
display an ACL (as described in <A HREF="#HDRWQ52">Displaying an ACL</A>), such entries appear underneath the following header, which
uses the term <I>rights</I> to refer to permissions:
<PRE>   Normal rights
</PRE>
<P>There are two ways to deny access:
<A NAME="IDX964"></A>
<OL TYPE=1>
<P><LI>The recommended method is simply to omit an entry for the user or group
from the ACL, or to omit the appropriate permissions from an entry. Use
the <B>fs setacl</B> command to remove or edit an existing entry.
In most cases, this method is enough to prevent access of certain kinds or by
certain users. You must take care, however, not to grant the undesired
permissions to any groups to which such users belong.
<P><LI>The more explicit method for denying access is to place an entry on the
<I>negative permissions</I> section of an ACL, by including the
<B>-negative</B> flag to the <B>fs setacl</B> command. For
instructions, see <A HREF="#HDRWQ56">To Add, Remove, or Edit Negative ACL Permissions</A>. The <B>fs listacl</B> command displays the
negative permissions section of an ACL underneath the following header: 
<PRE>   Negative rights
</PRE>
<P>When determining what type of access to grant to a user, AFS first examines
all of the entries in the normal permissions section of the ACL. It
then subtracts any permissions associated with the user (or with groups to
which the user belongs) on the negative permissions section of the ACL.
Therefore, negative permissions always cancel out normal permissions.
<P>Negative permissions can be confusing, because they reverse the usual
meaning of the <B>fs setacl</B> command. In particular, combining
the <B>none</B> shorthand and the <B>-negative</B> flag is a double
negative: by removing an entry from the negative permissions section of
the ACL, you enable a user once again to obtain permissions via entries in the
normal permissions section. Combining the <B>all</B> shorthand with
the <B>-negative</B> flag explicitly denies all permissions.
<P>It is useless to create an entry in the negative permissions section if an
entry in the normal permissions section grants the denied permissions to the
<B>system:anyuser</B> group. In this case, users can obtain
the permissions simply by using the <B>unlog</B> command to discard their
tokens. When they do so, AFS recognizes them as the
<B>anonymous</B> user, who belongs to the <B>system:anyuser</B>
group but does not match the entries on the negative permissions section of
the ACL.
</OL>
<P><H3><A NAME="Header_88" HREF="auusg002.htm#ToC_88">Setting DFS ACLs</A></H3>
<P>If your machine is configured to access a DCE cell's DFS filespace
via the AFS/DFS Migration Toolkit, then you can use the AFS <B>fs
listacl</B> and <B>fs setacl</B> commands to display and set the ACLs on
DFS directories and files that you own. However, DFS uses a slightly
different set of permissions and a different syntax for ACL entries.
See the DFS documentation or ask your system administrator.
<HR><H2><A NAME="HDRWQ50" HREF="auusg002.htm#ToC_89">Using the System Groups on ACLs</A></H2>
<P>
<A NAME="IDX965"></A>
<A NAME="IDX966"></A>
<A NAME="IDX967"></A>
<A NAME="IDX968"></A>
AFS defines two <I>system groups</I> that grant access to a large number
of users at once when placed on an ACL. However, you cannot control the
membership of these groups, so consider carefully what kind of permissions you
wish to give them. (You do control the membership of the groups you
own; see <A HREF="auusg008.htm#HDRWQ60">Using Groups</A>.)
<DL>
<P><DT><B>system:anyuser
</B><DD>Includes anyone who can access the cell's file tree, including users
who have tokens in the local cell, users who have logged in on a local AFS
client machine but have not obtained tokens (such as the local superuser
<B>root</B>), and users who have connected to a local machine from outside
the cell. Creating an ACL entry for this group is the only way to
extend access to AFS users from foreign cells, unless your system
administrator creates local authentication accounts for them.
<A NAME="IDX969"></A>
<P><DT><B>system:authuser
</B><DD>Includes all users who have a valid AFS token obtained from the local
cell's AFS authentication service.
</DL>
<P>The third system group, <B>system:administrators</B>, includes a
small group of administrators who have extensive permissions in the
cell. You do not generally need to put this group on your ACLs, because
its members always have the <B>a</B> (<B>administer</B>) permission on
every ACL, even if the group does not appear on it.
<P><H3><A NAME="Header_90" HREF="auusg002.htm#ToC_90">Enabling Access to Subdirectories</A></H3>
<A NAME="IDX970"></A>
<A NAME="IDX971"></A>
<P>A user must have the <B>l</B> permission on a directory to access its
subdirectories in any way. Even if users have extensive permissions on
a subdirectory, they cannot access it if the parent directory's ACL does
not grant the <B>l</B> permission.
<P>You can grant the <B>l</B> permission in one of three ways: grant
it to a system group (<B>system:anyuser</B> or
<B>system:authuser</B>), grant it to individual users, or grant it
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
<B>system:anyuser</B> group is the easiest option and is generally
secure because the permission only enables users to list the contents of the
directory, not to read the files in it. If you want to enable only
locally authenticated users to list a directory's contents, substitute
the <B>system:authuser</B> group for the
<B>system:anyuser</B> group. Your system administrator has
possibly already created an entry on your home directory's ACL that
grants the <B>r</B> and <B>l</B> permissions to the
<B>system:anyuser</B> group.
<P><H3><A NAME="Header_91" HREF="auusg002.htm#ToC_91">Extending Access to Service Processes</A></H3>
<A NAME="IDX972"></A>
<P>It is sometimes necessary to grant more extensive permissions to the
<B>system:anyuser</B> group so that processes that provide printing
and mail delivery service can work correctly. For example, printing
processes sometimes need the <B>r</B> permission in addition to the
<B>l</B> permission. A mail delivery process possibly needs the
<B>i</B> permission to place new messages in your mail directory.
Your system administrator has probably already created the necessary ACL
entries. If you notice an ACL entry for which the purpose is unclear,
check with your system administrator before removing it.
<P><H3><A NAME="HDRWQ51" HREF="auusg002.htm#ToC_92">Extending Access to Users from Foreign Cells</A></H3>
<P>
<A NAME="IDX973"></A>
 The only way to grant access to users from foreign cells who do not have an
account in your cell is to put the <B>system:anyuser</B> group on an
ACL. Remember, however, that such an entry extends access to everyone
who can reach your cell, not just the AFS users from foreign cells that you
have in mind.
<HR><H2><A NAME="HDRWQ52" HREF="auusg002.htm#ToC_93">Displaying an ACL</A></H2>
<A NAME="IDX974"></A>
<A NAME="IDX975"></A>
<A NAME="IDX976"></A>
<P>To display the ACL associated with a file or directory, issue the <B>fs
listacl</B> command.
<P><B>Note for AFS/DFS Migration Toolkit users:</B> If the machine
on which you issue the <B>fs listacl</B> command is configured to access a
DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use
the command to display the ACL on DFS files and directories. To display
a DFS directory's Initial Container or Initial Object ACL instead of the
regular one, include the <B>fs listacl</B> command's <B>-id</B>
or <B>-if</B> flag. For more information, ask your system
administrator. The <B>fs</B> command interpreter ignores the
<B>-id</B> and <B>-if</B> flags if you include them when displaying an
AFS ACL.
<P><H3><A NAME="HDRWQ53" HREF="auusg002.htm#ToC_94">To display an ACL</A></H3>
<OL TYPE=1>
<P><LI>Issue the <B>fs listacl</B> command. 
<A NAME="IDX977"></A>
<A NAME="IDX978"></A>
<PRE>   % <B>fs listacl</B> [&lt;<VAR>dir/file&nbsp;path</VAR>><SUP>+</SUP>]
</PRE>
<P>where
<DL>
<P><DT><B>la
</B><DD>Is an acceptable alias for <B>listacl</B> (and <B>lista</B> is the
shortest acceptable abbreviation).
<P><DT><B><VAR>dir/file path</VAR>
</B><DD>Names one or more files or directories for which to display the
ACL. For a file, the output displays the ACL on its directory.
If you omit this argument, the output is for the current working
directory. Partial pathnames are interpreted relative to the current
working directory. You can also use the following notation on its own
or as part of a pathname:
<DL>
<P><DT><B>.
</B><DD>(A single period). Specifies the current working directory.
<P><DT><B>..
</B><DD>(Two periods). Specifies the current working directory's
parent directory.
<P><DT><B>*
</B><DD>(The asterisk). Specifies each file and subdirectory in the current
working directory. The ACL displayed for a file is always the same as
for its directory, but the ACL for each subdirectory can differ.
</DL>
</DL>
</OL>
<P>The output for each file or directory specified as <VAR>dir/file path</VAR>
begins with the following header to identify it:
<PRE>   Access list for  <VAR>dir/file&nbsp;path</VAR> is
</PRE>
<P>The <TT>Normal rights</TT> header appears on the next line, followed by
lines that each pair a user or group name and a set of permissions. The
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
are any negative permissions, the <TT>Negative rights</TT> header appears
next, followed by pairs of negative permissions.
<P>If the following error message appears instead of an ACL, you do not have
the permissions needed to display an ACL. To specify a directory name
as the <VAR>dir/file path</VAR> argument, you must have the <B>l</B>
(<B>lookup</B>) permission on the ACL. To specify a filename, you
must also have the <B>r</B> (<B>read</B>) permission on its
directory's ACL.
<PRE>   fs: You don't have the required access permissions on '<VAR>dir/file&nbsp;path</VAR>'
</PRE>
<P><H3><A NAME="Header_95" HREF="auusg002.htm#ToC_95">Example: Displaying the ACL on One Directory</A></H3>
<A NAME="IDX979"></A>
<P>The following example displays the ACL on user <B>terry</B>'s home
directory in the ABC Corporation cell:
<PRE>   % <B>fs la /afs/abc.com/usr/terry</B>
   Access list for /afs/abc.com/usr/terry is
   Normal rights:
      system:authuser rl
      pat rlw
      terry rlidwka
   Negative rights:
      terry:other-dept rl
      jones rl
</PRE>
<P>where <B>pat</B>, <B>terry</B>, and <B>jones</B> are individual
users, <B>system:authuser</B> is a system group, and
<B>terry:other-dept</B> is a group that <B>terry</B>
owns. The list of normal permissions grants all permissions to
<B>terry</B>, the <B>rlw</B> permissions to <B>pat</B>, and the
<B>rl</B> permissions to the members of the
<B>system:authuser</B> group.
<P>The list of negative permissions denies the <B>rl</B> permissions to
<B>jones</B> and the members of the <B>terry:other-dept</B>
group. These entries effectively prevent them from accessing
<B>terry</B>'s home directory in any way; they cancel out the
<B>rl</B> permissions extended to the <B>system:authuser</B>
group, which is the only entry on the normal permissions section of the ACL
that possibly applies to them.
<P><H3><A NAME="Header_96" HREF="auusg002.htm#ToC_96">Example:  Displaying the ACLs on Multiple Directories</A></H3>
<A NAME="IDX980"></A>
<P>The following example illustrates how you can specify pathnames in
different ways, and the appearance of the output for multiple
directories. It displays the ACL for three directories: the
current working directory (which is a subdirectory of user
<B>terry</B>'s home directory), the home directory for user
<B>pat</B>, and another subdirectory of <B>terry</B>'s home
directory called <B>plans</B>.
<PRE>   % <B>fs listacl  .  /afs/abc.com/usr/pat  ../plans</B>
   Access list for . is
   Normal rights:
      system:anyuser rl
      pat:dept rliw
   Access list for /afs/abc.com/usr/pat is
   Normal rights:
      system:anyuser rl
      pat rlidwka
      terry rliw 
   Access list for ../plans is
   Normal rights:
      terry rlidwka
      pat rlidw
</PRE>
<HR><H2><A NAME="HDRWQ54" HREF="auusg002.htm#ToC_97">Changing an ACL</A></H2>
<A NAME="IDX981"></A>
<A NAME="IDX982"></A>
<A NAME="IDX983"></A>
<A NAME="IDX984"></A>
<P>To add, remove, or edit ACL entries, use the <B>fs setacl</B>
command. By default, the command manipulates entries on the normal
permissions section of the ACL. To manipulate entries on the negative
permissions section, include the <B>-negative</B> flag as instructed in <A HREF="#HDRWQ56">To Add, Remove, or Edit Negative ACL Permissions</A>.
<P>You can change any ACL on which you already have the <B>a</B>
permission. You always have the <B>a</B> permission on the ACL of
every directory that you own, even if you accidentally remove that permission
from the ACL. (The <B>ls -ld</B> command reports a directory's
owner.) Your system administrator normally designates you as the owner
of your home directory and its subdirectories, and you possibly own other
directories also.
<P>If an ACL entry already exists for the user or group you specify, then the
new permissions completely replace the existing permissions rather than being
added to them. In other words, when issuing the <B>fs setacl</B>
command, you must include all permissions that you want to grant to a user or
group.
<P><B>Note for AFS/DFS Migration Toolkit users:</B> If the machine
on which you issue the <B>fs setacl</B> command is configured to access a
DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can use
the command to set the ACL on DFS files and directories. To set a DFS
directory's Initial Container or Initial Object ACL instead of the
regular one, include the <B>fs setacl</B> command's <B>-id</B> or
<B>-if</B> flag. For more information, ask your system
administrator. The <B>fs</B> command interpreter ignores the
<B>-id</B> and <B>-if</B> flags if you include them when setting an
AFS ACL.
<P><H3><A NAME="HDRWQ55" HREF="auusg002.htm#ToC_98">To Add, Remove, or Edit Normal ACL Permissions</A></H3>
<A NAME="IDX985"></A>
<A NAME="IDX986"></A>
<A NAME="IDX987"></A>
<A NAME="IDX988"></A>
<A NAME="IDX989"></A>
<A NAME="IDX990"></A>
<A NAME="IDX991"></A>
<P>Issue the <B>fs setacl</B> command to edit entries in the normal
permissions section of the ACL. To remove an entry, specify the
<B>none</B> shorthand as the permissions. If an ACL entry already
exists for a user or group, the permissions you specify completely replace
those in the existing entry.
<A NAME="IDX992"></A>
<A NAME="IDX993"></A>
<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>
</PRE>
<P>where
<DL>
<P><DT><B>sa
</B><DD>Is an acceptable alias for <B>setacl</B> (and <B>seta</B> is the
shortest acceptable abbreviation).
<P><DT><B>-dir
</B><DD>Names one or more directories to which to apply the ACL entries defined by
the <B>-acl</B> argument. Partial pathnames are interpreted
relative to the current working directory. You can also use the
following notation on its own or as part of a pathname:
<DL>
<P><DT><B>.
</B><DD>(A single period). If used by itself, sets the ACL on the current
working directory.
<P><DT><B>..
</B><DD>(Two periods). If used by itself, sets the ACL on the current
working directory's parent directory.
<P><DT><B>*
</B><DD>(The asterisk). Sets the ACL on each of the subdirectories in the
current working directory. You must precede it with the <B>-dir</B>
switch, since it potentially designates multiple directories. The
<B>fs</B> command interpreter generates the following error message for
each file in the directory:
<PRE>   fs: '<VAR>filename</VAR>': Not a directory
</PRE>
</DL>
<P>If you specify only one directory (or file) name, you can omit the
<B>-dir</B> and <B>-acl</B> switches. For more on omitting
switches, see <A HREF="auusg011.htm#HDRWQ86">Appendix B,  AFS Command Syntax and Online Help</A>.
<P><DT><B>-acl
</B><DD>Specifies one or more ACL entries, each of which pairs a user or group
name and a set of permissions. Separate the pairs, and the two parts of
each pair, with one or more spaces. 
<P>To define the permissions, provide either:
<UL>
<P><LI>One or more of the letters that represent the standard or auxiliary
permissions (<B>rlidwka</B> and <B>ABCDEFGH</B>), in any order
<P><LI>One of the four shorthand notations:
<UL>
<P><LI><B>all</B> (equals <B>rlidwka</B>)
<P><LI><B>none</B> (removes the entry)
<P><LI><B>read</B> (equals <B>rl</B>)
<P><LI><B>write</B> (equals <B>rlidwk</B>)
</UL>
</UL>
<P>On a single command line, you can combine user and group entries.
Also, you can both combine individual letters and use the shorthand notations,
but not within a single pair.
</DL>
<P><H3><A NAME="Header_99" HREF="auusg002.htm#ToC_99">Example: Adding a Single ACL Entry</A></H3>
<A NAME="IDX994"></A>
<P>Either of the following example commands grants user <B>pat</B> the
<B>r</B> and <B>l</B> permissions on the ACL of the <B>notes</B>
subdirectory of the current working directory. They illustrate how it
is possible to omit the <B>-dir</B> and <B>-acl</B> switches when you
name only one directory.
<PRE>   % <B>fs sa notes pat rl</B>
   % <B>fs sa pat read</B>
</PRE>
<P><H3><A NAME="Header_100" HREF="auusg002.htm#ToC_100">Example: Setting Several ACL Entries on One Directory</A></H3>
<P>The following example edits the ACL for the current working
directory. It removes the entry for the <B>system:anyuser</B>
group, and adds two entries: one grants all permissions except
<B>a</B> to the members of the <B>terry:colleagues</B> group and
the other grants the <B>r</B> and <B>l</B> permissions to the
<B>system:authuser</B> group.
<PRE>   % <B>fs sa  -dir . -acl  system:anyuser none  terry:colleagues write</B>  \
            <B>system:authuser rl</B>
</PRE>
<P><H3><A NAME="HDRWQ56" HREF="auusg002.htm#ToC_101">To Add, Remove, or Edit Negative ACL Permissions</A></H3>
<A NAME="IDX995"></A>
<A NAME="IDX996"></A>
<A NAME="IDX997"></A>
<A NAME="IDX998"></A>
<A NAME="IDX999"></A>
<A NAME="IDX1000"></A>
<P>Issue the <B>fs setacl</B> command with the <B>-negative</B> flag
to edit entries in the negative permissions section of the ACL. To
remove an entry, specify the <B>none</B> shorthand as the
permissions. If an ACL entry already exists for a user or group, the
permissions you specify completely replace those in the existing entry.
<A NAME="IDX1001"></A>
<A NAME="IDX1002"></A>
<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> 
</PRE>
<P>where
<DL>
<P><DT><B>sa
</B><DD>Is an acceptable alias for <B>setacl</B> (and <B>seta</B> is the
shortest acceptable abbreviation).
<P><DT><B>-dir
</B><DD>Names one or more directories to which to apply the negative ACL entries
defined by the <B>-acl</B> argument. For a detailed description of
acceptable values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>.
<P><DT><B>-acl
</B><DD>Specifies one or more ACL entries, each of which pairs a user or group
name and a set of permissions. Separate the pairs, and the two parts of
each pair, with one or more spaces. For a detailed description of
acceptable values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>. Keep in mind that the usual meaning of each
permission is reversed.
<P><DT><B>-negative
</B><DD>Places the entries defined by the <B>-acl</B> argument on the negative
permissions section of the ACL for each directory named by the <B>-dir</B>
argument.
</DL>
<P><H3><A NAME="Header_102" HREF="auusg002.htm#ToC_102">Example:  Setting an Entry in the Negative Permissions Section</A></H3>
<A NAME="IDX1003"></A>
<P>User <B>terry</B> has granted all access permissions except
<B>a</B> to the group <B>terry:team</B> on her <B>plans</B>
subdirectory.
<PRE>   % <B>cd /afs/abc.com/usr/terry</B>
   % <B>fs listacl plans</B>
   Access control list for plans is
   Normal rights:
      system:anyuser rl
      terry:team rlidwk
      terry  rlidwka
</PRE>
<P>However, <B>terry</B> notices that one of the members of the group,
user <B>pat</B>, has been making inappropriate changes to files. To
prevent this without removing <B>pat</B> from the group or changing the
permissions for the <B>terry:team</B> group, <B>terry</B>
creates an entry on the negative permissions section of the ACL that denies
the <B>w</B> and <B>d</B> permissions to <B>pat</B>:
<PRE>   % <B>fs setacl plans pat wd -negative</B>
   % <B>fs listacl plans</B>
   Access control list for plans is
   Normal rights:
      system:anyuser rl
      terry:team rlidwk
      terry: rlidwka
   Negative rights:
      pat wd
</PRE>
<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>
<P>In the previous example, user <B>terry</B> put <B>pat</B> on
the negative permissions section of ACL for the <B>plans</B>
subdirectory. But the result has been inconvenient and <B>pat</B>
has promised not to change files any more. To enable <B>pat</B> to
exercise all permissions granted to the members of the
<B>terry:team</B> group, <B>terry</B> removes the entry for
<B>pat</B> from the negative permissions section of the ACL.
<PRE>   % <B>fs setacl plans pat  none -negative</B>
   % <B>fs listacl plans</B>
   Access control list for plans is
   Normal rights:
      system:anyuser rl
      terry:team rlidwk
      terry  rlidwka
</PRE>
<HR><H2><A NAME="HDRWQ57" HREF="auusg002.htm#ToC_104">Completely Replacing an ACL</A></H2>
<A NAME="IDX1004"></A>
<A NAME="IDX1005"></A>
<A NAME="IDX1006"></A>
<A NAME="IDX1007"></A>
<A NAME="IDX1008"></A>
<A NAME="IDX1009"></A>
<A NAME="IDX1010"></A>
<P>It is sometimes simplest to clear an ACL completely before defining new
permissions on it, for instance if the mix of normal and negative permissions
makes it difficult to understand how their interaction affects access to the
directory. To clear an ACL completely while you define new entries,
include the <B>-clear</B> flag on the <B>fs setacl</B> command.
When you include this flag, you can create entries on either the normal
permissions or the negative permissions section of the ACL, but not on both at
once.
<P>Remember to create an entry for yourself. As the owner of the
directory, you always have the <B>a</B> (<B>administer</B>) permission
required to replace a deleted entry, but the effects the effects of a missing
ACL entry can be confusing enough to make it difficult to realize that the
problem is a missing entry. In particular, the lack of the <B>l</B>
(<B>lookup</B>) permission prevents you from using any shorthand notation
in pathnames (such as a period for the current working directory or two
periods for the parent directory).
<P><H3><A NAME="Header_105" HREF="auusg002.htm#ToC_105">To Replace an ACL Completely</A></H3>
<P>Issue the <B>fs setacl</B> command with the <B>-clear</B> flag
to clear the ACL completely before setting either normal or negative
permissions. Because you need to grant the owner of the directory all
permissions, it is better in most cases to set normal permissions at this
point.
<A NAME="IDX1011"></A>
<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>]
</PRE>
<P>where
<DL>
<P><DT><B>sa
</B><DD>Is an acceptable alias for <B>setacl</B> (and <B>seta</B> is the
shortest acceptable abbreviation).
<P><DT><B>-dir
</B><DD>Names one or more directories to which to apply the ACL entries defined by
the <B>-acl</B> argument. For a detailed description of acceptable
values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>.
<P><DT><B>-acl
</B><DD>Specifies one or more ACL entries, each of which pairs a user or group
name and a set of permissions. Separate the pairs, and the two parts of
each pair, with one or more spaces. Remember to grant all permissions
to the owner of the directory. For a detailed description of acceptable
values, see <A HREF="#HDRWQ55">To Add, Remove, or Edit Normal ACL Permissions</A>.
<P><DT><B>-clear
</B><DD>Removes all entries from each ACL before creating the entries indicated by
the <B>-acl</B> argument.
<P><DT><B>-negative
</B><DD>Places the entries defined by the <B>-acl</B> argument on the negative
permissions section of each ACL.
</DL>
<P><H3><A NAME="Header_106" HREF="auusg002.htm#ToC_106">Example:  Replacing an ACL</A></H3>
<A NAME="IDX1012"></A>
<P>The following example clears the ACL on the current working directory and
creates entries that grant all permissions to user <B>terry</B> and all
permissions except <B>a</B> to user <B>pat</B>.
<PRE>   % <B>fs setacl . terry all pat write -clear</B>
   % <B>fs listacl .</B>
   Access control list for . is
   Normal rights:
     terry rlidwka
     pat rlidwk
</PRE>
<HR><H2><A NAME="HDRWQ58" HREF="auusg002.htm#ToC_107">Copying ACLs Between Directories</A></H2>
<A NAME="IDX1013"></A>
<A NAME="IDX1014"></A>
<A NAME="IDX1015"></A>
<A NAME="IDX1016"></A>
<P>The <B>fs copyacl</B> command copies a source directory's ACL to
one or more destination directories. It does not affect the source ACL
at all, but changes each destination ACL as follows:
<UL>
<P><LI>If an entry on the source ACL does not exist on the destination ACL, the
command copies it to the destination ACL.
<P><LI>If an entry on the destination ACL does not also exist on the source ACL,
the command does not remove it unless you include the <B>-clear</B> flag,
which overwrites the destination ACL completely.
<P><LI>If an entry is on both ACLs, the command changes the destination ACL entry
to match the source ACL entry.
</UL>
<P>To copy an ACL, you must have the <B>l</B> permission on the source ACL
and the <B>a</B> permission on each destination ACL. If you
identify the source directory by naming a file in it, you must also have the
<B>r</B> permission on the source ACL. To display the permissions
you have on the two directories, use the <B>fs listacl</B> command as
described in <A HREF="#HDRWQ52">Displaying an ACL</A>.
<P><B>Note for AFS/DFS Migration Toolkit users:</B> If the machine
on which you issue the <B>fs copyacl</B> command is configured for access
to a DCE cell's DFS filespace via the AFS/DFS Migration Toolkit, you can
use the command to copy ACLs between DFS files and directories also.
The command includes <B>-id</B> and <B>-if</B> flags for altering a
DFS directory's Initial Container and Initial Object ACLs as well as its
regular ACL; for details, ask your system administrator. You
cannot copy ACLs between AFS and DFS directories, because they use different
ACL formats. The <B>fs</B> command interpreter ignores the
<B>-id</B> and <B>-if</B> flags if you include them when copying AFS
ACLs.
<P><H3><A NAME="Header_108" HREF="auusg002.htm#ToC_108">To Copy an ACL Between Directories</A></H3>
<A NAME="IDX1017"></A>
<A NAME="IDX1018"></A>
<P>Issue the <B>fs copyacl</B> command to copy a source ACL to the ACL on
one or more destination directories.
<PRE>   % <B>fs copyacl -fromdir</B> &lt;<VAR>source&nbsp;directory</VAR>> <B>-todir</B> &lt;<VAR>destination&nbsp;directory</VAR>><SUP>+</SUP>  \
                [<B>-clear</B>]
</PRE>
<P>where
<DL>
<P><DT><B>co
</B><DD>Is the shortest acceptable abbreviation for <B>copyacl</B>.
<P><DT><B>-fromdir
</B><DD>Names the source directory from which to copy the ACL. Partial
pathnames are interpreted relative to the current working directory. If
this argument names a file, the ACL is copied from its directory.
<P><DT><B>-todir
</B><DD>Names each destination directory to which to copy the source ACL.
Partial pathnames are interpreted relative to the current working
directory. Filenames are not acceptable.
<P><DT><B>-clear
</B><DD>Completely overwrites each destination directory's ACL with the
source ACL.
</DL>
<P><H3><A NAME="Header_109" HREF="auusg002.htm#ToC_109">Example:  Copying an ACL from One Directory to Another</A></H3>
<A NAME="IDX1019"></A>
<P>In this example, user <B>terry</B> copies the ACL from her home
directory (the current working directory) to its <B>plans</B>
subdirectory. She begins by displaying both ACLs.
<PRE>   % <B>fs listacl . plans</B>
   Access list for . is
   Normal rights:
      terry rlidwka
      pat rlidwk
      jones rl
   Access list for plans is
   Normal rights:
      terry rlidwka
      pat rl
      smith rl   
     
  % <B>fs copyacl -from . -to plans</B>
   
   % <B>fs listacl . plans</B>
   Access list for . is
   Normal rights:
      terry rlidwka
      pat rlidwk
      jones rl
   Access list for plans is
   Normal rights:
      terry rlidwka
      pat rlidwk
      jones rl
      smith rl   
</PRE>
<HR><H2><A NAME="HDRWQ59" HREF="auusg002.htm#ToC_110">How AFS Uses the UNIX Mode Bits</A></H2>
<A NAME="IDX1020"></A>
<A NAME="IDX1021"></A>
<P>Although AFS protects data primarily with ACLs rather than mode bits, it
does not ignore the mode bits entirely. An explanation of how mode bits
work in the UNIX file system is outside the scope of this document, and the
following discussion assumes you understand them; if necessary, see your
UNIX documentation. Also, the following discussion does not cover the
setuid, setgid or sticky bits. If you need to understand how those bits
work on AFS files, see the <I>IBM AFS Administration Guide</I> or ask your
system administrator.
<P>AFS uses the UNIX mode bits in the following way:
<UL>
<P><LI>It uses the initial bit to distinguish files and directories. This
is the bit that appears first in the output from the <B>ls -l</B> command
and shows the hyphen (<TT>-</TT>) for a file or the letter <TT>d</TT> for
a directory.
<P><LI>It does not use any of the mode bits on a directory. The AFS ACL
alone controls directory access.
<P><LI>For a file, the owner (first) set of bits interacts with the ACL entries
that apply to the file in the following way. AFS does not use the group
or world (second and third sets) of mode bits at all.
<UL>
<P><LI>If the first <B>r</B> mode bit is not set, no one (including the
owner) can read the file, no matter what permissions they have on the
ACL. If the bit is set, users also need the <B>r</B> and
<B>l</B> permissions on the ACL of the file's directory to read the
file.
<P><LI>If the first <B>w</B> mode bit is not set, no one (including the
owner) can modify the file. If the <B>w</B> bit is set, users also
need the <B>w</B> and <B>l</B> permissions on the ACL of the
file's directory to modify the file.
<P><LI>There is no ACL permission directly corresponding to the <B>x</B> mode
bit, but to execute a file stored in AFS, the user must also have the
<B>r</B> and <B>l</B> permissions on the ACL of the file's
directory.
</UL>
</UL>
<P>When you issue the UNIX <B>chmod</B> command on an AFS file or
directory, AFS changes the bits appropriately. To change a file's
mode bits, you must have the AFS <B>w</B> permission on the ACL of the
file's directory. To change a directory's mode bits, you must
have the <B>d</B>, <B>i</B>, and <B>l</B> permissions on its
ACL.
<A NAME="IDX1022"></A>
<A NAME="IDX1023"></A>
<P><H3><A NAME="Header_111" HREF="auusg002.htm#ToC_111">Example:  Disabling Write Access for a File</A></H3>
<P><B></B>
<A NAME="IDX1024"></A>
<P>Suppose <B>terry</B> is chairing a committee that is writing a
proposal. As each section is approved, she turns off write access to
that file to prevent further changes. For example, the following
<B>chmod</B> command turns off the <B>w</B> mode bits on the file
<B>proposal.chap2</B>. This makes it impossible for anyone
to change the file, no matter what permissions are granted on the directory
ACL.
<PRE>   % <B>chmod -w proposal.chap2</B>
   % <B>ls -l</B>
   -rw-r--r--  1 terry     573 Nov 10 09:57 conclusion
   -r--r--r--  1 terry     573 Nov 15 10:34 intro
   -r--r--r--  1 terry     573 Dec  1 15:07 proposal.chap2
   -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap3
   -rw-r--r--  1 terry     573 Nov 10 09:57 proposal.chap4
</PRE>
<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> 
<!-- Begin Footer Records  ========================================== -->
<P><HR><B> 
<br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved 
</B> 
<!-- End Footer Records  ============================================ -->
<A NAME="Bot_Of_Page"></A>
</BODY></HTML>