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
37 .Op Fl R Op Fl H | L | P
39 .Op Fl a Ar position entries
42 .Op Fl x Ar entries | position
48 utility sets discretionary access control information on
49 the specified file(s).
50 If no files are specified, or the list consists of the only
52 the file names are taken from the standard input.
54 The following options are available:
55 .Bl -tag -width indent
56 .It Fl a Ar position entries
57 Modify the ACL on the specified files by inserting new
64 This option is only applicable to NFSv4 ACLs.
66 Remove all ACL entries except for the ones synthesized
67 from the file mode - the three mandatory entries in case
69 If the POSIX.1e ACL contains a
71 entry, the permissions of the
73 entry in the resulting ACL will be set to the permission
74 associated with both the
78 entries of the current ACL.
80 The operations apply to the default ACL entries instead of
82 Currently only directories may have
84 This option is not applicable to NFSv4 ACLs.
86 If the target of the operation is a symbolic link, perform the operation
87 on the symbolic link itself, rather than following the link.
91 option is specified, symbolic links on the command line are followed
92 and hence unaffected by the command.
93 (Symbolic links encountered during tree traversal are not followed.)
95 Delete any default ACL entries on the specified files.
97 is not considered an error if the specified files do not have
98 any default ACL entries.
99 An error will be reported if any of
100 the specified files cannot have a default entry (i.e.,
102 This option is not applicable to NFSv4 ACLs.
106 option is specified, all symbolic links are followed.
108 Modify the ACL on the specified file.
109 New entries will be added, and existing entries will be modified
113 For NFSv4 ACLs, it is recommended to use the
119 Modify the ACL entries on the specified files by adding new
120 ACL entries and modifying existing ACL entries with the ACL
121 entries specified in the file
127 the input is taken from stdin.
129 Do not recalculate the permissions associated with the ACL
131 This option is not applicable to NFSv4 ACLs.
135 option is specified, no symbolic links are followed.
138 Perform the action recursively on any specified directories.
139 When modifying or adding NFSv4 ACL entries, inheritance flags
140 are applied only to directories.
141 .It Fl x Ar entries | position
144 is specified, remove the ACL entries specified there
145 from the access or default ACL of the specified files.
146 Otherwise, remove entry at index
150 Remove the ACL entries specified in the file
152 from the access or default ACL of the specified files.
155 The above options are evaluated in the order specified
157 .Sh POSIX.1e ACL ENTRIES
158 A POSIX.1E ACL entry contains three colon-separated fields:
159 an ACL tag, an ACL qualifier, and discretionary access
161 .Bl -tag -width indent
163 The ACL tag specifies the ACL entry type and consists of
164 one of the following:
168 specifying the access
169 granted to the owner of the file or a specified user;
173 specifying the access granted to the file owning group
174 or a specified group;
178 specifying the access
179 granted to any process that does not match any user or group
184 specifying the maximum access
185 granted to any ACL entry except the
187 ACL entry for the file owner and the
190 .It Ar "ACL qualifier"
191 The ACL qualifier field describes the user or group associated with
193 It may consist of one of the following: uid or
194 user name, gid or group name, or empty.
197 ACL entries, an empty field specifies access granted to the
201 ACL entries, an empty field specifies access granted to the
206 ACL entries do not use this field.
207 .It Ar "access permissions"
208 The access permissions field contains up to one of each of
214 to set read, write, and
215 execute permissions, respectively.
216 Each of these may be excluded
219 character to indicate no access.
224 ACL entry is required on a file with any ACL entries other than
233 option is not specified and no
235 ACL entry was specified, the
240 ACL entry consisting of the union of the permissions associated
243 ACL entries in the resulting ACL.
245 Traditional POSIX interfaces acting on file system object modes have
246 modified semantics in the presence of POSIX.1e extended ACLs.
247 When a mask entry is present on the access ACL of an object, the mask
248 entry is substituted for the group bits; this occurs in programs such
253 When the mode is modified on an object that has a mask entry, the
254 changes applied to the group bits will actually be applied to the
256 These semantics provide for greater application compatibility:
257 applications modifying the mode instead of the ACL will see
258 conservative behavior, limiting the effective rights granted by all
259 of the additional user and group entries; this occurs in programs
263 ACL entries applied from a file using the
267 options shall be of the following form: one ACL entry per line, as
268 previously specified; whitespace is ignored; any text after a
270 is ignored (comments).
272 When POSIX.1e ACL entries are evaluated, the access check algorithm checks
273 the ACL entries in the following order: file owner,
275 ACL entries, file owning group,
281 Multiple ACL entries specified on the command line are
284 It is possible for files and directories to inherit ACL entries from their
286 This is accomplished through the use of the default ACL.
287 It should be noted that before you can specify a default ACL, the mandatory
288 ACL entries for user, group, other and mask must be set.
289 For more details see the examples below.
290 Default ACLs can be created by using
292 .Sh NFSv4 ACL ENTRIES
293 An NFSv4 ACL entry contains four or five colon-separated fields: an ACL tag,
294 an ACL qualifier (only for
298 tags), discretionary access permissions, ACL inheritance flags, and ACL type:
299 .Bl -tag -width indent
301 The ACL tag specifies the ACL entry type and consists of
302 one of the following:
306 specifying the access
307 granted to the specified user;
311 specifying the access granted to the specified group;
313 specifying the access granted to the owner of the file;
315 specifying the access granted to the file owning group;
320 is not the same as traditional Unix
323 literally, everyone, including file owner and owning group.
324 .It Ar "ACL qualifier"
325 The ACL qualifier field describes the user or group associated with
327 It may consist of one of the following: uid or
328 user name, or gid or group name.
329 In entries whose tag type is one of
334 this field is omitted altogether, including the trailing comma.
335 .It Ar "access permissions"
336 Access permissions may be specified in either short or long form.
337 Short and long forms may not be mixed.
338 Permissions in long form are separated by the
340 character; in short form, they are concatenated together.
341 Valid permissions are:
342 .Bl -tag -width ".Dv modify_set"
375 In addition, the following permission sets may be used:
376 .Bl -tag -width ".Dv modify_set"
380 all permissions, as shown above
382 all permissions except write_acl and write_owner
384 read_data, read_attributes, read_xattr and read_acl
386 write_data, append_data, write_attributes and write_xattr
388 .It Ar "ACL inheritance flags"
389 Inheritance flags may be specified in either short or long form.
390 Short and long forms may not be mixed.
391 Access flags in long form are separated by the
393 character; in short form, they are concatenated together.
394 Valid inheritance flags are:
395 .Bl -tag -width ".Dv short"
410 Other than the "inherited" flag, inheritance flags may be only set on directories.
412 The ACL type field is either
418 ACL entries applied from a file using the
422 options shall be of the following form: one ACL entry per line, as
423 previously specified; whitespace is ignored; any text after a
425 is ignored (comments).
427 NFSv4 ACL entries are evaluated in their visible order.
429 Multiple ACL entries specified on the command line are
432 Note that the file owner is always granted the read_acl, write_acl,
433 read_attributes, and write_attributes permissions, even if the ACL
438 .Dl setfacl -d -m u::rwx,g::rx,o::rx,mask::rwx dir
439 .Dl setfacl -d -m g:admins:rwx dir
441 The first command sets the mandatory elements of the POSIX.1e default ACL.
442 The second command specifies that users in group admins can have read, write, and execute
443 permissions for directory named "dir".
444 It should be noted that any files or directories created underneath "dir" will
445 inherit these default ACLs upon creation.
447 .Dl setfacl -m u::rwx,g:mail:rw file
449 Sets read, write, and execute permissions for the
451 owner's POSIX.1e ACL entry and read and write permissions for group mail on
454 .Dl setfacl -m owner@:rwxp::allow,g:mail:rwp::allow file
456 Semantically equal to the example above, but for NFSv4 ACL.
458 .Dl setfacl -M file1 file2
460 Sets/updates the ACL entries contained in
465 .Dl setfacl -x g:mail:rw file
467 Remove the group mail POSIX.1e ACL entry containing read/write permissions
473 Remove the first entry from the NFSv4 ACL from
480 ACL entries except for the three required from
483 .Dl getfacl file1 | setfacl -b -n -M - file2
485 Copy ACL entries from
499 utility is expected to be
501 Std 1003.2c compliant.
503 Extended Attribute and Access Control List support was developed
506 Project and introduced in
508 NFSv4 ACL support was introduced in
514 utility was written by
515 .An Chris D. Faulhaber Aq Mt jedgar@fxp.org .
516 NFSv4 ACL support was implemented by
517 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org .