1.\"- 2.\" Copyright (c) 2001 Chris D. Faulhaber 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR THE VOICES IN HIS HEAD BE 18.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 7, 2001 29.Dt SETFACL 1 30.Os 31.Sh NAME 32.Nm setfacl 33.Nd set ACL information 34.Sh SYNOPSIS 35.Nm 36.Op Fl bdhkn 37.Op Fl m Ar entries 38.Op Fl M Ar file 39.Op Fl x Ar entries 40.Op Fl X Ar file 41.Op Ar 42.Sh DESCRIPTION 43The 44.Nm 45utility sets discretionary access control information on 46the specified file(s). 47If no files are specified, or the list consists of the only 48.Sq Fl , 49the file names are taken from the standard input. 50.Pp 51The following options are available: 52.Bl -tag -width indent 53.It Fl b 54Remove all ACL entries except for the three required entries. 55If the ACL contains a 56.Dq Li mask 57entry, the permissions of the 58.Dq Li group 59entry in the resulting ACL will be set to the permission 60associated with both the 61.Dq Li group 62and 63.Dq Li mask 64entries of the current ACL. 65.It Fl d 66The operations apply to the default ACL entries instead of 67access ACL entries. 68Currently only directories may have 69default ACL's. 70.It Fl h 71If the target of the operation is a symbolic link, perform the operation 72on the symbolic link itself, rather than following the link. 73.It Fl k 74Delete any default ACL entries on the specified files. 75It 76is not considered an error if the specified files do not have 77any default ACL entries. 78An error will be reported if any of 79the specified files cannot have a default entry (i.e.\& 80non-directories). 81.It Fl m Ar entries 82Modify the ACL entries on the specified files by adding new 83entries and modifying existing ACL entries with the ACL entries 84specified in 85.Ar entries . 86.It Fl M Ar file 87Modify the ACL entries on the specified files by adding new 88ACL entries and modifying existing ACL entries with the ACL 89entries specified in the file 90.Ar file . 91If 92.Ar file 93is 94.Fl , 95the input is taken from stdin. 96.It Fl n 97Do not recalculate the permissions associated with the ACL 98mask entry. 99.It Fl x Ar entries 100Remove the ACL entries specified in 101.Ar entries 102from the access or default ACL of the specified files. 103.It Fl X Ar file 104Remove the ACL entries specified in the file 105.Ar file 106from the access or default ACL of the specified files. 107.El 108.Pp 109The above options are evaluated in the order specified 110on the command-line. 111.Sh ACL ENTRIES 112An ACL entry contains three colon-separated fields: 113an ACL tag, an ACL qualifier, and discretionary access 114permissions: 115.Bl -tag -width indent 116.It Ar "ACL tag" 117The ACL tag specifies the ACL entry type and consists of 118one of the following: 119.Dq Li user 120or 121.Ql u 122specifying the access 123granted to the owner of the file or a specified user; 124.Dq Li group 125or 126.Ql g 127specifying the access granted to the file owning group 128or a specified group; 129.Dq Li other 130or 131.Ql o 132specifying the access 133granted to any process that does not match any user or group 134ACL entry; 135.Dq Li mask 136or 137.Ql m 138specifying the maximum access 139granted to any ACL entry except the 140.Dq Li user 141ACL entry for the file owner and the 142.Dq Li other 143ACL entry. 144.It Ar "ACL qualifier" 145The ACL qualifier field describes the user or group associated with 146the ACL entry. 147It may consist of one of the following: uid or 148user name, gid or group name, or empty. 149For 150.Dq Li user 151ACL entries, an empty field specifies access granted to the 152file owner. 153For 154.Dq Li group 155ACL entries, an empty field specifies access granted to the 156file owning group. 157.Dq Li mask 158and 159.Dq Li other 160ACL entries do not use this field. 161.It Ar "access permissions" 162The access permissions field contains up to one of each of 163the following: 164.Ql r , 165.Ql w , 166and 167.Ql x 168to set read, write, and 169execute permissions, respectively. 170Each of these may be excluded 171or replaced with a 172.Ql - 173character to indicate no access. 174.El 175.Pp 176A 177.Dq Li mask 178ACL entry is required on a file with any ACL entries other than 179the default 180.Dq Li user , 181.Dq Li group , 182and 183.Dq Li other 184ACL entries. 185If the 186.Fl n 187option is not specified and no 188.Dq Li mask 189ACL entry was specified, the 190.Nm 191utility 192will apply a 193.Dq Li mask 194ACL entry consisting of the union of the permissions associated 195with all 196.Dq Li group 197ACL entries in the resulting ACL. 198.Pp 199Traditional POSIX interfaces acting on file system object modes have 200modified semantics in the presence of POSIX.1e extended ACLs. 201When a mask entry is present on the access ACL of an object, the mask 202entry is substituted for the group bits; this occurs in programs such 203as 204.Xr stat 1 205or 206.Xr ls 1 . 207When the mode is modified on an object that has a mask entry, the 208changes applied to the group bits will actually be applied to the 209mask entry. 210These semantics provide for greater application compatibility: 211applications modifying the mode instead of the ACL will see 212conservative behavior, limiting the effective rights granted by all 213of the additional user and group entries; this occurs in programs 214such as 215.Xr chmod 1 . 216.Pp 217ACL entries applied from a file using the 218.Fl M 219or 220.Fl X 221options shall be of the following form: one ACL entry per line, as 222previously specified; whitespace is ignored; any text after a 223.Ql # 224is ignored (comments). 225.Pp 226When ACL entries are evaluated, the access check algorithm checks 227the ACL entries in the following order: file owner, 228.Dq Li user 229ACL entries, file owning group, 230.Dq Li group 231ACL entries, and 232.Dq Li other 233ACL entry. 234.Pp 235Multiple ACL entries specified on the command line are 236separated by commas. 237.Pp 238It is possible for files and directories to inherit ACL entries from their 239parent directory. 240This is accomplished through the use of the default ACL. 241It should be noted that before you can specify a default ACL, the mandatory 242ACL entries for user, group, other and mask must be set. 243For more details see the examples below. 244Default ACLs can be created by using 245.Fl d . 246.Sh EXIT STATUS 247.Ex -std 248.Sh EXAMPLES 249.Dl setfacl -d -m u::rwx,g::rx,o::rx,mask::rwx dir 250.Dl setfacl -d -m g:admins:rwx dir 251.Pp 252The first command sets the mandatory elements of the default ACL. 253The second command specifies that users in group admins can have read, write, and execute 254permissions for directory named "dir". 255It should be noted that any files or directories created underneath "dir" will 256inherit these default ACLs upon creation. 257.Pp 258.Dl setfacl -m u::rwx,g:mail:rw file 259.Pp 260Sets read, write, and execute permissions for the 261.Pa file 262owner's ACL entry and read and write permissions for group mail on 263.Pa file . 264.Pp 265.Dl setfacl -M file1 file2 266.Pp 267Sets/updates the ACL entries contained in 268.Pa file1 269on 270.Pa file2 . 271.Pp 272.Dl setfacl -x g:mail:rw file 273.Pp 274Remove the group mail ACL entry containing read/write permissions 275from 276.Pa file . 277.Pp 278.Dl setfacl -bn file 279.Pp 280Remove all 281.Dq Li access 282ACL entries except for the three required from 283.Pa file . 284.Pp 285.Dl getfacl file1 | setfacl -b -n -M - file2 286.Pp 287Copy ACL entries from 288.Pa file1 289to 290.Pa file2 . 291.Sh SEE ALSO 292.Xr getfacl 1 , 293.Xr acl 3 , 294.Xr getextattr 8 , 295.Xr setextattr 8 , 296.Xr acl 9 , 297.Xr extattr 9 298.Sh STANDARDS 299The 300.Nm 301utility is expected to be 302.Tn IEEE 303Std 1003.2c compliant. 304.Sh HISTORY 305Extended Attribute and Access Control List support was developed 306as part of the 307.Tn TrustedBSD 308Project and introduced in 309.Fx 5.0 . 310.Sh AUTHORS 311The 312.Nm 313utility was written by 314.An Chris D. Faulhaber Aq jedgar@fxp.org . 315