| blob | e49d18a185aae287ef4cff9ff4287bb5d57ed780 |
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
43 The
44 .Nm
45 utility sets discretionary access control information on
46 the specified file(s).
47 If no files are specified, or the list consists of the only
48 .Sq Fl ,
49 the file names are taken from the standard input.
50 .Pp
51 The following options are available:
52 .Bl -tag -width indent
53 .It Fl b
54 Remove all ACL entries except for the three required entries.
55 If the ACL contains a
56 .Dq Li mask
57 entry, the permissions of the
58 .Dq Li group
59 entry in the resulting ACL will be set to the permission
60 associated with both the
61 .Dq Li group
62 and
63 .Dq Li mask
64 entries of the current ACL.
65 .It Fl d
66 The operations apply to the default ACL entries instead of
67 access ACL entries.
68 Currently only directories may have
69 default ACL's.
70 .It Fl h
71 If the target of the operation is a symbolic link, perform the operation
72 on the symbolic link itself, rather than following the link.
73 .It Fl k
74 Delete any default ACL entries on the specified files.
75 It
76 is not considered an error if the specified files do not have
77 any default ACL entries.
78 An error will be reported if any of
79 the specified files cannot have a default entry (i.e.\&
80 non-directories).
81 .It Fl m Ar entries
82 Modify the ACL entries on the specified files by adding new
83 entries and modifying existing ACL entries with the ACL entries
84 specified in
85 .Ar entries .
86 .It Fl M Ar file
87 Modify the ACL entries on the specified files by adding new
88 ACL entries and modifying existing ACL entries with the ACL
89 entries specified in the file
90 .Ar file .
91 If
92 .Ar file
93 is
94 .Fl ,
95 the input is taken from stdin.
96 .It Fl n
97 Do not recalculate the permissions associated with the ACL
98 mask entry.
99 .It Fl x Ar entries
100 Remove the ACL entries specified in
101 .Ar entries
102 from the access or default ACL of the specified files.
103 .It Fl X Ar file
104 Remove the ACL entries specified in the file
105 .Ar file
106 from the access or default ACL of the specified files.
107 .El
108 .Pp
109 The above options are evaluated in the order specified
110 on the command-line.
111 .Sh ACL ENTRIES
112 An ACL entry contains three colon-separated fields:
113 an ACL tag, an ACL qualifier, and discretionary access
114 permissions:
115 .Bl -tag -width indent
116 .It Ar "ACL tag"
117 The ACL tag specifies the ACL entry type and consists of
118 one of the following:
119 .Dq Li user
120 or
121 .Ql u
122 specifying the access
123 granted to the owner of the file or a specified user;
124 .Dq Li group
125 or
126 .Ql g
127 specifying the access granted to the file owning group
128 or a specified group;
129 .Dq Li other
130 or
131 .Ql o
132 specifying the access
133 granted to any process that does not match any user or group
134 ACL entry;
135 .Dq Li mask
136 or
137 .Ql m
138 specifying the maximum access
139 granted to any ACL entry except the
140 .Dq Li user
141 ACL entry for the file owner and the
142 .Dq Li other
143 ACL entry.
144 .It Ar "ACL qualifier"
145 The ACL qualifier field describes the user or group associated with
146 the ACL entry.
147 It may consist of one of the following: uid or
148 user name, gid or group name, or empty.
149 For
150 .Dq Li user
151 ACL entries, an empty field specifies access granted to the
152 file owner.
153 For
154 .Dq Li group
155 ACL entries, an empty field specifies access granted to the
156 file owning group.
157 .Dq Li mask
158 and
159 .Dq Li other
160 ACL entries do not use this field.
161 .It Ar "access permissions"
162 The access permissions field contains up to one of each of
163 the following:
164 .Ql r ,
165 .Ql w ,
166 and
167 .Ql x
168 to set read, write, and
169 execute permissions, respectively.
170 Each of these may be excluded
171 or replaced with a
172 .Ql -
173 character to indicate no access.
174 .El
175 .Pp
176 A
177 .Dq Li mask
178 ACL entry is required on a file with any ACL entries other than
179 the default
180 .Dq Li user ,
181 .Dq Li group ,
182 and
183 .Dq Li other
184 ACL entries.
185 If the
186 .Fl n
187 option is not specified and no
188 .Dq Li mask
189 ACL entry was specified, the
190 .Nm
191 utility
192 will apply a
193 .Dq Li mask
194 ACL entry consisting of the union of the permissions associated
195 with all
196 .Dq Li group
197 ACL entries in the resulting ACL.
198 .Pp
199 Traditional POSIX interfaces acting on file system object modes have
200 modified semantics in the presence of POSIX.1e extended ACLs.
201 When a mask entry is present on the access ACL of an object, the mask
202 entry is substituted for the group bits; this occurs in programs such
203 as
204 .Xr stat 1
205 or
206 .Xr ls 1 .
207 When the mode is modified on an object that has a mask entry, the
208 changes applied to the group bits will actually be applied to the
209 mask entry.
210 These semantics provide for greater application compatibility:
211 applications modifying the mode instead of the ACL will see
212 conservative behavior, limiting the effective rights granted by all
213 of the additional user and group entries; this occurs in programs
214 such as
215 .Xr chmod 1 .
216 .Pp
217 ACL entries applied from a file using the
218 .Fl M
219 or
220 .Fl X
221 options shall be of the following form: one ACL entry per line, as
222 previously specified; whitespace is ignored; any text after a
223 .Ql #
224 is ignored (comments).
225 .Pp
226 When ACL entries are evaluated, the access check algorithm checks
227 the ACL entries in the following order: file owner,
228 .Dq Li user
229 ACL entries, file owning group,
230 .Dq Li group
231 ACL entries, and
232 .Dq Li other
233 ACL entry.
234 .Pp
235 Multiple ACL entries specified on the command line are
236 separated by commas.
237 .Pp
238 It is possible for files and directories to inherit ACL entries from their
239 parent directory.
240 This is accomplished through the use of the default ACL.
241 It should be noted that before you can specify a default ACL, the mandatory
242 ACL entries for user, group, other and mask must be set.
243 For more details see the examples below.
244 Default 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
252 The first command sets the mandatory elements of the default ACL.
253 The second command specifies that users in group admins can have read, write, and execute
254 permissions for directory named "dir".
255 It should be noted that any files or directories created underneath "dir" will
256 inherit these default ACLs upon creation.
257 .Pp
258 .Dl setfacl -m u::rwx,g:mail:rw file
259 .Pp
260 Sets read, write, and execute permissions for the
261 .Pa file
262 owner'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
267 Sets/updates the ACL entries contained in
268 .Pa file1
269 on
270 .Pa file2 .
271 .Pp
272 .Dl setfacl -x g:mail:rw file
273 .Pp
274 Remove the group mail ACL entry containing read/write permissions
275 from
276 .Pa file .
277 .Pp
278 .Dl setfacl -bn file
279 .Pp
280 Remove all
281 .Dq Li access
282 ACL entries except for the three required from
283 .Pa file .
284 .Pp
285 .Dl getfacl file1 | setfacl -b -n -M - file2
286 .Pp
287 Copy ACL entries from
288 .Pa file1
289 to
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
299 The
300 .Nm
301 utility is expected to be
302 .Tn IEEE
303 Std 1003.2c compliant.
304 .Sh HISTORY
305 Extended Attribute and Access Control List support was developed
306 as part of the
307 .Tn TrustedBSD
308 Project and introduced in
309 .Fx 5.0 .
310 .Sh AUTHORS
311 The
312 .Nm
313 utility was written by
314 .An Chris D. Faulhaber Aq jedgar@fxp.org .