1 '\" te
   2 .\"  Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright (c) 2020 Peter Tribble.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH SETFACL 1 "Feb 8, 2020"
   8 .SH NAME
   9 setfacl \- modify the Access Control List (ACL) for a file or files
  11 .nf
  12 \fBsetfacl\fR [\fB-r\fR] \fB-s\fR \fIacl_entries\fR \fIfile\fR
  13 .fi
  15 .LP
  16 .nf
  17 \fBsetfacl\fR [\fB-r\fR] \fB-md\fR \fIacl_entries\fR \fIfile\fR
  18 .fi
  20 .LP
  21 .nf
  22 \fBsetfacl\fR [\fB-r\fR] \fB-f\fR \fIacl_file\fR \fIfile\fR
  23 .fi
  26 For each file specified, \fBsetfacl\fR either replaces its entire \fBACL\fR,
  27 including the default \fBACL\fR on a directory, or it adds, modifies, or
  28 deletes one or more \fBACL\fR entries, including default entries on
  29 directories.
  30 .sp
  31 .LP
  32 The \fBsetfacl\fR utility can only manipulate POSIX-draft \fBACL\fRs.  See
  33 \fBacl\fR(5) for a description of the difference between the older POSIX-draft
  34 \fBACL\fRs and the newer NFSv4 \fBACL\fRs.  The \fBchmod\fR(1) utility can
  35 be used to manipulate \fBACL\fRs on all types of file system.
  36 .sp
  37 .LP
  38 When the \fBsetfacl\fR command is used, it can result in changes to the file
  39 permission bits. When the user \fBACL\fR entry for the file owner is changed,
  40 the file owner class permission bits are modified. When the group \fBACL\fR
  41 entry for the file group class is changed, the file group class permission bits
  42 are modified. When the other \fBACL\fR entry is changed, the file other class
  43 permission bits are modified.
  44 .sp
  45 .LP
  46 If you use the \fBchmod\fR(1) command to change the file group owner
  47 permissions on a file with \fBACL\fR entries, both the file group owner
  48 permissions and the \fBACL\fR mask are changed to the new permissions. Be aware
  49 that the new \fBACL\fR mask permissions can change the effective permissions
  50 for additional users and groups who have \fBACL\fR entries on the file.
  51 .sp
  52 .LP
  53 A directory can contain default \fBACL\fR entries. If a file or directory is
  54 created in a directory that contains default \fBACL\fR entries, the newly
  55 created file has permissions generated according to the intersection of the
  56 default \fBACL\fR entries and the permissions requested at creation time. The
  57 \fBumask\fR(1) are not applied if the directory contains default \fBACL\fR
  58 entries. If a default \fBACL\fR is specified for a specific user (or users),
  59 the file has a regular \fBACL\fR created. Otherwise, only the mode bits are
  60 initialized according to the intersection described above. The default
  61 \fBACL\fR should be thought of as the maximum discretionary access permissions
  62 that can be granted.
  63 .sp
  64 .LP
  65 Use the \fBsetfacl\fR command to set ACLs on files in a UFS file system, which
  66 supports POSIX-draft ACLS (or \fBaclent_t\fR style ACLs). Use the \fBchmod\fR
  67 command to set ACLs on files in a ZFS file system, which supports NFSv4-style
  68 ACLS (or \fBace_t\fR style ACLs).
  69 .SS "\fIacl_entries\fR Syntax"
  70 For the \fB-m\fR and \fB-s\fR options, \fIacl_entries\fR are one or more
  71 comma-separated \fBACL\fR entries.
  72 .sp
  73 .LP
  74 An \fBACL\fR entry consists of the following fields separated by colons:
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIentry_type\fR\fR
  79 .ad
  80 .RS 14n
  81 Type of \fBACL\fR entry on which to set file permissions. For example,
  82 \fIentry_type\fR can be \fBuser\fR (the owner of a file) or \fBmask\fR (the
  83 \fBACL\fR mask).
  84 .RE
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fIuid\fR or \fIgid\fR\fR
  90 .ad
  91 .RS 14n
  92 User name or user identification number. Or, group name or group identification
  93 number.
  94 .RE
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fIperms\fR\fR
 100 .ad
 101 .RS 14n
 102 Represents the permissions that are set on \fIentry_type\fR. \fIperms\fR can be
 103 indicated by the symbolic characters \fBrwx\fR or a number (the same
 104 permissions numbers used with the \fBchmod\fR command).
 105 .RE
 107 .sp
 108 .LP
 109 The following table shows the valid \fBACL\fR entries (default entries can only
 110 be specified for directories):
 111 .sp
 113 .sp
 114 .TS
 115 c c
 116 l l .
 117 \fBACL\fR Entry Description
 118 _
 119 u[ser]::\fIperms\fR     File owner permissions.
 120 g[roup]::\fIperms\fR    File group owner permissions.
 121 o[ther]:\fIperms\fR     T{
 122 Permissions for users other than the file owner or members of file group owner.
 123 T}
 124 m[ask]:\fIperms\fR      T{
 125 The \fBACL\fR mask. The mask entry indicates the maximum permissions allowed for users (other than the owner) and for groups. The mask is a quick way to change permissions on all the users and groups.
 126 T}
 127 u[ser]:\fIuid:perms\fR  T{
 128 Permissions for a specific user. For \fIuid\fR, you can specify either a user name or a numeric UID.
 129 T}
 130 g[roup]:\fIgid:perms\fR T{
 131 Permissions for a specific group. For \fIgid\fR, you can specify either a group name or a numeric GID.
 132 T}
 133 d[efault]:u[ser]::\fIperms\fR   Default file owner permissions.
 134 d[efault]:g[roup]::\fIperms\fR  Default file group owner permissions.
 135 d[efault]:o[ther]:\fIperms\fR   T{
 136 Default permissions for users other than the file owner or members of the file group owner.
 137 T}
 138 d[efault]:m[ask]:\fIperms\fR    Default \fBACL\fR mask.
 139 d[efault]:u[ser]:\fIuid\fR:\fIperms\fR  T{
 140 Default permissions for a specific user. For \fIuid\fR, you can specify either a user name or a numeric UID.
 141 T}
 142 d[efault]:g[roup]:\fIgid\fR:\fIperms\fR T{
 143 Default permissions for a specific group. For \fIgid\fR, you can specify either a group name or a numeric GID.
 144 T}
 145 .TE
 147 .sp
 148 .LP
 149 For the \fB-d\fR option, \fIacl_entries\fR are one or more comma-separated
 150 \fBACL\fR entries without permissions. Notice that the entries for file owner,
 151 file group owner, \fBACL\fR mask, and others can not be deleted.
 153 The options have the following meaning:
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fB-d\fR \fIacl_entries\fR\fR
 158 .ad
 159 .RS 18n
 160 Deletes one or more entries from the file. The entries for the file owner, the
 161 file group owner, and others can not be deleted from the \fBACL\fR. Notice that
 162 deleting an entry does not necessarily have the same effect as removing all
 163 permissions from the entry.
 164 .RE
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fB-f\fR \fIacl_file\fR\fR
 170 .ad
 171 .RS 18n
 172 Sets a file's \fBACL\fR with the \fBACL\fR entries contained in the file named
 173 \fIacl_file\fR. The same constraints on specified entries hold as with the
 174 \fB-s\fR option. The entries are not required to be in any specific order in
 175 the file. Also, if you specify a dash (\fB-\fR) for \fIacl_file\fR, standard
 176 input is used to set the file's \fBACL\fR.
 177 .sp
 178 The character \fB#\fR in \fIacl_file\fR can be used to indicate a comment. All
 179 characters, starting with the \fB#\fR until the end of the line, are ignored.
 180 Notice that if the \fIacl_file\fR has been created as the output of the
 181 \fBgetfacl\fR(1) command, any effective permissions, which follow a \fB#\fR,
 182 are ignored.
 183 .RE
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fB-m\fR \fIacl_entries\fR\fR
 189 .ad
 190 .RS 18n
 191 Adds one or more new \fBACL\fR entries to the file, and/or modifies one or more
 192 existing \fBACL\fR entries on the file. If an entry already exists for a
 193 specified \fIuid\fR or \fIgid\fR, the specified permissions replace the current
 194 permissions. If an entry does not exist for the specified \fIuid\fR or
 195 \fIgid\fR, an entry is created. When using the \fB-m\fR option to modify a
 196 default \fBACL\fR, you must specify a complete default \fBACL\fR (user, group,
 197 other, mask, and any additional entries) the first time.
 198 .RE
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fB-r\fR\fR
 204 .ad
 205 .RS 18n
 206 Recalculates the permissions for the \fBACL\fR mask entry. The permissions
 207 specified in the \fBACL\fR mask entry are ignored and replaced by the maximum
 208 permissions necessary to grant the access to all additional user, file group
 209 owner, and additional group entries in the \fBACL\fR. The permissions in the
 210 additional user, file group owner, and additional group entries are left
 211 unchanged.
 212 .RE
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fB-s\fR \fIacl_entries\fR\fR
 218 .ad
 219 .RS 18n
 220 Sets a file's \fBACL\fR. All old \fBACL\fR entries are removed and replaced
 221 with the newly specified \fBACL\fR. The entries need not be in any specific
 222 order. They are sorted by the command before being applied to the file.
 223 .sp
 224 Required entries:
 225 .RS +4
 226 .TP
 227 .ie t \(bu
 228 .el o
 229 Exactly one \fBuser\fR entry specified for the file owner.
 230 .RE
 231 .RS +4
 232 .TP
 233 .ie t \(bu
 234 .el o
 235 Exactly one \fBgroup\fR entry for the file group owner.
 236 .RE
 237 .RS +4
 238 .TP
 239 .ie t \(bu
 240 .el o
 241 Exactly one \fBother\fR entry specified.
 242 .RE
 243 If there are additional user and group entries:
 244 .RS +4
 245 .TP
 246 .ie t \(bu
 247 .el o
 248 Exactly one \fBmask\fR entry specified for the \fBACL\fR mask that indicates
 249 the maximum permissions allowed for users (other than the owner) and groups.
 250 .RE
 251 .RS +4
 252 .TP
 253 .ie t \(bu
 254 .el o
 255 Must not be duplicate \fBuser\fR entries with the same \fIuid\fR.
 256 .RE
 257 .RS +4
 258 .TP
 259 .ie t \(bu
 260 .el o
 261 Must not be duplicate \fBgroup\fR entries with the same \fIgid\fR.
 262 .RE
 263 If \fIfile\fR is a directory, the following default \fBACL\fR entries can be
 264 specified:
 265 .RS +4
 266 .TP
 267 .ie t \(bu
 268 .el o
 269 Exactly one \fBdefault user\fR entry for the file owner.
 270 .RE
 271 .RS +4
 272 .TP
 273 .ie t \(bu
 274 .el o
 275 Exactly one \fBdefault group\fR entry for the file group owner.
 276 .RE
 277 .RS +4
 278 .TP
 279 .ie t \(bu
 280 .el o
 281 Exactly one \fBdefault mask\fR entry for the \fBACL\fR mask.
 282 .RE
 283 .RS +4
 284 .TP
 285 .ie t \(bu
 286 .el o
 287 Exactly one \fBdefault other\fR entry.
 288 .RE
 289 There can be additional \fBdefault user\fR entries and additional \fBdefault
 290 group\fR entries specified, but there can not be duplicate additional
 291 \fBdefault user\fR entries with the same \fIuid\fR, or duplicate \fBdefault
 292 group\fR entries with the same \fIgid\fR.
 293 .RE
 296 \fBExample 1 \fRAdding read permission only
 297 .sp
 298 .LP
 299 The following example adds one \fBACL\fR entry to file \fBabc\fR, which gives
 300 user \fBshea\fR read permission only.
 302 .sp
 303 .in +2
 304 .nf
 305 \fBsetfacl -m user:shea:r\(mi\(mi abc\fR
 306 .fi
 307 .in -2
 308 .sp
 310 .LP
 311 \fBExample 2 \fRReplacing a file's entire \fBACL\fR
 312 .sp
 313 .LP
 314 The following example replaces the entire \fBACL\fR for the file \fBabc\fR,
 315 which gives \fBshea\fR read access, the file owner all access, the file group
 316 owner read access only, the \fBACL\fR mask read access only, and others no
 317 access.
 319 .sp
 320 .in +2
 321 .nf
 322 \fBsetfacl -s user:shea:rwx,user::rwx,group::rw-,mask:r--,other:--- abc\fR
 323 .fi
 324 .in -2
 325 .sp
 327 .sp
 328 .LP
 329 Notice that after this command, the file permission bits are \fBrwxr-----\fR.
 330 Even though the file group owner was set with read/write permissions, the
 331 \fBACL\fR mask entry limits it to have only read permission. The mask entry
 332 also specifies the maximum permissions available to all additional user and
 333 group \fBACL\fR entries. Once again, even though the user \fBshea\fR was set
 334 with all access, the mask limits it to have only read permission. The \fBACL\fR
 335 mask entry is a quick way to limit or open access to all the user and group
 336 entries in an \fBACL\fR. For example, by changing the mask entry to read/write,
 337 both the file group owner and user \fBshea\fR would be given read/write access.
 339 .LP
 340 \fBExample 3 \fRSetting the same \fBACL\fR on two files
 341 .sp
 342 .LP
 343 The following example sets the same \fBACL\fR on file \fBabc\fR as the file
 344 \fBxyz\fR.
 346 .sp
 347 .in +2
 348 .nf
 349 \fBgetfacl xyz | setfacl -f \(mi abc\fR
 350 .fi
 351 .in -2
 352 .sp
 354 .SH FILES
 355 .ne 2
 356 .na
 357 \fB\fB/etc/passwd\fR\fR
 358 .ad
 359 .RS 15n
 360 password file
 361 .RE
 363 .sp
 364 .ne 2
 365 .na
 366 \fB\fB/etc/group\fR\fR
 367 .ad
 368 .RS 15n
 369 group file
 370 .RE
 373 \fBchmod\fR(1), \fBgetfacl\fR(1), \fBumask\fR(1), \fBaclcheck\fR(3SEC),
 374 \fBaclsort\fR(3SEC), \fBgroup\fR(4), \fBpasswd\fR(4), \fBacl\fR(5),
 375 \fBattributes\fR(5)