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