2 .\" Copyright (c) 2001 Chris D. Faulhaber
3 .\" Copyright (c) 2011 Edward Tomasz NapieraĆa
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
34 .Nd set ACL information
38 .Op Fl a Ar position entries
41 .Op Fl x Ar entries | position
47 utility sets discretionary access control information on
48 the specified file(s).
49 If no files are specified, or the list consists of the only
51 the file names are taken from the standard input.
53 The following options are available:
54 .Bl -tag -width indent
55 .It Fl a Ar position entries
56 Modify the ACL on the specified files by inserting new
63 This option is only applicable to NFSv4 ACLs.
65 Remove all ACL entries except for the three required entries
66 (POSIX.1e ACLs) or six "canonical" entries (NFSv4 ACLs).
67 If the POSIX.1e ACL contains a
69 entry, the permissions of the
71 entry in the resulting ACL will be set to the permission
72 associated with both the
76 entries of the current ACL.
78 The operations apply to the default ACL entries instead of
80 Currently only directories may have
81 default ACL's. This option is not applicable to NFSv4 ACLs.
83 If the target of the operation is a symbolic link, perform the operation
84 on the symbolic link itself, rather than following the link.
86 Delete any default ACL entries on the specified files.
88 is not considered an error if the specified files do not have
89 any default ACL entries.
90 An error will be reported if any of
91 the specified files cannot have a default entry (i.e.\&
92 non-directories). This option is not applicable to NFSv4 ACLs.
94 Modify the ACL on the specified file.
95 New entries will be added, and existing entries will be modified
99 For NFSv4 ACLs, it is recommended to use the
105 Modify the ACL entries on the specified files by adding new
106 ACL entries and modifying existing ACL entries with the ACL
107 entries specified in the file
113 the input is taken from stdin.
115 Do not recalculate the permissions associated with the ACL
116 mask entry. This option is not applicable to NFSv4 ACLs.
117 .It Fl x Ar entries | position
120 is specified, remove the ACL entries specified there
121 from the access or default ACL of the specified files.
122 Otherwise, remove entry at index
126 Remove the ACL entries specified in the file
128 from the access or default ACL of the specified files.
131 The above options are evaluated in the order specified
133 .Sh POSIX.1e ACL ENTRIES
134 A POSIX.1E ACL entry contains three colon-separated fields:
135 an ACL tag, an ACL qualifier, and discretionary access
137 .Bl -tag -width indent
139 The ACL tag specifies the ACL entry type and consists of
140 one of the following:
144 specifying the access
145 granted to the owner of the file or a specified user;
149 specifying the access granted to the file owning group
150 or a specified group;
154 specifying the access
155 granted to any process that does not match any user or group
160 specifying the maximum access
161 granted to any ACL entry except the
163 ACL entry for the file owner and the
166 .It Ar "ACL qualifier"
167 The ACL qualifier field describes the user or group associated with
169 It may consist of one of the following: uid or
170 user name, gid or group name, or empty.
173 ACL entries, an empty field specifies access granted to the
177 ACL entries, an empty field specifies access granted to the
182 ACL entries do not use this field.
183 .It Ar "access permissions"
184 The access permissions field contains up to one of each of
190 to set read, write, and
191 execute permissions, respectively.
192 Each of these may be excluded
195 character to indicate no access.
200 ACL entry is required on a file with any ACL entries other than
209 option is not specified and no
211 ACL entry was specified, the
216 ACL entry consisting of the union of the permissions associated
219 ACL entries in the resulting ACL.
221 Traditional POSIX interfaces acting on file system object modes have
222 modified semantics in the presence of POSIX.1e extended ACLs.
223 When a mask entry is present on the access ACL of an object, the mask
224 entry is substituted for the group bits; this occurs in programs such
229 When the mode is modified on an object that has a mask entry, the
230 changes applied to the group bits will actually be applied to the
232 These semantics provide for greater application compatibility:
233 applications modifying the mode instead of the ACL will see
234 conservative behavior, limiting the effective rights granted by all
235 of the additional user and group entries; this occurs in programs
239 ACL entries applied from a file using the
243 options shall be of the following form: one ACL entry per line, as
244 previously specified; whitespace is ignored; any text after a
246 is ignored (comments).
248 When POSIX.1e ACL entries are evaluated, the access check algorithm checks
249 the ACL entries in the following order: file owner,
251 ACL entries, file owning group,
257 Multiple ACL entries specified on the command line are
260 It is possible for files and directories to inherit ACL entries from their
262 This is accomplished through the use of the default ACL.
263 It should be noted that before you can specify a default ACL, the mandatory
264 ACL entries for user, group, other and mask must be set.
265 For more details see the examples below.
266 Default ACLs can be created by using
268 .Sh NFSv4 ACL ENTRIES
269 An NFSv4 ACL entry contains four or five colon-separated fields: an ACL tag,
270 an ACL qualifier (only for
274 tags), discretionary access permissions, ACL inheritance flags, and ACL type:
275 .Bl -tag -width indent
277 The ACL tag specifies the ACL entry type and consists of
278 one of the following:
282 specifying the access
283 granted to the specified user;
287 specifying the access granted to the specified group;
289 specifying the access granted to the owner of the file;
291 specifying the access granted to the file owning group;
293 specifying everyone. Note that
295 is not the same as traditional Unix
298 literally, everyone, including file owner and owning group.
299 .It Ar "ACL qualifier"
300 The ACL qualifier field describes the user or group associated with
302 It may consist of one of the following: uid or
303 user name, or gid or group name. In entries whose tag type is
309 this field is omitted altogether, including the trailing comma.
310 .It Ar "access permissions"
311 Access permissions may be specified in either short or long form.
312 Short and long forms may not be mixed.
313 Permissions in long form are separated by the
315 character; in short form, they are concatenated together.
316 Valid permissions are:
317 .Bl -tag -width ".Dv modify_set"
350 In addition, the following permission sets may be used:
351 .Bl -tag -width ".Dv modify_set"
355 all permissions, as shown above
357 all permissions except write_acl and write_owner
359 read_data, read_attributes, read_xattr and read_acl
361 write_data, append_data, write_attributes and write_xattr
363 .It Ar "ACL inheritance flags"
364 Inheritance flags may be specified in either short or long form.
365 Short and long forms may not be mixed.
366 Access flags in long form are separated by the
368 character; in short form, they are concatenated together.
369 Valid inheritance flags are:
370 .Bl -tag -width ".Dv short"
385 Other than the "inherited" flag, inheritance flags may be only set on directories.
387 The ACL type field is either
393 ACL entries applied from a file using the
397 options shall be of the following form: one ACL entry per line, as
398 previously specified; whitespace is ignored; any text after a
400 is ignored (comments).
402 NFSv4 ACL entries are evaluated in their visible order.
404 Multiple ACL entries specified on the command line are
407 Note that the file owner is always granted the read_acl, write_acl,
408 read_attributes, and write_attributes permissions, even if the ACL
413 .Dl setfacl -d -m u::rwx,g::rx,o::rx,mask::rwx dir
414 .Dl setfacl -d -m g:admins:rwx dir
416 The first command sets the mandatory elements of the POSIX.1e default ACL.
417 The second command specifies that users in group admins can have read, write, and execute
418 permissions for directory named "dir".
419 It should be noted that any files or directories created underneath "dir" will
420 inherit these default ACLs upon creation.
422 .Dl setfacl -m u::rwx,g:mail:rw file
424 Sets read, write, and execute permissions for the
426 owner's POSIX.1e ACL entry and read and write permissions for group mail on
429 .Dl setfacl -m owner@:rwxp::allow,g:mail:rwp::allow file
431 Semantically equal to the example above, but for NFSv4 ACL.
433 .Dl setfacl -M file1 file2
435 Sets/updates the ACL entries contained in
440 .Dl setfacl -x g:mail:rw file
442 Remove the group mail POSIX.1e ACL entry containing read/write permissions
448 Remove the first entry from the NFSv4 ACL from
455 ACL entries except for the three required from
458 .Dl getfacl file1 | setfacl -b -n -M - file2
460 Copy ACL entries from
474 utility is expected to be
476 Std 1003.2c compliant.
478 Extended Attribute and Access Control List support was developed
481 Project and introduced in
483 NFSv4 ACL support was introduced in
489 utility was written by
490 .An Chris D. Faulhaber Aq jedgar@fxp.org .
491 NFSv4 ACL support was implemented by
492 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org .