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