1SETFACL(1)                   Access Control Lists                   SETFACL(1)
2
3
4

NAME

6       setfacl - set file access control lists
7

SYNOPSIS

9       setfacl [-bkndRLPvh] [{-m|-x} acl_spec] [{-M|-X} acl_file] file ...
10
11       setfacl --restore=file
12
13

DESCRIPTION

15       This utility sets Access Control Lists (ACLs) of files and directories.
16       On the command line, a sequence of commands is followed by  a  sequence
17       of  files  (which  in  turn can be followed by another sequence of com‐
18       mands, ...).
19
20       The -m and -x options expect an ACL on the command line.  Multiple  ACL
21       entries  are separated by comma characters (`,'). The -M and -X options
22       read an ACL from a file or from standard input. The ACL entry format is
23       described in Section ACL ENTRIES.
24
25       The  --set and --set-file options set the ACL of a file or a directory.
26       The previous ACL is replaced.  ACL entries for this operation must  in‐
27       clude permissions.
28
29       The  -m  (--modify)  and -M (--modify-file) options modify the ACL of a
30       file or directory.  ACL entries for this operation must include permis‐
31       sions.
32
33       The -x (--remove) and -X (--remove-file) options remove ACL entries. It
34       is not an error to remove an entry which does not exist.  Only ACL  en‐
35       tries  without  the  perms  field  are  accepted  as parameters, unless
36       POSIXLY_CORRECT is defined.
37
38       When reading from files using the -M and -X  options,  setfacl  accepts
39       the  output getfacl produces.  There is at most one ACL entry per line.
40       After a Pound sign (`#'), everything up to  the  end  of  the  line  is
41       treated as a comment.
42
43       If  setfacl  is used on a file system which does not support ACLs, set‐
44       facl operates on the file mode permission bits. If the ACL does not fit
45       completely  in the permission bits, setfacl modifies the file mode per‐
46       mission bits to reflect the ACL as closely as possible, writes an error
47       message to standard error, and returns with an exit status greater than
48       0.
49
50
51   PERMISSIONS
52       The file owner and processes capable  of  CAP_FOWNER  are  granted  the
53       right  to  modify  ACLs of a file. This is analogous to the permissions
54       required for accessing the file mode. (On current Linux  systems,  root
55       is the only user with the CAP_FOWNER capability.)
56
57

OPTIONS

59       -b, --remove-all
60           Remove all extended ACL entries. The base ACL entries of the owner,
61           group and others are retained.
62
63       -k, --remove-default
64           Remove the Default ACL. If no Default ACL exists, no  warnings  are
65           issued.
66
67       -n, --no-mask
68           Do  not recalculate the effective rights mask. The default behavior
69           of setfacl is to recalculate the ACL mask entry, unless a mask  en‐
70           try  was  explicitly  given.  The mask entry is set to the union of
71           all permissions of the owning group, and all named user  and  group
72           entries.  (These  are  exactly the entries affected by the mask en‐
73           try).
74
75       --mask
76           Do recalculate the effective rights mask, even if an ACL mask entry
77           was explicitly given. (See the -n option.)
78
79       -d, --default
80           All operations apply to the Default ACL. Regular ACL entries in the
81           input set are promoted to Default ACL entries. Default ACL  entries
82           in  the  input set are discarded. (A warning is issued if that hap‐
83           pens).
84
85       --restore=file
86           Restore a permission backup created by `getfacl -R' or similar. All
87           permissions of a complete directory subtree are restored using this
88           mechanism. If the input contains owner comments or group  comments,
89           setfacl  attempts to restore the owner and owning group. If the in‐
90           put contains flags comments (which define the setuid,  setgid,  and
91           sticky bits), setfacl sets those three bits accordingly; otherwise,
92           it clears them. This option cannot be mixed with other options  ex‐
93           cept `--test'.
94
95       --test
96           Test mode. Instead of changing the ACLs of any files, the resulting
97           ACLs are listed.
98
99       -R, --recursive
100           Apply operations to all files and directories recursively. This op‐
101           tion cannot be mixed with `--restore'.
102
103       -L, --logical
104           Logical walk, follow symbolic links to directories. The default be‐
105           havior is to follow symbolic  link  arguments,  and  skip  symbolic
106           links encountered in subdirectories.  Only effective in combination
107           with -R.  This option cannot be mixed with `--restore'.
108
109       -P, --physical
110           Physical walk, do not follow symbolic links to  directories.   This
111           also  skips symbolic link arguments.  Only effective in combination
112           with -R.  This option cannot be mixed with `--restore'.
113
114       -v, --version
115           Print the version of setfacl and exit.
116
117       -h, --help
118           Print help explaining the command line options.
119
120       --  End of command line options. All remaining  parameters  are  inter‐
121           preted as file names, even if they start with a dash.
122
123       -   If  the  file name parameter is a single dash, setfacl reads a list
124           of files from standard input.
125
126
127   ACL ENTRIES
128       The setfacl utility recognizes the following ACL entry formats  (blanks
129       inserted for clarity):
130
131
132       [d[efault]:] [u[ser]:]uid [:perms]
133              Permissions  of  a  named user. Permissions of the file owner if
134              uid is empty.
135
136       [d[efault]:] g[roup]:gid [:perms]
137              Permissions of a named group. Permissions of the owning group if
138              gid is empty.
139
140       [d[efault]:] m[ask][:] [:perms]
141              Effective rights mask
142
143       [d[efault]:] o[ther][:] [:perms]
144              Permissions of others.
145
146       Whitespace between delimiter characters and non-delimiter characters is
147       ignored.
148
149       Proper ACL entries including permissions are used in modify and set op‐
150       erations.  (options -m, -M, --set and --set-file).  Entries without the
151       perms field are used for deletion of entries (options -x and -X).
152
153       For uid and gid you can specify either a name or a  number.   Character
154       literals  may be specified with a backslash followed by the 3-digit oc‐
155       tal digits corresponding to the ASCII code  for  the  character  (e.g.,
156       \101  for 'A').  If the name contains a literal backslash followed by 3
157       digits, the backslash must be escaped (i.e., \\).
158
159       The perms field is a combination of characters that indicate  the  read
160       (r),  write (w), execute (x) permissions.  Dash characters in the perms
161       field (-) are ignored.  The character X stands for the execute  permis‐
162       sion  if  the file is a directory or already has execute permission for
163       some user.  Alternatively, the perms field can define  the  permissions
164       numerically, as a bit-wise combination of read (4), write (2), and exe‐
165       cute (1).  Zero perms fields or  perms  fields  that  only  consist  of
166       dashes indicate no permissions.
167
168   AUTOMATICALLY CREATED ENTRIES
169       Initially,  files  and  directories contain only the three base ACL en‐
170       tries for the owner, the group, and others. There are some  rules  that
171       need to be satisfied in order for an ACL to be valid:
172
173       *   The three base entries cannot be removed. There must be exactly one
174           entry of each of these base entry types.
175
176       *   Whenever an ACL contains named user entries or named group objects,
177           it must also contain an effective rights mask.
178
179       *   Whenever an ACL contains any Default ACL entries, the three Default
180           ACL base entries (default owner, default group, and default others)
181           must also exist.
182
183       *   Whenever  a  Default ACL contains named user entries or named group
184           objects, it must also contain a default effective rights mask.
185
186       To help the user ensure these rules, setfacl creates entries  from  ex‐
187       isting entries under the following conditions:
188
189       *   If  an  ACL contains named user or named group entries, and no mask
190           entry exists, a mask entry containing the same permissions  as  the
191           group  entry is created. Unless the -n option is given, the permis‐
192           sions of the mask entry are further adjusted to include  the  union
193           of  all  permissions affected by the mask entry. (See the -n option
194           description).
195
196       *   If a Default ACL entry is created, and the Default ACL contains  no
197           owner, owning group, or others entry, a copy of the ACL owner, own‐
198           ing group, or others entry is added to the Default ACL.
199
200       *   If a Default ACL contains named user entries  or  named  group  en‐
201           tries,  and  no mask entry exists, a mask entry containing the same
202           permissions as the default Default ACL's group entry is added.  Un‐
203           less  the -n option is given, the permissions of the mask entry are
204           further adjusted to include the union of all  permissions  affected
205           by the mask entry. (See the -n option description).
206

EXAMPLES

208       Granting an additional user read access
209              setfacl -m u:lisa:r file
210
211       Revoking  write  access  from all groups and all named users (using the
212       effective rights mask)
213              setfacl -m m::rx file
214
215       Removing a named group entry from a file's ACL
216              setfacl -x g:staff file
217
218       Copying the ACL of one file to another
219              getfacl file1 | setfacl --set-file=- file2
220
221       Copying the access ACL into the Default ACL
222              getfacl --access dir | setfacl -d -M- dir
223

CONFORMANCE TO POSIX 1003.1e DRAFT STANDARD 17

225       If the environment variable POSIXLY_CORRECT is defined, the default be‐
226       havior of setfacl changes as follows: All non-standard options are dis‐
227       abled.  The ``default:'' prefix is disabled.  The  -x  and  -X  options
228       also accept permission fields (and ignore them).
229

AUTHOR

231       Andreas Gruenbacher, <andreas.gruenbacher@gmail.com>.
232
233       Please  send  your  bug reports, suggested features and comments to the
234       above address.
235

SEE ALSO

237       getfacl(1), chmod(1), umask(1), acl(5)
238
239
240
241May 2000                      ACL File Utilities                    SETFACL(1)
Impressum