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