doc/old-acl.5

   1 .\"
   2 .\" Access Control Lists
   3 .\"
   4 .\" Documentation for the Linux implementation
   5 .\" (C) Andreas Gruenbacher, 1999
   6 .\"
   7 .TH ACL 5 "Access Control Lists" "Sep 1999" "Access Control Lists"
   8 .SH NAME
   9 acl - Access Control Lists
  10 .SH DESCRIPTION
  11 This document describes Posix-style access control lists as implemented under
  12 Linux. Access control lists (ACLs) are used to define access to files
  13 and directories.
  14
  15 In portable programs, the Posix 1003.1e Draft Standard 17 library
  16 functions should be used for mainpulating ACL. On most platforms, the
  17 ACL entry manipulation functions are not available, so relying only on
  18 the ACL manipulation and format conversion functions (ACL to and from
  19 text format) is more portable.  The library functions are declared in
  20 the
  21 .I sys/acl.h
  22 header file.
  23
  24 .SH ACCESS CONTROL LIST ENTRIES
  25 An access control list contains a number of entries of various types. Each entry stands for permissions granted to a user, or to a group of users.
  26 .PP
  27 An ACL may contain entries with the following entry tag types.
  28 .PP
  29 .RS
  30 .fam C
  31 .nf
  32 ACL_USER_OBJ         (owner)
  33 ACL_USER             (named user)
  34 ACL_GROUP_OBJ        (owning group)
  35 ACL_GROUP            (named group)
  36 ACL_MASK             (effective rights mask)
  37 ACL_OTHER            (other users)
  38 .fi
  39 .fam T
  40 .RE
  41 .PP
  42 The
  43 ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER entries
  44 correspond to the traditional file mode permission bits. There is
  45 exactly one each of these entries in a valid ACL.
  46 .PP
  47 ACL_USER and ACL_GROUP
  48 entries define explicit rights for users and groups, respectively. For
  49 entries of these two types,
  50 .I a_id[0]
  51 is set to the ID of the user or group in question. Whenever there are
  52 any entries of the last two types in the ACL, an ACL_MASK
  53 entry is also required.
  54
  55 An ACL_MASK entry limits the effective rights granted
  56 to named users or groups. The efective rights granted are those
  57 that are both granted by the user's or group's entry, and by the ACL_MASK entry. The ACL_MASK entry does not apply to the ACL_USER_OBJ and ACL_OTHER entries.
  58 .PP
  59 The lowest three bits of
  60 .I a_perm
  61 define the rights granted to the user the entry applies to, just like
  62 the bits in the traditional file mode. This results in a value between 0 and 7
  63 (from 0 standing for no access to 7 standing for read, write, and execute access). For accessing these bits, the constants ACL_READ, ACL_WRITE and ACL_EXECUTE should be used.
  64
  65 .SH VALID ACCESS CONTROL LISTS
  66 Each valid ACL has as a minimum the three required base entries
  67 ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. These entries correspond
  68 to the traditional Posix permission bits. There must be exactly one each
  69 of these three entries. The permission mask `rw-r-----' corresponds to the
  70 following entries:
  71 .sp
  72 .RS
  73 .fam C
  74 .nf
  75         u::rw- (ACL_USER_OBJ entry)
  76         g::r-- (ACL_GROUP_OBJ entry)
  77         o::--- (ACL_OTHER entry)
  78 .fi
  79 .fam T
  80 .RE
  81 .PP
  82 An ACL must also contain exactly one ACL_MASK entry, if it contains
  83 additional ACL_USER or ACL_GROUP entries. For each user or group, there
  84 must be at most one ACL_USER or ACL_GROUP entry per access control list. An ACL may also contain an ACL_MASK entry if no ACL_USER or ACL_GROUP entries exist.
  85 .sp
  86 .RS
  87 .fam C
  88 .nf
  89         u:joe:rw- (ACL_USER entry)
  90         g:webteam:rw- (ACL_GROUP entry)
  91         m::rw- (ACL_MASK entry)
  92 .fi
  93 .fam T
  94 .RE
  95 .PP
  96 .SS THE ACL_MASK ENTRY
  97 The purpose of the ACL_MASK entry is to limit
  98 the effective rights granted to groups and named users in
  99 the ACL. The effective rights granted to a user or a group with an ACL_USER
 100 or an ACL_GROUP entry are those which are listed in both the ACL_USER
 101 or ACL_GROUP entry
 102 .I and
 103 the ACL_MASK entry. The ACL_USER_OBJ and ACL_OTHER entries
 104 are not affected by the ACL_MASK entry.
 105
 106 .SH PERMISSIONS
 107 The permissions required for manipulating ACLs of an inode are similar
 108 to the permissions required for manipulating the file mode. Processes
 109 with search access to a file are granted the right to read ACLs. Only the
 110 file owner and processes capable of CAP_FOWNER are granted the right to
 111 modify ACLs. (On current Linux systems, root is the only user with the
 112 CAP_FOWNER capability.)
 113
 114 .SH DETERMINING ACCESS
 115 When a process requests access to a file, the following algorithm determines whether access is granted or not. The input to the algorithm is a set of requested permissions (read, write, execute).
 116
 117 .SS (1) "Find a matching ACL entry"
 118 .IP * 4
 119 If the user is the file owner, access is granted \fIonly\fR if the
 120 ACL_USER_OBJ entry contains the requested permissions.
 121 .IP * 4
 122 If the ACL contains a named user (ACL_USER) entry that matches the user, then:
 123 .RS
 124 .IP - 4
 125 If access is granted by that entry, continue with step \fB(2)\fR below.
 126 .IP - 4
 127 Otherwise, access is denied.
 128 .RE
 129 .IP * 4
 130 If the user is in the owning group of the file (ACL_GROUP_OBJ entry), or if the user is member of a named group (ACL_GROUP entries), then:
 131 .RS
 132 .IP - 4
 133 If either the ACL_GROUP_OBJ entry or one of the ACL_GROUP entries contains the requested permissions, continue with step \fB(2)\fR below. (Permissions of multiple ACL entries are
 134 .I not
 135 accumulated.)
 136 .IP - 4
 137 Otherwise, access is denied.
 138 .RE
 139 .IP * 4
 140 If none of the above rules match, then
 141 .RS
 142 .IP - 4
 143 If the ACL_OTHER entry contains the requested permissions, access is
 144 granted.
 145 .IP - 4
 146 Otherwise, access is denied.
 147 .RE
 148 .SS (2) Check the access mask
 149 .IP * 4
 150 If the access mask (ACL_MASK) contains the requested permissions, access is granted.
 151 .IP * 4
 152 Otherwise, access is denied.
 153 .SH DEFAULT ACCESS CONTROL LISTS
 154 Directories may have a default ACL, in addition to the regular ACL. While the
 155 purpose of the regular ACL is to control access to a file or directory,
 156 the purpose of the default ACL is to control access to files which are
 157 created inside the directory.
 158 .PP
 159 When a file is created,
 160 a create permissions are specified that determines the maximum access rights to
 161 the file. This usually is 0666 of files, and 0777 for directories.
 162 .PP
 163 Traditionally, the effective access rights to new files are determined by combining the
 164 .B umask
 165 and the create permissions. The default ACL replaces the role of the
 166 .BR umask .
 167 The following steps are taken when a file is created inside a directory which has a default ACL:
 168 .IP * 4
 169 The new file inherits the directory's default ACL as its access ACL.
 170 .IP * 4
 171 The permissions of the new file's access ACL are modified in the following way:
 172 .RS
 173 .IP - 4
 174 The ACL_USER entry is set to the union of the value determied by the default ACL and the user bits of the create permissions.
 175 .IP - 4
 176 The ACL_OTHER entry is set to the union of the value determined by the default ACL and the other bits of the create permissions.
 177 .IP - 4
 178 If the new file's ACL contains an ACL_MASK entry, the permission bits of the ACL_MASK entry are set to the group bits of the create permissions. If the new file's ACL does not contain an ACL_MASK entry, the permission bits of the ACL_GROUP_OBJ entry are set to the group bits of the create permissions.
 179 .RE
 180 .IP * 4
 181 The user and other part of the new file's mode bits are set to the ACL_USER_OBJ and ACL_OTHER permission bits, respectively.
 182 .IP * 4
 183 If the new file's ACL contains an ACL_MASK entry, the group bits of the new file's mode field are set to the ACL_MASK entry permission bits. If the new file's ACL does not contain an ACL_MASK entry, the group bits of the new file's mode field are set to the ACL_GROUP_OBJ entry permission bits.
 184 .IP * 4
 185 If the new file is a directory, it inherits the parent directory's default ACL as its own default ACL.
 186 .PP
 187 For directories without a default ACL, the
 188 .B umask
 189 is used to determine effective permissions (see
 190 .BR umask (2)).
 191 .PP
 192 .SH FILE MODE PERMISSION BITS TO ACL ENTRY MAPPING
 193 .fam C
 194 .nf
 195           user    group   other
 196     ----+-------+-------+-------+
 197         | r w x | r w x | r w x |
 198     ----+-------+-------+-------+
 199             ^       ^       ^
 200             |       |       +-- maps to ACL_OTHER
 201             |       +-- maps to ACL_GROUP_OBJ or ACL_MASK
 202             +-- maps to ACL_USER_OBJ
 203 .fi
 204 .fam T
 205 .PP
 206 .SH NFSv2, NFSv3 AND ACCESS CONTROL LISTS
 207 The NFS protocol in version 2 performs some access control decisions at
 208 the client, based on the file mode permission bits. It serves the user
 209 cached file contents if it thinks access would be granted. This logic
 210 is no longer correct if access control lists are in effect. Both false
 211 positives and denials might result.
 212
 213 As a workaround, the file mode permission bits are modified before
 214 sending them to NFSv2 clients. This ensures NFS clients don't grant
 215 extra permissions. (Only the kernel NFS daemon does that right now; the
 216 userspace NFS daemon has not been patched yet.) The file mode permission
 217 sent are a subset of the real file mode permission bits. They are changed
 218 as follows:
 219
 220 .IP * 4
 221 The group file mode permission bits are set to the intersection of the ACL_GROUP_OBJ and the ACL_MASK ACL entry.
 222 .IP * 4
 223 The others file mode permission bits are set to the intersection of all
 224 ACL entries excluding the ACL_USER_OBJ entry.
 225 .PP
 226 A consequence of these changes is that extended permissions granted by ACLs are not available over NFSv2 mounts.
 227
 228 Up to at least 2.2.18 and 2.4.2 kernels, the NFSv3 implementation does
 229 not implement the ACCESS remote procedure call. Therefore, NFSv3 currently
 230 suffers the same problems as NFSv2. The same workaround is employed right
 231 now.
 232
 233 .SH CHANGES TO THE FILE UTILITIES
 234 The
 235 .BR ls (1)
 236 utility displays a plus sign (`+') after the permission string of entries with an extended ACL (i.e., entries where the permission string shows only part of the effective permissions).
 237 .PP
 238 The
 239 .BR cp "(1) and " mv (1)
 240 utilities preserve ACLs if possible. If files are copied or moved between fileystems that do not support ACLs, only the file mode permission bits are preserved, and a warning is written to standard error.
 241 .PP
 242 The
 243 .BR chmod (1)
 244 utility is traditionally used to change the file mode permission bits.
 245 Changing the permission bits using
 246 .B chmod
 247 has the following effect on an ACL that is associated with a file:
 248 .IP * 4
 249 The new user permission bits replace the permissions of the owner ACL entry.
 250 .IP * 4
 251 The new group permission bits replace the permission bits of the mask ACL entry if a mask ACL entry exists. The new group permission bits replace the permission bits of the owning group ACL entry if no mask ACL entry exists.
 252 .IP * 4
 253 The new others permission bits replace the permissions of the others ACL entry.
 254 .PP
 255 .fam T
 256 .SH AUTHOR
 257 Andreas Gruenbacher,
 258 .RI < a.gruenbacher@computer.org >.
 259
 260 Please send your bug reports, suggested features and comments to the
 261 above address.
 262 .SH SEE ALSO
 263 getfacl(1), setfacl(1), chmod(1), umask(1), ls(1)