bin/setfacl/setfacl.1

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