Print this page
12288 getfacl and setfacl could stand improvement
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man5/acl.5.man.txt
+++ new/usr/src/man/man5/acl.5.man.txt
1 1 ACL(5) Standards, Environments, and Macros ACL(5)
2 2
3 3
4 4
5 5 NAME
6 6 acl - Access Control Lists
7 7
8 8 DESCRIPTION
9 9 Access control lists (ACLs) are discretionary access control mechanisms
10 10 that grant and deny access to files and directories. Two different ACL
11 - models are supported in the Solaris release: POSIX-draft ACLs and NFSv4
12 - ACLs.
11 + models are supported in this release: POSIX-draft ACLs and NFSv4 ACLs.
13 12
14 13
15 14 The older, POSIX-draft model is supported by the UFS file system. This
16 15 model is based on a withdrawn ACL POSIX specification that was never
17 16 standardized. It was subsequently withdrawn by the POSIX committee.
18 17
19 18
20 19 The other model is based on the standards of the NFSv4 working group
21 20 and is an approved standard from the Internet Engineering Task Force
22 21 (IETF). The ZFS file system uses the NFSv4 model, and provides richer
23 22 semantics and finer grained permission capabilities than the POSIX-
24 23 draft model.
25 24
26 25 POSIX-draft ACLs
27 26 POSIX-draft ACLs provide an alternative security mechanism to basic
28 - UNIX file permissions in the Solaris release. Their purpose is to
29 - further restrict access to files and directories or to extend
30 - permissions to a particular user. ACLs can be used to change the
31 - permissions for the standard owner, group and other class bits of a
32 - file's mode. ACLs can give additional users and groups access to the
33 - file. A directory can also have a special kind of ACL called a default
34 - ACL, which defines ACL entries to be inherited by descendents of the
35 - directory. POSIX-draft ACLs have an ACL entry called mask. The mask
36 - defines the maximum permissions that can be granted to additional user
37 - and group entries. Whenever a file is created or its mode is changed by
38 - chmod(1) or chmod(2), the mask is recomputed. It is recomputed to be
39 - the group permission defined in the mode passed to chmod(2).
27 + UNIX file permissions. Their purpose is to further restrict access to
28 + files and directories or to extend permissions to a particular user.
29 + ACLs can be used to change the permissions for the standard owner,
30 + group and other class bits of a file's mode. ACLs can give additional
31 + users and groups access to the file. A directory can also have a
32 + special kind of ACL called a default ACL, which defines ACL entries to
33 + be inherited by descendents of the directory. POSIX-draft ACLs have an
34 + ACL entry called mask. The mask defines the maximum permissions that
35 + can be granted to additional user and group entries. Whenever a file is
36 + created or its mode is changed by chmod(1) or chmod(2), the mask is
37 + recomputed. It is recomputed to be the group permission defined in the
38 + mode passed to chmod(2).
40 39
41 40
42 41 The POSIX-draft ACL model uses the standard rwx model of traditional
43 42 UNIX permissions.
44 43
45 44
46 45 An ACL is represented as follows:
47 46
48 47 acl_entry[,acl_entry]...
49 48
50 49
51 50
52 51
53 52 Each acl_entry contains one ACL entry. An ACL entry is represented by
54 53 two or three colon-separated(:) fields.
55 54
56 55 user:[uid]:perms
57 56 If uid blank, it represents the file owner.
58 57
59 58
60 59 group:[gid]:perms
61 60 If gid is blank, it represents the owning group.
62 61
63 62
64 63 other:perms
65 64 Represents the file other class.
66 65
67 66
68 67 mask:perms
69 68 Defines the MAX permission to hand out.
70 69
|
↓ open down ↓ |
21 lines elided |
↑ open up ↑ |
71 70
72 71
73 72 For example to give user joe read and write permissions, the ACL entry
74 73 is specified as:
75 74
76 75 user:joe:rw-
77 76
78 77
79 78
80 79 NFSv4 ACLs
81 - NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4
80 + The NFSv4 ACL model is based loosely on the Windows NT ACL model. NFSv4
82 81 ACLs provide a much richer ACL model than POSIX-draft ACLs.
83 82
84 83
85 84 The major differences between NFSv4 and POSIX-draft ACLs are as
86 85 follows:
87 86
88 87 o NFSv4 ACLs provide finer grained permissions than the rwx
89 88 model.
90 89
91 90 o NFSv4 ACLs allow for both ALLOW and DENY entries.
92 91
93 92 o NFSv4 ACLs provide a rich set of inheritance semantics.
94 93 POSIX ACLs also have inheritance, but with the NFSv4 model
95 94 you can control the following inheritance features:
|
↓ open down ↓ |
4 lines elided |
↑ open up ↑ |
96 95
97 96 o Whether inheritance cascades to both files and
98 97 directories or only to files or directories.
99 98
100 99 o In the case of directories, you can indicate whether
101 100 inheritance is applied to the directory itself, to just
102 101 one level of subdirectories, or cascades to all
103 102 subdirectories of the directory.
104 103
105 104 o NFSv4 ACLs provide a mechanism for hooking into a system's
106 - audit trail. Currently, Solaris does not support this
105 + audit trail. Currently, illumos does not support this
107 106 mechanism.
108 107
109 108 o NFSv4 ACLs enable administrators to specify the order in
110 109 which ACL entries are checked. With POSIX-draft ACLs the
111 110 file system reorders ACL entries into a well defined, strict
112 111 access, checking order.
113 112
114 113
115 114 POSIX-draft ACL semantics can be achieved with NFSv4 ACLs. However,
116 115 only some NFSv4 ACLs can be translated to equivalent POSIX-draft ACLs.
117 116
118 117
119 118 Permissions can be specified in three different chmod ACL formats:
120 119 verbose, compact, or positional. The verbose format uses words to
121 120 indicate that the permissions are separated with a forward slash (/)
122 121 character. Compact format uses the permission letters and positional
123 122 format uses the permission letters or the hyphen (-) to identify no
124 123 permissions.
125 124
126 125
127 126 The permissions for verbose mode and their abbreviated form in
128 127 parentheses for compact and positional mode are described as follows:
129 128
130 129 read_data (r)
131 130 Permission to read the data of the file
132 131
133 132
134 133 list_directory (r)
135 134 Permission to list the contents of a directory.
136 135
137 136
138 137 write_data (w)
139 138 Permission to modify a file's data anywhere in
140 139 the file's offset range. This includes the
141 140 ability to grow the file or write to any
142 141 arbitrary offset.
143 142
144 143
145 144 add_file (w)
146 145 Permission to add a new file to a directory.
147 146
148 147
149 148 append_data (p)
150 149 The ability to modify the file's data, but only
151 150 starting at EOF. Currently, this permission is
152 151 not supported.
153 152
154 153
155 154 add_subdirectory (p)
156 155 Permission to create a subdirectory to a
157 156 directory.
158 157
159 158
160 159 read_xattr (R)
161 160 The ability to read the extended attributes of
162 161 a file or do a lookup in the extended
163 162 attributes directory.
164 163
165 164
166 165 write_xattr (W)
167 166 The ability to create extended attributes or
168 167 write to the extended attributes directory.
169 168
170 169
171 170 execute (x)
172 171 Permission to execute a file.
173 172
174 173
175 174 read_attributes (a)
176 175 The ability to read basic attributes (non-ACLs)
177 176 of a file. Basic attributes are considered to
178 177 be the stat level attributes. Allowing this
179 178 access mask bit means that the entity can
180 179 execute ls(1) and stat(2).
181 180
182 181
183 182 write_attributes (A)
184 183 Permission to change the times associated with
185 184 a file or directory to an arbitrary value.
186 185
187 186
188 187 delete (d)
189 188 Permission to delete the file.
190 189
191 190
192 191 delete_child (D)
193 192 Permission to delete a file within a directory.
194 193
195 194
196 195 read_acl (c)
197 196 Permission to read the ACL.
198 197
199 198
200 199 write_acl (C)
201 200 Permission to write the ACL or the ability to
202 201 execute chmod(1) or setfacl(1).
203 202
204 203
205 204 write_owner (o)
206 205 Permission to change the owner or the ability
207 206 to execute chown(1) or chgrp(1).
208 207
209 208
210 209 synchronize (s)
211 210 Permission to access a file locally at the
212 211 server with synchronous reads and writes.
213 212 Currently, this permission is not supported.
214 213
215 214
216 215
217 216 The following inheritance flags are supported by NFSv4 ACLs:
218 217
219 218 file_inherit (f)
220 219 Inherit to all newly created files in a
221 220 directory.
222 221
223 222
224 223 dir_inherit (d)
225 224 Inherit to all newly created directories in a
226 225 directory.
227 226
228 227
229 228 inherit_only (i)
230 229 Placed on a directory, but does not apply to
231 230 the directory itself, only to newly created
232 231 files and directories. This flag requires
233 232 file_inherit and/or dir_inherit to indicate
234 233 what to inherit.
235 234
236 235
237 236 no_propagate (n)
238 237 Placed on directories and indicates that ACL
239 238 entries should only be inherited one level of
240 239 the tree. This flag requires file_inherit
241 240 and/or dir_inherit to indicate what to
242 241 inherit.
243 242
244 243
245 244 successful_access (S)
246 245 Indicates whether an alarm or audit record
247 246 should be initiated upon successful accesses.
248 247 Used with audit/alarm ACE types.
249 248
250 249
251 250 failed_access (F)
252 251 Indicates whether an alarm or audit record
253 252 should be initiated when access fails. Used
254 253 with audit/alarm ACE types.
255 254
256 255
257 256 inherited (I)
258 257 ACE was inherited.
259 258
260 259
261 260 -
262 261 No permission granted.
263 262
264 263
265 264
266 265 An NFSv4 ACL is expressed using the following syntax:
267 266
268 267 acl_entry[,acl_entry]...
269 268
270 269 owner@:<perms>[:inheritance flags]:<allow|deny>
271 270 group@:<perms>[:inheritance flags]:<allow|deny>
272 271 everyone@:<perms>[:inheritance flags]:<allow|deny>
273 272 user:<username>:<perms>[:inheritance flags]:<allow|deny>
274 273 usersid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
275 274 group:<groupname>:<perms>[:inheritance flags]:<allow|deny>
276 275 groupsid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
277 276 sid:<sid string>:<perms>[:inheritance flags]:<allow|deny>
278 277
279 278
280 279 owner@
281 280 File owner
282 281
283 282
284 283 group@
285 284 Group owner
286 285
287 286
288 287 user
289 288 Permissions for a specific user
290 289
291 290
292 291 group
293 292 Permissions for a specific group
294 293
295 294
296 295
297 296 Permission and inheritance flags are separated by a / character.
298 297
299 298
300 299 ACL specification examples:
301 300
302 301 user:fred:read_data/write_data/read_attributes:file_inherit:allow
303 302 owner@:read_data:allow,group@:read_data:allow,user:tom:read_data:deny
304 303
305 304
306 305
307 306
308 307 Using the compact ACL format, permissions are specified by using 14
309 308 unique letters to indicate permissions.
310 309
311 310
312 311 Using the positional ACL format, permissions are specified as
313 312 positional arguments similar to the ls -V format. The hyphen (-), which
314 313 indicates that no permission is granted at that position, can be
315 314 omitted and only the required letters have to be specified.
316 315
317 316
318 317 The letters above are listed in the order they would be specified in
319 318 positional notation.
320 319
321 320
322 321 With these letters you can specify permissions in the following
323 322 equivalent ways.
324 323
325 324 user:fred:rw------R------:file_inherit:allow
326 325
327 326
328 327
329 328
330 329 Or you can remove the - and scrunch it together.
331 330
332 331 user:fred:rwR:file_inherit:allow
333 332
334 333
|
↓ open down ↓ |
218 lines elided |
↑ open up ↑ |
335 334
336 335
337 336 The inheritance flags can also be specified in a more compact manner,
338 337 as follows:
339 338
340 339 user:fred:rwR:f:allow
341 340 user:fred:rwR:f------:allow
342 341
343 342
344 343
345 - Shell-level Solaris API
346 - The Solaris command interface supports the manipulation of ACLs. The
347 - following Solaris utilities accommodate both ACL models:
344 + Shell-level API
345 + Several utilities support the manipulation of ACLs. The following
346 + utilities accommodate both ACL models:
348 347
349 348 chmod
350 349 The chmod utility has been enhanced to allow for the
351 350 setting and deleting of ACLs. This is achieved by extending
352 351 the symbolic-mode argument to support ACL manipulation. See
353 352 chmod(1) for details.
354 353
355 354
356 355 compress
357 356 When a file is compressed any ACL associated with the
358 357 original file is preserved with the compressed file.
359 358
360 359
361 360 cp
362 361 By default, cp ignores ACLs, unless the -p option is
363 362 specified. When -p is specified the owner and group id,
364 363 permission modes, modification and access times, ACLs, and
365 364 extended attributes if applicable are preserved.
366 365
367 366
368 367 cpio
369 368 ACLs are preserved when the -P option is specified.
370 369
371 370
372 371 find
373 372 Find locates files with ACLs when the -acl flag is
374 373 specified.
375 374
376 375
377 376 ls
378 377 By default ls does not display ACL information. When the -v
379 378 option is specified, a file's ACL is displayed.
380 379
381 380
382 381 mv
383 382 When a file is moved, all attributes are carried along with
384 383 the renamed file. When a file is moved across a file
385 384 system boundary, the ACLs are replicated. If the ACL
386 385 information cannot be replicated, the move fails and the
387 386 source file is not removed.
388 387
389 388
390 389 pack
391 390 When a file is packed, any ACL associated with the original
392 391 file is preserved with the packed file.
393 392
394 393
395 394 rcp
396 395 rcp has been enhanced to support copying. A file's ACL is
397 396 only preserved when the remote host supports ACLs.
398 397
399 398
400 399 tar
401 400 ACLs are preserved when the -p option is specified.
|
↓ open down ↓ |
44 lines elided |
↑ open up ↑ |
402 401
403 402
404 403 unpack
405 404 When a file with an ACL is unpacked, the unpacked file
406 405 retains the ACL information.
407 406
408 407
409 408 Application-level API
410 409 The primary interfaces required to access file system ACLs at the
411 410 programmatic level are the acl_get() and acl_set() functions. These
412 - functions support both POSIX draft ACLs and NFSv4 ACLs.
411 + functions support both POSIX-draft ACLs and NFSv4 ACLs.
413 412
414 413 Retrieving a file's ACL
415 414 int acl_get(const char *path, int flag, acl_t **aclp);
416 415 int facl_get(int fd, int flag, acl_t **aclp);
417 416
418 417
419 418
420 - The acl_get(3SEC) and facl_get(3SEC) functions retrieves an ACL on a
419 + The acl_get(3SEC) and facl_get(3SEC) functions retrieve an ACL on a
421 420 file whose name is given by path or referenced by the open file
422 421 descriptor fd. The flag argument specifies whether a trivial ACL should
423 - be retrieved. When the flag argument equals ACL_NO_TRIVIAL then only
424 - ACLs that are not trivial are retrieved. The ACL is returned in the
425 - aclp argument.
422 + be retrieved. When the flag argument equals ACL_NO_TRIVIAL only ACLs
423 + that are not trivial are retrieved. The ACL is returned in the aclp
424 + argument.
426 425
427 426 Freeing ACL structure
428 - void acl_free(acl_t *aclp)s;
427 + void acl_free(acl_t *aclp);
429 428
430 429
431 430
432 431 The acl_free() function frees up memory allocated for the argument
433 - aclp;.
432 + aclp.
434 433
435 434 Setting an ACL on a file
436 435 int acl_set(const char *path, acl_t *aclp);
437 436 int facl_set(int fd, acl_t *aclp);
438 437
439 438
440 439
441 440 The acl_set(3SEC) and facl_get(3SEC) functions are used for setting an
442 441 ACL on a file whose name is given by path or referenced by the open
443 442 file descriptor fd. The aclp argument specifies the ACL to set. The
444 - acl_set(3SEC) translates an POSIX-draft ACL into a NFSv4 ACL when the
445 - target file systems supports NFSv4 ACLs. No translation is performed
446 - when trying to set an NFSv4 ACL on a POSIX-draft ACL supported file
447 - system.
443 + acl_set(3SEC) function translates a POSIX-draft ACL into a NFSv4 ACL
444 + when the target file system supports NFSv4 ACLs. No translation is
445 + performed when trying to set an NFSv4 ACL on a POSIX-draft ACL
446 + supported file system.
448 447
449 448 Determining an ACL's trivialness
450 449 int acl_trivial(const char *path);
451 450
452 451
453 452
454 453 The acl_trivial() function is used to determine whether a file has a
455 454 trivial ACL.
456 455
457 456 Removing all ACLs from a file
458 457 int acl_strip(const char *path, uid_t uid, gid_t gid, mode_t mode);
459 458
460 459
461 460
462 461 The acl_strip() function removes all ACLs from a file and replaces them
463 462 with a trivial ACL based off of the passed in argument mode. After
464 463 replacing the ACL the owner and group of the file are set to the values
465 464 specified in the uid and gid parameters.
466 465
467 466 Converting ACLs to/from external representation
|
↓ open down ↓ |
10 lines elided |
↑ open up ↑ |
468 467 int acl_fromtext(const char *path, acl_t **aclp);
469 468 char *acl_totext(acl_t *aclp, int flags);
470 469
471 470
472 471
473 472 The acl_totext() function converts an internal ACL representation
474 473 pointed to by aclp into an external representation. See DESCRIPTION for
475 474 details about external representation.
476 475
477 476
478 - The acl_fromtext() functions converts and external representation into
479 - an internal representation. See DESCRIPTION for details about external
477 + The acl_fromtext() function converts an external representation into an
478 + internal representation. See DESCRIPTION for details about external
480 479 representation.
481 480
482 481 EXAMPLES
483 482 The following examples demonstrate how the API can be used to perform
484 483 basic operations on ACLs.
485 484
486 485 Example 1 Retrieving and Setting an ACL
487 486
488 487
489 488 Use the following to retrieve an ACL and set it on another file:
490 489
491 490
492 491 error = acl_get("file", ACL_NO_TRIVIAL, &aclp);
493 492
494 493 if (error == 0 && aclp != NULL) {
495 494 error = acl_set("file2", aclp);
496 495 acl_free(aclp);
497 496 }
498 497 ...
499 498
500 499
501 500 Example 2 Retrieving and Setting Any ACLs
502 501
503 502
504 503 Use the following to retrieve any ACL, including trivial ACLs, and set
505 504 it on another file:
506 505
507 506
508 507 error = acl_get("file3", 0, &aclp);
509 508 if (error == 0) {
510 509 error = acl_set("file4", aclp);
511 510 acl_free(aclp);
512 511 }
513 512 ...
514 513
515 514
516 515 Example 3 Determining if a File has a Trivial ACL
517 516
518 517
519 518 Use the following to determine if a file has a trivial ACL:
520 519
521 520
522 521 char *file = "file5";
523 522 istrivial = acl_trivial(file);
524 523
525 524 if (istrivial == 0)
526 525 printf("file %s has a trivial ACL\n", file);
527 526 else
528 527 printf("file %s has a NON-trivial ACL\n", file);
529 528 ...
530 529
531 530
532 531 Example 4 Removing all ACLs from a File
533 532
534 533
535 534 Use the following to remove all ACLs from a file, and set a new mode,
536 535 owner, and group:
537 536
538 537
539 538 error = acl_strip("file", 10, 100, 0644);
540 539 ...
|
↓ open down ↓ |
51 lines elided |
↑ open up ↑ |
541 540
542 541
543 542 SEE ALSO
544 543 chgrp(1), chmod(1), chown(1), cp(1), cpio(1), find(1), ls(1), mv(1),
545 544 tar(1), setfacl(1), chmod(2), acl(2), stat(2), acl_get(3SEC),
546 545 aclsort(3SEC), acl_fromtext(3SEC), acl_free(3SEC), acl_strip(3SEC),
547 546 acl_trivial(3SEC)
548 547
549 548
550 549
551 - November 24, 2014 ACL(5)
550 + February 8, 2020 ACL(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX