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