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