1.\"- 2.\" Copyright (c) 2001 Chris D. Faulhaber 3.\" Copyright (c) 2011 Edward Tomasz NapieraĆa 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd April 29, 2023 28.Dt SETFACL 1 29.Os 30.Sh NAME 31.Nm setfacl 32.Nd set ACL information 33.Sh SYNOPSIS 34.Nm 35.Op Fl R Op Fl H | L | P 36.Op Fl bdhkn 37.Op Fl a Ar position entries 38.Op Fl m Ar entries 39.Op Fl M Ar file 40.Op Fl x Ar entries | position 41.Op Fl X Ar file 42.Op Ar 43.Sh DESCRIPTION 44The 45.Nm 46utility sets discretionary access control information on 47the specified file(s). 48If no files are specified, or the list consists of the only 49.Sq Fl , 50the file names are taken from the standard input. 51.Pp 52The following options are available: 53.Bl -tag -width indent 54.It Fl a Ar position entries 55Modify the ACL on the specified files by inserting new 56ACL entries 57specified in 58.Ar entries , 59starting at position 60.Ar position , 61counting from zero. 62This option is only applicable to NFSv4 ACLs. 63.It Fl b 64Remove all ACL entries except for the ones synthesized 65from the file mode - the three mandatory entries in case 66of POSIX.1e ACL. 67If the POSIX.1e ACL contains a 68.Dq Li mask 69entry, the permissions of the 70.Dq Li group 71entry in the resulting ACL will be set to the permission 72associated with both the 73.Dq Li group 74and 75.Dq Li mask 76entries of the current ACL. 77.It Fl d 78The operations apply to the default ACL entries instead of 79access ACL entries. 80Currently only directories may have 81default ACL's. 82This option is not applicable to NFSv4 ACLs. 83.It Fl h 84If the target of the operation is a symbolic link, perform the operation 85on the symbolic link itself, rather than following the link. 86.It Fl H 87If the 88.Fl R 89option is specified, symbolic links on the command line are followed 90and hence unaffected by the command. 91(Symbolic links encountered during tree traversal are not followed.) 92.It Fl k 93Delete any default ACL entries on the specified files. 94It 95is not considered an error if the specified files do not have 96any default ACL entries. 97An error will be reported if any of 98the specified files cannot have a default entry (i.e., 99non-directories). 100This option is not applicable to NFSv4 ACLs. 101.It Fl L 102If the 103.Fl R 104option is specified, all symbolic links are followed. 105.It Fl m Ar entries 106Modify the ACL on the specified file. 107New entries will be added, and existing entries will be modified 108according to the 109.Ar entries 110argument. 111For NFSv4 ACLs, it is recommended to use the 112.Fl a 113and 114.Fl x 115options instead. 116.It Fl M Ar file 117Modify the ACL entries on the specified files by adding new 118ACL entries and modifying existing ACL entries with the ACL 119entries specified in the file 120.Ar file . 121If 122.Ar file 123is 124.Fl , 125the input is taken from stdin. 126.It Fl n 127Do not recalculate the permissions associated with the ACL 128mask entry. 129This option is not applicable to NFSv4 ACLs. 130.It Fl P 131If the 132.Fl R 133option is specified, no symbolic links are followed. 134This is the default. 135.It Fl R 136Perform the action recursively on any specified directories. 137When modifying or adding NFSv4 ACL entries, inheritance flags 138are applied only to directories. 139.It Fl x Ar entries | position 140If 141.Ar entries 142is specified, remove the ACL entries specified there 143from the access or default ACL of the specified files. 144Otherwise, remove entry at index 145.Ar position , 146counting from zero. 147.It Fl X Ar file 148Remove the ACL entries specified in the file 149.Ar file 150from the access or default ACL of the specified files. 151.El 152.Pp 153The above options are evaluated in the order specified 154on the command-line. 155.Sh POSIX.1e ACL ENTRIES 156A POSIX.1E ACL entry contains three colon-separated fields: 157an ACL tag, an ACL qualifier, and discretionary access 158permissions: 159.Bl -tag -width indent 160.It Ar "ACL tag" 161The ACL tag specifies the ACL entry type and consists of 162one of the following: 163.Dq Li user 164or 165.Ql u 166specifying the access 167granted to the owner of the file or a specified user; 168.Dq Li group 169or 170.Ql g 171specifying the access granted to the file owning group 172or a specified group; 173.Dq Li other 174or 175.Ql o 176specifying the access 177granted to any process that does not match any user or group 178ACL entry; 179.Dq Li mask 180or 181.Ql m 182specifying the maximum access 183granted to any ACL entry except the 184.Dq Li user 185ACL entry for the file owner and the 186.Dq Li other 187ACL entry. 188.It Ar "ACL qualifier" 189The ACL qualifier field describes the user or group associated with 190the ACL entry. 191It may consist of one of the following: uid or 192user name, gid or group name, or empty. 193For 194.Dq Li user 195ACL entries, an empty field specifies access granted to the 196file owner. 197For 198.Dq Li group 199ACL entries, an empty field specifies access granted to the 200file owning group. 201.Dq Li mask 202and 203.Dq Li other 204ACL entries do not use this field. 205.It Ar "access permissions" 206The access permissions field contains up to one of each of 207the following: 208.Ql r , 209.Ql w , 210and 211.Ql x 212to set read, write, and 213execute permissions, respectively. 214Each of these may be excluded 215or replaced with a 216.Ql - 217character to indicate no access. 218.El 219.Pp 220A 221.Dq Li mask 222ACL entry is required on a file with any ACL entries other than 223the default 224.Dq Li user , 225.Dq Li group , 226and 227.Dq Li other 228ACL entries. 229If the 230.Fl n 231option is not specified and no 232.Dq Li mask 233ACL entry was specified, the 234.Nm 235utility 236will apply a 237.Dq Li mask 238ACL entry consisting of the union of the permissions associated 239with all 240.Dq Li group 241ACL entries in the resulting ACL. 242.Pp 243Traditional POSIX interfaces acting on file system object modes have 244modified semantics in the presence of POSIX.1e extended ACLs. 245When a mask entry is present on the access ACL of an object, the mask 246entry is substituted for the group bits; this occurs in programs such 247as 248.Xr stat 1 249or 250.Xr ls 1 . 251When the mode is modified on an object that has a mask entry, the 252changes applied to the group bits will actually be applied to the 253mask entry. 254These semantics provide for greater application compatibility: 255applications modifying the mode instead of the ACL will see 256conservative behavior, limiting the effective rights granted by all 257of the additional user and group entries; this occurs in programs 258such as 259.Xr chmod 1 . 260.Pp 261ACL entries applied from a file using the 262.Fl M 263or 264.Fl X 265options shall be of the following form: one ACL entry per line, as 266previously specified; whitespace is ignored; any text after a 267.Ql # 268is ignored (comments). 269.Pp 270When POSIX.1e ACL entries are evaluated, the access check algorithm checks 271the ACL entries in the following order: file owner, 272.Dq Li user 273ACL entries, file owning group, 274.Dq Li group 275ACL entries, and 276.Dq Li other 277ACL entry. 278.Pp 279Multiple ACL entries specified on the command line are 280separated by commas. 281.Pp 282It is possible for files and directories to inherit ACL entries from their 283parent directory. 284This is accomplished through the use of the default ACL. 285It should be noted that before you can specify a default ACL, the mandatory 286ACL entries for user, group, other and mask must be set. 287For more details see the examples below. 288Default ACLs can be created by using 289.Fl d . 290.Sh NFSv4 ACL ENTRIES 291An NFSv4 ACL entry contains four or five colon-separated fields: an ACL tag, 292an ACL qualifier (only for 293.Dq Li user 294and 295.Dq Li group 296tags), discretionary access permissions, ACL inheritance flags, and ACL type: 297.Bl -tag -width indent 298.It Ar "ACL tag" 299The ACL tag specifies the ACL entry type and consists of 300one of the following: 301.Dq Li user 302or 303.Ql u 304specifying the access 305granted to the specified user; 306.Dq Li group 307or 308.Ql g 309specifying the access granted to the specified group; 310.Dq Li owner@ 311specifying the access granted to the owner of the file; 312.Dq Li group@ 313specifying the access granted to the file owning group; 314.Dq Li everyone@ 315specifying everyone. 316Note that 317.Dq Li everyone@ 318is not the same as traditional Unix 319.Dq Li other 320- it means, 321literally, everyone, including file owner and owning group. 322.It Ar "ACL qualifier" 323The ACL qualifier field describes the user or group associated with 324the ACL entry. 325It may consist of one of the following: uid or 326user name, or gid or group name. 327In entries whose tag type is one of 328.Dq Li owner@ , 329.Dq Li group@ , 330or 331.Dq Li everyone@ , 332this field is omitted altogether, including the trailing colon. 333.It Ar "access permissions" 334Access permissions may be specified in either short or long form. 335Short and long forms may not be mixed. 336Permissions in long form are separated by the 337.Ql / 338character; in short form, they are concatenated together. 339Valid permissions are: 340.Bl -tag -width ".Dv modify_set" 341.It Short 342Long 343.It r 344read_data 345.It w 346write_data 347.It x 348execute 349.It p 350append_data 351.It D 352delete_child 353.It d 354delete 355.It a 356read_attributes 357.It A 358write_attributes 359.It R 360read_xattr 361.It W 362write_xattr 363.It c 364read_acl 365.It C 366write_acl 367.It o 368write_owner 369.It s 370synchronize 371.El 372.Pp 373In addition, the following permission sets may be used: 374.Bl -tag -width ".Dv modify_set" 375.It Set 376Permissions 377.It full_set 378all permissions, as shown above 379.It modify_set 380all permissions except write_acl and write_owner 381.It read_set 382read_data, read_attributes, read_xattr and read_acl 383.It write_set 384write_data, append_data, write_attributes and write_xattr 385.El 386.It Ar "ACL inheritance flags" 387Inheritance flags may be specified in either short or long form. 388Short and long forms may not be mixed. 389Access flags in long form are separated by the 390.Ql / 391character; in short form, they are concatenated together. 392Valid inheritance flags are: 393.Bl -tag -width ".Dv short" 394.It Short 395Long 396.It f 397file_inherit 398.It d 399dir_inherit 400.It i 401inherit_only 402.It n 403no_propagate 404.It I 405inherited 406.El 407.Pp 408Other than the "inherited" flag, inheritance flags may be only set on directories. 409.It Ar "ACL type" 410The ACL type field is either 411.Dq Li allow 412or 413.Dq Li deny . 414.El 415.Pp 416ACL entries applied from a file using the 417.Fl M 418or 419.Fl X 420options shall be of the following form: one ACL entry per line, as 421previously specified; whitespace is ignored; any text after a 422.Ql # 423is ignored (comments). 424.Pp 425NFSv4 ACL entries are evaluated in their visible order. 426.Pp 427Multiple ACL entries specified on the command line are 428separated by commas. 429.Pp 430Note that the file owner is always granted the read_acl, write_acl, 431read_attributes, and write_attributes permissions, even if the ACL 432would deny it. 433.Sh EXIT STATUS 434.Ex -std 435.Sh EXAMPLES 436.Dl setfacl -d -m u::rwx,g::rx,o::rx,mask::rwx dir 437.Dl setfacl -d -m g:admins:rwx dir 438.Pp 439The first command sets the mandatory elements of the POSIX.1e default ACL. 440The second command specifies that users in group admins can have read, write, and execute 441permissions for directory named "dir". 442It should be noted that any files or directories created underneath "dir" will 443inherit these default ACLs upon creation. 444.Pp 445.Dl setfacl -m u::rwx,g:mail:rw file 446.Pp 447Sets read, write, and execute permissions for the 448.Pa file 449owner's POSIX.1e ACL entry and read and write permissions for group mail on 450.Pa file . 451.Pp 452.Dl setfacl -m owner@:rwxp::allow,g:mail:rwp::allow file 453.Pp 454Semantically equal to the example above, but for NFSv4 ACL. 455.Pp 456.Dl setfacl -M file1 file2 457.Pp 458Sets/updates the ACL entries contained in 459.Pa file1 460on 461.Pa file2 . 462.Pp 463.Dl setfacl -x g:mail:rw file 464.Pp 465Remove the group mail POSIX.1e ACL entry containing read/write permissions 466from 467.Pa file . 468.Pp 469.Dl setfacl -x0 file 470.Pp 471Remove the first entry from the NFSv4 ACL from 472.Pa file . 473.Pp 474.Dl setfacl -bn file 475.Pp 476Remove all 477.Dq Li access 478ACL entries except for the three required from 479.Pa file . 480.Pp 481.Dl getfacl file1 | setfacl -b -n -M - file2 482.Pp 483Copy ACL entries from 484.Pa file1 485to 486.Pa file2 . 487.Sh SEE ALSO 488.Xr getfacl 1 , 489.Xr acl 3 , 490.Xr getextattr 8 , 491.Xr setextattr 8 , 492.Xr acl 9 , 493.Xr extattr 9 494.Sh STANDARDS 495The 496.Nm 497utility is expected to be 498.Tn IEEE 499Std 1003.2c compliant. 500.Sh HISTORY 501Extended Attribute and Access Control List support was developed 502as part of the 503.Tn TrustedBSD 504Project and introduced in 505.Fx 5.0 . 506NFSv4 ACL support was introduced in 507.Fx 8.1 . 508.Sh AUTHORS 509.An -nosplit 510The 511.Nm 512utility was written by 513.An Chris D. Faulhaber Aq Mt jedgar@fxp.org . 514NFSv4 ACL support was implemented by 515.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . 516