bin/setfacl/setfacl.1

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