manual/acl/original/man5/acl.5

   1 .\" Access Control Lists manual pages
   2 .\"
   3 .\" (C) 2002 Andreas Gruenbacher, <a.gruenbacher@bestbits.at>
   4 .\"
   5 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
   6 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   7 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   8 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
   9 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  10 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  11 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  12 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  13 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  14 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  15 .\" SUCH DAMAGE.
  16 .\"
  17 .Dd March 23, 2002
  18 .Dt ACL 5
  19 .Os "Linux ACL"
  20 .Sh NAME
  21 .Nm acl
  22 .Nd Access Control Lists
  23 .Sh DESCRIPTION
  24 This manual page describes POSIX Access Control Lists, which are used to
  25 define more fine-grained discretionary access rights for files and
  26 directories.
  27 .Sh ACL TYPES
  28 Every object can be thought of as having associated with it an ACL that
  29 governs the discretionary access to that object; this ACL is referred to
  30 as an access ACL. In addition, a directory may have an associated ACL
  31 that governs the initial access ACL for objects created within that
  32 directory; this ACL is referred to as a default ACL.
  33 .Sh ACL ENTRIES
  34 An ACL consists of a set of ACL entries. An ACL entry specifies the
  35 access permissions on the associated object for an individual user or a
  36 group of users as a combination of read, write and search/execute
  37 permissions.
  38 .Pp
  39 An ACL entry contains an entry tag type, an optional entry tag
  40 qualifier, and a set of permissions.
  41 We use the term qualifier to denote the entry tag qualifier of an ACL entry.
  42 .Pp
  43 The qualifier denotes the identifier of a user or a group, for entries
  44 with tag types of ACL_USER or ACL_GROUP, respectively. Entries with tag
  45 types other than ACL_USER or ACL_GROUP have no defined qualifiers.
  46 .Pp
  47 The following entry tag types are defined:
  48 .Bl -tag -offset indent -width ACL_GROUP_OBJ.
  49 .It ACL_USER_OBJ
  50 The ACL_USER_OBJ entry denotes access rights for the file owner.
  51 .It ACL_USER
  52 ACL_USER entries denote access rights for users identified by
  53 the entry's qualifier.
  54 .It ACL_GROUP_OBJ
  55 The ACL_GROUP_OBJ entry denotes access rights for the file group.
  56 .It ACL_GROUP
  57 ACL_GROUP entries denote access rights for groups identified by
  58 the entry's qualifier.
  59 .It ACL_MASK
  60 The ACL_MASK entry denotes the maximum access rights that can be granted
  61 by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.
  62 .It ACL_OTHER
  63 The ACL_OTHER entry denotes access rights for processes
  64 that do not match any other entry in the ACL.
  65 .El
  66 .Pp
  67 When an access check is performed, the ACL_USER_OBJ and ACL_USER entries
  68 are tested against the effective user ID. The effective group ID, as
  69 well as all supplementary group IDs are tested against the ACL_GROUP_OBJ
  70 and ACL_GROUP entries.
  71 .Sh VALID ACLs
  72 A valid ACL contains exactly one entry with each of the ACL_USER_OBJ,
  73 ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and
  74 ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that
  75 contains entries of ACL_USER or ACL_GROUP tag types must contain
  76 exactly one entry of the ACL_MASK tag type. If an ACL contains no
  77 entries of ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is
  78 optional.
  79 .Pp
  80 All user ID qualifiers must be unique among all entries of
  81 ACL_USER tag type, and all group IDs must be unique among all entries of
  82 ACL_GROUP tag type.
  83 .\"minimal vs. extended ACLs
  84 .Pp
  85   The
  86 .Fn acl_get_file
  87 function returns an ACL with zero ACL entries as the default ACL of a
  88 directory, if the directory is not associated with a default ACL. The
  89 .Fn acl_set_file
  90 function also accepts an ACL with zero ACL entries as a valid default ACL for
  91 directories, denoting that the directory shall not be associated with a
  92 default ACL. This is equivalent to using the
  93 .Fn acl_delete_def_file
  94 function.
  95 .Sh CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS
  96 The permissions defined by ACLs are a superset of the permissions
  97 specified by the file permission bits. The permissions defined for
  98 the file owner correspond to the permissions of the ACL_USER_OBJ entry.
  99 The permissions defined for the file group correspond to the permissions
 100 of the ACL_GROUP_OBJ entry, if the ACL has no ACL_MASK entry. If the ACL
 101 has an ACL_MASK entry, then the permissions defined for the file group
 102 correspond to the permissions of the ACL_MASK entry. The permissions
 103 defined for the other class correspond to the permissions of the
 104 ACL_OTHER_OBJ entry.
 105 .Pp
 106 Modification of the file permission bits results in the modification of
 107 the permissions in the associated ACL entries. Modification of the
 108 permissions in the ACL entries results in the modification of the file
 109 permission bits.
 110 .Sh OBJECT CREATION AND DEFAULT ACLs
 111 The access ACL of a file object is initialized when the object is
 112 created with any of the
 113 .Fn creat ,
 114 .Fn mkdir ,
 115 .Fn mknod ,
 116 .Fn mkfifo ,
 117 or
 118 .Fn open
 119 functions. If a default ACL is associated with a directory, the
 120 .Va mode
 121 parameter to the functions creating file objects and the default ACL of
 122 the directory are used to determine the ACL of the new object:
 123 .Bl -enum
 124 .It
 125 The new object inherits the default ACL of the containing directory
 126 as its access ACL.
 127 .It
 128 The access ACL entries corresponding to the file permission bits are
 129 modified so that they contain no permissions that are not
 130 contained in the permissions specified by the
 131 .Va mode
 132 parameter.
 133 .El
 134 .Pp
 135 If no default ACL is associated with a directory, the
 136 .Va mode
 137 parameter to the functions creating file objects and the file creation
 138 mask (see
 139 .Xr umask 2 )
 140 are used to determine the ACL of the new object:
 141 .Bl -enum
 142 .It
 143 The new object is assigned an access ACL containing entries of tag types
 144 ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. The permissions of these
 145 entries are set to the permissions specified by the file creation mask.
 146 .It
 147 The access ACL entries corresponding to the file permission bits are
 148 modified so that they contain no permissions that are not
 149 contained in the permissions specified by the
 150 .Va mode
 151 parameter.
 152 .El
 153 .Sh ACCESS CHECK ALGORITHM
 154 A process may request read, write, or execute/search access to a file object
 155 protected by an ACL. The access check algorithm determines whether access to
 156 the object will be granted.
 157 .Bl -enum
 158 .It
 159 .Sy If
 160 the effective user ID of the process matches the user ID of the file object owner,
 161 .Sy then
 162 .Pp
 163 .in +4
 164 .Bd -filled
 165 .Sy if
 166 the ACL_USER_OBJ entry contains the requested permissions, access is granted,
 167 .Pp
 168 .Sy else
 169 access is denied.
 170 .in -4
 171 .Ed
 172 .It
 173 .Sy "else if"
 174 the effective user ID of the process matches the qualifier of any entry
 175 of type ACL_USER,
 176 .Sy then
 177 .Pp
 178 .in +4
 179 .Bd -filled
 180 .Sy if
 181 the matching ACL_USER entry and the ACL_MASK entry contain the requested
 182 permissions, access is granted,
 183 .Pp
 184 .Sy else
 185 access is denied.
 186 .in -4
 187 .Ed
 188 .It
 189 .Sy else if
 190 the effective group ID or any of the supplementary group IDs of the process
 191 match the file group or the qualifier of any entry of type ACL_GROUP,
 192 .Sy then
 193 .Pp
 194 .in +4
 195 .Bd -filled
 196 .Sy if
 197 the ACL contains an ACL_MASK entry,
 198 .Sy then
 199 .in +4
 200 .Bd -filled
 201 .Sy if
 202 the ACL_MASK entry and any of the matching ACL_GROUP_OBJ or ACL_GROUP entries
 203 contain
 204 the requested permissions, access is granted,
 205 .Pp
 206 .Sy else
 207 access is denied.
 208 .Pp
 209 .in -4
 210 .Ed
 211 .Sy else
 212 (note that there can be no ACL_GROUP entries without an ACL_MASK entry)
 213 .in +4
 214 .Bd -filled
 215 .Sy if
 216 the ACL_GROUP_OBJ entry contains the requested permissions,
 217 access is granted,
 218 .Ed
 219 .Pp
 220 .Sy else
 221 access is denied.
 222 .Pp
 223 .in -4
 224 .Ed
 225 .in -4
 226 .Ed
 227 .It
 228 .Sy else if
 229 the ACL_OTHER entry contains the requested permissions, access is granted.
 230 .It
 231 .Sy else
 232 access is denied.
 233 .El
 234 .\".It
 235 .\"Checking whether the requested access modes are granted by the matched entry.
 236 .\".El
 237 .Sh ACL TEXT FORMS
 238 A long and a short text form for representing ACLs is defined. In both forms, ACL entries are represented as three colon separated fields: an ACL entry tag type, an ACL entry qualifier, and the discretionary access permissions. The first field contains one of the following entry tag type keywords:
 239 .Bl -tag -offset indent -width group.
 240 .It Li user
 241 A
 242 .Li user
 243 ACL entry specifies the access granted to either the file owner (entry tag
 244 type ACL_USER_OBJ) or a specified user (entry tag type ACL_USER).
 245 .It Li group
 246 A
 247 .Li group
 248 ACL entry specifies the access granted to either the file group (entry tag
 249 type ACL_GROUP_OBJ) or a specified group (entry tag type ACL_GROUP).
 250 .It Li mask
 251 A
 252 .Li mask
 253 ACL entry specifies the maximum access which can be granted by any ACL
 254 entry except the
 255 .Li user
 256 entry for the file owner and the
 257 .Li other
 258 entry (entry tag type ACL_MASK).
 259 .It Li other
 260 An other ACL entry specifies the access granted to any process that does
 261 not match any
 262 .Li user
 263 or
 264 .Li group
 265 ACL entries (entry tag type ACL_OTHER).
 266 .El
 267 .Pp
 268 The second field contains the user or group identifier of the user or
 269 group associated with the ACL entry for entries of entry tag type ACL_USER
 270 or ACL_GROUP, and is empty for all other entries. A user identifier can
 271 be a user name or a user ID number in decimal form. A group identifier can
 272 be a group name or a group ID number in decimal form.
 273 .Pp
 274 The third field contains the discretionary access permissions. The read,
 275 write and search/execute permissions are represented by the
 276 .Li r ,
 277 .Li w ,
 278 and
 279 .Li x
 280 characters, in this order. Each of these characters is replaced by the
 281 .Li \-
 282 character to denote that a permission is absent in the ACL entry.
 283 When converting from the text form to the internal representation,
 284 permissions that are absent need not be specified.
 285 .Pp
 286 White space is permitted at the beginning and end of each ACL entry, and
 287 immediately before and after a field separator (the colon character).
 288 .Ss LONG TEXT FORM
 289 The long text form contains one ACL entry per line. In addition, a
 290 number sign
 291 .No ( Li # )
 292 may start a comment that extends until the end of the line. If an
 293 ACL_USER, ACL_GROUP_OBJ or ACL_GROUP ACL entry contains permissions that
 294 are not also contained in the ACL_MASK entry, the entry is followed by a
 295 number sign, the string \(lqeffective:\(rq, and the effective access
 296 permissions defined by that entry. This is an example of the long text
 297 form:
 298 .Bd -literal -offset indent
 299 user::rw-
 300 user:lisa:rw-         #effective:r--
 301 group::r--
 302 group:toolies:rw-     #effective:r--
 303 mask::r--
 304 other::r--
 305 .Ed
 306 .Ss SHORT TEXT FORM
 307 The short text form is a sequence of ACL entries separated by commas,
 308 and is used for input. Comments are not supported. Entry tag type
 309 keywords may either appear in their full unabbreviated form, or in their
 310 single letter abbreviated form. The abbreviation for
 311 .Li user
 312 is
 313 .Li u ,
 314 the abbreviation for
 315 .Li group
 316 is
 317 .Li g ,
 318 the abbreviation for
 319 .Li mask
 320 is
 321 .Li m ,
 322 and the abbreviation for
 323 .Li other
 324 is
 325 .Li o .
 326 The permissions may contain at most one each of the following characters
 327 in any order:
 328 .Li r ,
 329 .Li w ,
 330 .Li x .
 331 These are examples of the short text form:
 332 .Bd -literal -offset indent
 333 u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
 334 g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r
 335 .Ed
 336 .Sh RATIONALE
 337 IEEE 1003.1e draft 17 defines Access Control Lists that include entries
 338 of tag type ACL_MASK, and defines a mapping between file permission bits
 339 that is not constant. The standard working group defined this relatively
 340 complex interface in order to ensure that applications that are compliant
 341 with IEEE 1003.1 (\(lqPOSIX.1\(rq) will still function as expected on
 342 systems with ACLs. The IEEE 1003.1e draft 17 contains the rationale for
 343 choosing this interface in section B.23.
 344 .Sh CHANGES TO THE FILE UTILITIES
 345 On a system that supports ACLs, the file utilities
 346 .Xr ls 1 ,
 347 .Xr cp 1 ,
 348 and
 349 .Xr mv 1
 350 change their behavior in the following way:
 351 .Bl -bullet
 352 .It
 353 For files that have a default ACL or an access ACL that contains more than
 354 the three required ACL entries, the
 355 .Xr ls 1
 356 utility in the long form produced by
 357 .Ic "ls \-l"
 358 displays a plus sign
 359 .No ( Li + )
 360 after the permission string.
 361 .It
 362 If the
 363 .Fl p
 364 flag is specified, the
 365 .Xr cp 1
 366 utility also preserves ACLs.
 367 If this is not possible, a warning is produced.
 368 .It
 369   The
 370 .Xr mv 1
 371 utility always preserves ACLs. If this is not possible, a warning is produced.
 372 .El
 373 .Pp
 374 The effect of the
 375 .Xr chmod 1
 376 utility, and of the
 377 .Xr chmod 2
 378 system call, on the access ACL is described in
 379 .Sx "CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS" .
 380 .Sh STANDARDS
 381 The IEEE 1003.1e draft 17 (\(lqPOSIX.1e\(rq) document describes several
 382 security extensions to the IEEE 1003.1 standard. While the work on
 383 1003.1e has been abandoned, many UNIX style systems implement parts of
 384 POSIX.1e draft 17, or of earlier drafts.
 385 .Pp
 386 Linux Access Control Lists implement the full set of functions and
 387 utilities defined for Access Control Lists in POSIX.1e, and several
 388 extensions.  The implementation is fully compliant with POSIX.1e draft
 389 17; extensions are marked as such.
 390 The Access Control List manipulation functions are defined in
 391 the ACL library (libacl, \-lacl). The POSIX compliant interfaces are
 392 declared in the
 393 .Li <sys/acl.h>
 394 header.  Linux-specific extensions to these functions are declared in the
 395 .Li <acl/libacl.h>
 396 header.
 397 .Sh SEE ALSO
 398 .Xr chmod 1 ,
 399 .Xr creat 2 ,
 400 .Xr getfacl 1 ,
 401 .Xr ls 1 ,
 402 .Xr mkdir 2 ,
 403 .Xr mkfifo 2 ,
 404 .Xr mknod 2 ,
 405 .Xr open 2 ,
 406 .Xr setfacl 1 ,
 407 .Xr stat 2 ,
 408 .Xr umask 1
 409 .Ss POSIX 1003.1e DRAFT 17
 410 .Xr "http://www.guug.de/~winni/posix.1e/download.html"
 411 .Ss POSIX 1003.1e FUNCTIONS BY CATEGORY
 412 .Bl -tag -width "MMM"
 413 .It Sy ACL storage management
 414 .Xr acl_dup 3 ,
 415 .Xr acl_free 3 ,
 416 .Xr acl_init 3
 417 .It Sy ACL entry manipulation
 418 .Xr acl_copy_entry 3 ,
 419 .Xr acl_create_entry 3 ,
 420 .Xr acl_delete_entry 3 ,
 421 .Xr acl_get_entry 3 ,
 422 .Xr acl_valid 3
 423 .Pp
 424 .Xr acl_add_perm 3 ,
 425 .Xr acl_calc_mask 3 ,
 426 .Xr acl_clear_perms 3 ,
 427 .Xr acl_delete_perm 3 ,
 428 .Xr acl_get_permset 3 ,
 429 .Xr acl_set_permset 3
 430 .Pp
 431 .Xr acl_get_qualifier 3 ,
 432 .Xr acl_get_tag_type 3 ,
 433 .Xr acl_set_qualifier 3 ,
 434 .Xr acl_set_tag_type 3
 435 .It Sy ACL manipulation on an object
 436 .Xr acl_delete_def_file 3 ,
 437 .Xr acl_get_fd 3 ,
 438 .Xr acl_get_file 3 ,
 439 .Xr acl_set_fd 3 ,
 440 .Xr acl_set_file 3
 441 .It Sy ACL format translation
 442 .Xr acl_copy_entry 3 ,
 443 .Xr acl_copy_ext 3 ,
 444 .Xr acl_from_text 3 ,
 445 .Xr acl_to_text 3 ,
 446 .Xr acl_size 3
 447 .El
 448 .Ss POSIX 1003.1e FUNCTIONS BY AVAILABILITY
 449 The first group of functions is supported on most systems with POSIX-like
 450 access control lists, while the second group is supported on fewer systems.
 451 For applications that will be ported the second group is best avoided.
 452 .Pp
 453 .Xr acl_delete_def_file 3 ,
 454 .Xr acl_dup 3 ,
 455 .Xr acl_free 3 ,
 456 .Xr acl_from_text 3 ,
 457 .Xr acl_get_fd 3 ,
 458 .Xr acl_get_file 3 ,
 459 .Xr acl_init 3 ,
 460 .Xr acl_set_fd 3 ,
 461 .Xr acl_set_file 3 ,
 462 .Xr acl_to_text 3 ,
 463 .Xr acl_valid 3
 464 .Pp
 465 .Xr acl_add_perm 3 ,
 466 .Xr acl_calc_mask 3 ,
 467 .Xr acl_clear_perms 3 ,
 468 .Xr acl_copy_entry 3 ,
 469 .Xr acl_copy_ext 3 ,
 470 .Xr acl_copy_int 3 ,
 471 .Xr acl_create_entry 3 ,
 472 .Xr acl_delete_entry 3 ,
 473 .Xr acl_delete_perm 3 ,
 474 .Xr acl_get_entry 3 ,
 475 .Xr acl_get_permset 3 ,
 476 .Xr acl_get_qualifier 3 ,
 477 .Xr acl_get_tag_type 3 ,
 478 .Xr acl_set_permset 3 ,
 479 .Xr acl_set_qualifier 3 ,
 480 .Xr acl_set_tag_type 3 ,
 481 .Xr acl_size 3
 482 .Ss LINUX EXTENSIONS
 483 These non-portable extensions are available on Linux systems.
 484 .Pp
 485 .Xr acl_check 3 ,
 486 .Xr acl_cmp 3 ,
 487 .Xr acl_entries 3 ,
 488 .Xr acl_equiv_mode 3 ,
 489 .Xr acl_error 3 ,
 490 .Xr acl_extended_fd 3 ,
 491 .Xr acl_extended_file 3 ,
 492 .Xr acl_from_mode 3 ,
 493 .Xr acl_get_perm 3 ,
 494 .Xr acl_to_any_text 3
 495 .Sh AUTHOR
 496 Andreas Gruenbacher, <a.gruenbacher@bestbits.at>