man/man5/acl.5

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