doc/man/apply-default-acl.1

   1 .TH apply-default-acl 1
   2
   3 .SH NAME
   4 apply-default-acl \- Apply default POSIX ACLs to files and directories.
   5
   6 .SH SYNOPSIS
   7
   8 \fBapply-default-acl\fR [\fB-r\fR] \fIpath\fR [\fIpath2 ...\fR]
   9
  10 .SH DESCRIPTION
  11
  12 .P
  13 If the directory containing \fIpath\fR has a default ACL, the ACL on
  14 \fIpath\fR is replaced with that default. Neither symbolic nor hard
  15 links are followed; symbolic links are ignored in all path components
  16 to avoid a dangerous race condition.
  17 .P
  18 A heuristic is used to determine whether or not the execute bits are
  19 removed from \fIpath\fR. If \fIpath\fR is a directory or if some user
  20 or group has \fBeffective\fR execute permissions on \fIpath\fR, then
  21 the execute bits will be left alone. Otherwise, they will be
  22 removed. In effect we pretend that the \fBx\fR permission acts like
  23 the \fBX\fR (note the case difference) permission of \fBsetfacl\fR.
  24
  25 .SH OPTIONS
  26 .IP \fB\-\-recursive\fR,\ \fB\-r\fR
  27 Apply default ACLs recursively. This works top-down, so if directory
  28 \fBfoo\fR is in another directory \fBbar\fR which has a default ACL,
  29 then \fBbar\fR's default ACL will be applied to \fBfoo\fR before the
  30 contents of \fBfoo\fR are processed.
  31
  32 .SH ALGORITHM
  33 .IP "I. Argument validation" 0.4i
  34 .RS
  35 .IP "a. If any part of the target path contains a symlink" 0.4i
  36 Return failure
  37 .IP "b. If there is no default ACL to apply"
  38 Return success
  39 .IP "c. If the target is not a (non-hardlink) regular file or directory"
  40 Return failure
  41 .RE
  42 .IP "II. ACL application"
  43 .RS
  44 .IP "a. If the target is a directory" 0.4i
  45 Set the target's default ACL equal to its parent's default ACL
  46 .IP "b. Set the target's access ACL equal to its parent's default ACL"
  47 .IP "c. If the target is a directory"
  48 Return success
  49 .IP "d. If the target was executable by anyone"
  50 Return success
  51 .IP "e. Unset the user/group/other/mask execute bits"
  52 .IP "f. Return success"
  53 .RE
  54 .P
  55 The action of apply-default ACL largely mimics what the kernel would
  56 do if you ran \fBmkdir\fR or \fBtouch\fR to create a new file. The one
  57 point of disagreement is on how to mask group-execute permissions for
  58 files. The kernel will let the \(dqmask\(dq bits prevent group-execute,
  59 whereas apply-default-acl will explicitly remove the group-execute bits.
  60 For example,
  61
  62 .nf
  63 .I $ mkdir herp
  64 .I $ setfacl --default --modify user:mjo:rw herp
  65 .I $ touch herp/derp
  66 .I $ getfacl --omit-header herp/derp
  67 user::rw-
  68 user:mjo:rw-
  69 group::r-x                      #effective:r--
  70 mask::rw-
  71 other::r--
  72 .fi
  73
  74 In the same situation, apply-default-acl will mask the group \fBx\fR bit:
  75
  76 .nf
  77 .I $ apply-default-acl herp/derp
  78 .I $ getfacl --omit-header herp/derp
  79 user::rw-
  80 user:mjo:rw-
  81 group::r--
  82 mask::rw-
  83 other::r--
  84 .fi
  85
  86 The author is of the opinion that the latter is more sensible, if not
  87 simply more consistent.
  88
  89 .SH EXIT CODE
  90 .P
  91 When given a single path, the following codes correspond directly to
  92 the action of the program on that path:
  93 .IP \fB0\ (EXIT_SUCCESS)\fR
  94 Success
  95 .IP \fB1\ (EXIT_FAILURE)\fR
  96 Failure due to a symlink, hardlink, or invalid/inaccessible path
  97 .IP \fB2\fP
  98 Other unexpected library error
  99 .P
 100 When called on multiple paths, the results from all paths are
 101 collected and the \(dqworst\(dq result is returned. For example, if
 102 one path succeeds and another fails, the overall result will be
 103 failure. If one succeeds, one fails, and one causes an error, then the
 104 overall result will be an error; and so on.
 105 .P
 106 When the \fB\-\-recursive\fR flag is used, the exit code is computed
 107 as if all affected paths were passed, depth-first, on the command-line.