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