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