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