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.