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