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/.example.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, optionally
  98 followed by a single plus (+) or minus (-) chracter to request a relative
  99 ACL change
 100
 101 =back
 102
 103 in that order, separated by a space (thus every instance of this argument
 104 has two parts). The accepted AFS abbreviations and shorthand words, and
 105 the meaning of each, are as follows:
 106
 107 =over 4
 108
 109 =item a (administer)
 110
 111 Change the entries on the ACL.
 112
 113 =item d (delete)
 114
 115 Remove files and subdirectories from the directory or move them to other
 116 directories.
 117
 118 =item i (insert)
 119
 120 Add files or subdirectories to the directory by copying, moving or
 121 creating.
 122
 123 =item k (lock)
 124
 125 Set read locks or write locks on the files in the directory.
 126
 127 =item l (lookup)
 128
 129 List the files and subdirectories in the directory, stat the directory
 130 itself, and issue the B<fs listacl> command to examine the directory's
 131 ACL.
 132
 133 =item r (read)
 134
 135 Read the contents of files in the directory; issue the C<ls -l> command to
 136 stat the elements in the directory.
 137
 138 =item w (write)
 139
 140 Modify the contents of files in the directory, and issue the UNIX B<chmod>
 141 command to change their mode bits.
 142
 143 =item A, B, C, D, E, F, G, H
 144
 145 Have no default meaning to the AFS server processes, but are made
 146 available for applications to use in controlling access to the directory's
 147 contents in additional ways. The letters must be uppercase.
 148
 149 =item all
 150
 151 Equals all seven permissions (C<rlidwka>).
 152
 153 =item none
 154
 155 No permissions. Removes the user/group from the ACL, but does not
 156 guarantee they have no permissions if they belong to groups that remain on
 157 the ACL.
 158
 159 =item read
 160
 161 Equals the C<r> (read) and C<l> (lookup) permissions.
 162
 163 =item write
 164
 165 Equals all permissions except C<a> (administer), that is, C<rlidwk>.
 166
 167 =back
 168
 169 It is acceptable to mix entries that combine the individual letters with
 170 entries that use the shorthand words, but not use both types of notation
 171 within an individual pairing of user or group and permissions.
 172
 173 Granting the C<l> (lookup) and C<i> (insert) permissions without
 174 granting the C<w> (write) and/or C<r> (read) permissions is a special
 175 case, and grants rights approrpriate for "dropbox" directories. See the
 176 L</DROPBOXES> section for details.
 177
 178 If setting ACLs on a pathname in DFS filespace, see the DFS documentation
 179 for the proper format and acceptable values for DFS ACL entries.
 180
 181 =item B<-clear>
 182
 183 Removes all existing entries on each ACL before adding the entries
 184 specified with the B<-acl> argument.
 185
 186 =item B<-negative>
 187
 188 Places the specified ACL entries in the C<Negative rights> section of each
 189 ACL, explicitly denying the rights to the user or group, even if entries
 190 on the accompanying C<Normal rights> section of the ACL grant them
 191 permissions.
 192
 193 This argument is not supported for DFS files or directories, because DFS
 194 does not implement negative ACL permissions.
 195
 196 =item B<-id>
 197
 198 Places the ACL entries on the Initial Container ACL of each DFS directory,
 199 which are the only file system objects for which this flag is supported.
 200
 201 =item B<-if>
 202
 203 Places the ACL entries on the Initial Object ACL of each DFS directory,
 204 which are the only file system objects for which this flag is supported.
 205
 206 =item B<-help>
 207
 208 Prints the online help for this command. All other valid options are
 209 ignored.
 210
 211 =back
 212
 213 =head1 DROPBOXES
 214
 215 If an accessing user has the C<l> (lookup) and C<i> (insert) permissions
 216 on a directory, but not the C<w> (write) and/or C<r> (read) permissions,
 217 the user is implicitly granted the ability to write and/or read any file
 218 they create in that directory, until they close the file. This is to
 219 allow "dropbox"-style directories to exist, where users can deposit
 220 files, but cannot modify them later nor can they modify or read any
 221 files deposited in the directory by other users.
 222
 223 Note, however, that the dropbox functionality is not perfect. The
 224 fileserver does not have knowledge of when a file is opened or closed on
 225 the client, and so the fileserver always allows an accessing user to
 226 read or write to a file in a "dropbox" directory if they own the file.
 227 While the client prevents the user from reading or modifying their
 228 deposited file later, this is not enforced on the fileserver, and so
 229 should not be relied on for security.
 230
 231 Additionally, if "dropbox" permissions are granted to C<system:anyuser>,
 232 unauthenticated users may deposit files in the directory. If an
 233 unauthenticated user deposits a file in the directory, the new file will
 234 be owned by the unauthenticated user ID, and is thus potentially
 235 modifiable by anyone.
 236
 237 In an effort to try and reduce accidentally publicizing private data, the
 238 fileserver may refuse read requests for "dropbox" files from unauthenticated
 239 users. As a result, depositing files as an unauthenticated user may arbitrarily
 240 fail if C<system:anyuser> has been granted dropbox permissions. While this
 241 should be rare, it is not completely preventable, and so for this reason
 242 relying on unauthenticated users to be able to deposit files in a dropbox is
 243 B<NOT RECOMMENDED>.
 244
 245 =head1 EXAMPLES
 246
 247 The following example adds two entries to the C<Normal rights> section of
 248 the current working directory's ACL: the first entry grants C<r> (read)
 249 and C<l> (lookup) permissions to the group pat:friends, while the other
 250 (using the C<write> shorthand) gives all permissions except C<a>
 251 (administer) to the user C<smith>.
 252
 253    % fs setacl -dir . -acl pat:friends rl smith write
 254
 255    % fs listacl -path .
 256    Access list for . is
 257    Normal rights:
 258       pat:friends rl
 259       smith rlidwk
 260
 261 The following example includes the B<-clear> flag, which removes the
 262 existing permissions (as displayed with the B<fs listacl> command) from
 263 the current working directory's F<reports> subdirectory and replaces them
 264 with a new set.
 265
 266    % fs listacl -dir reports
 267    Access list for reports is
 268    Normal rights:
 269       system:authuser rl
 270       pat:friends rlid
 271       smith rlidwk
 272       pat rlidwka
 273    Negative rights:
 274       terry rl
 275
 276    % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl
 277
 278    % fs listacl -dir reports
 279    Access list for reports is
 280    Normal rights:
 281       system:anyuser rl
 282       smith rlidwk
 283       pat rlidwka
 284
 285 The following example use the B<-dir> and B<-acl> switches because it sets
 286 the ACL for more than one directory (both the current working directory
 287 and its F<public> subdirectory).
 288
 289    % fs setacl -dir . public -acl pat:friends rli
 290
 291    % fs listacl -path . public
 292    Access list for . is
 293    Normal rights:
 294       pat rlidwka
 295       pat:friends rli
 296    Access list for public is
 297    Normal rights:
 298       pat rlidwka
 299       pat:friends rli
 300
 301 The following example demonstrates the use of the + and - options to
 302 modfiy ACLs relative to the existing set
 303
 304    % fs setacl dir . -acl pat:friends r-
 305    % fs listacl -path .
 306    Access list for . is
 307    Normal rights:
 308       pat rlidwka
 309       pat:friends li
 310    % fs setacl dir . acl pat:friends w+
 311    % fs listacl -path .
 312    Access list for . is
 313    Normal rights:
 314       pat rlidwka
 315       pat:friends wli
 316
 317 =head1 PRIVILEGE REQUIRED
 318
 319 The issuer must have the C<a> (administer) permission on the directory's
 320 ACL, a member of the system:administrators group, or, as a special case,
 321 must be the UID owner of the top-level directory of the volume containing
 322 this directory.  The last provision allows the UID owner of a volume to
 323 repair accidental ACL errors without requiring intervention by a member of
 324 system:administrators.
 325
 326 Earlier versions of OpenAFS also extended implicit administer permission
 327 to the owner of any directory.  In current versions of OpenAFS, only the
 328 owner of the top-level directory of the volume has this special
 329 permission.
 330
 331 =head1 SEE ALSO
 332
 333 L<fs_copyacl(1)>,
 334 L<fs_listacl(1)>,
 335 L<fs_mkmount(1)>
 336
 337 =head1 COPYRIGHT
 338
 339 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 340
 341 This documentation is covered by the IBM Public License Version 1.0.  It was
 342 converted from HTML to POD by software written by Chas Williams and Russ
 343 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.