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