.SH SYNOPSIS
-\fBapply-default-acl\fR [\fB-rx\fR] \fIpath\fR [\fIpath2 ...\fR]
+\fBapply-default-acl\fR [\fB-r\fR] \fIpath\fR [\fIpath2 ...\fR]
.SH DESCRIPTION
.P
If the directory containing \fIpath\fR has a default ACL, the ACL on
\fIpath\fR is replaced with that default. Neither symbolic nor hard
-links are followed; symbolic links are ignored in all path components
-to avoid a dangerous race condition.
+links are followed; symbolic links are ignored in all \fIpath\fR
+components to avoid a dangerous race condition.
.P
-By default, a heuristic is used to determine whether or not the
-execute bit is masked on \fIpath\fR. If \fIpath\fR is not a directory,
-and no user or group has \fBeffective\fR execute permissions on
-\fIpath\fR, then the execute bit will not masked. Otherwise, it is
-left alone. In effect we pretend that the \fBx\fR permission acts like
-the \fBX\fR (note the case difference) permission of \fBsetfacl\fR.
+A heuristic is used to determine whether or not the execute bits are
+removed from \fIpath\fR. If \fIpath\fR is a directory or if some user
+or group can execute \fIpath\fR, then the execute bits are left alone.
+Otherwise, they are removed. In effect, we pretend that the \fBx\fR
+permission in the parent's default ACL acts like the \fBX\fR (note the
+case difference) permission used by \fBsetfacl\fR.
+
+.SH RATIONALE
+
+.P
+Why would you need this? When you change the default ACL on a
+directory, it doesn't affect any of the files in that directory. So,
+if change the default ACL on a directory to allow group-read access,
+then you still have to manually allow group-read access on every file
+in that directory. That wouldn't be so bad, except that you need to do
+it recursively, and the \fBsetfacl\fR command is different for files
+and directories. Instead, once you've set the default ACL, you can use
+apply-default-acl to \(dqreset\(dq the permissions on everything in
+the directory. The differences between files and directories are
+handled for you.
.P
-This behavior can be modified with the \fB--no-exec-mask\fR flag.
+Another reason is that several common utilities like \fBcp\fR and
+\fBtar\fR will call \fBchmod\fR on the files that they create without
+regard for your default ACLs. When those utilities try to preserve
+group permissions, they are actually affecting your ACL mask, and this
+can prevent your default permissions from taking effect. For example,
+if you \fBcp\fR a file that is not group-writable into a directory
+that has a default ACL, the effective write permissions will all be
+masked when \fBcp\fR clears the group-write (that is, the mask-write)
+bit. Calling apply-default-acl on the files created by these utilities
+fixes the permissions.
.SH OPTIONS
.IP \fB\-\-recursive\fR,\ \fB\-r\fR
\fBfoo\fR is in another directory \fBbar\fR which has a default ACL,
then \fBbar\fR's default ACL will be applied to \fBfoo\fR before the
contents of \fBfoo\fR are processed.
-.IP \fB\-\-no-exec-mask\fR,\ \fB\-x\fR
-Apply the default ACL literally; that is, don't use a heuristic to
-decide whether or not to mask the execute bit. This usually results in
-looser-than-necessary execute permissions.
+
+.SH ALGORITHM
+.IP "I. Argument validation" 0.4i
+.RS
+.IP "a. If any part of the target path contains a symlink" 0.4i
+Return failure
+.IP "b. If there is no default ACL to apply"
+Return success
+.IP "c. If the target is not a (non-hardlink) regular file or directory"
+Return failure
+.RE
+.IP "II. ACL application"
+.RS
+.IP "a. If the target is a directory" 0.4i
+Set the target's default ACL equal to its parent's default ACL
+.IP "b. Set the target's access ACL equal to its parent's default ACL"
+.IP "c. If the target is a directory"
+Return success
+.IP "d. If the target was executable by anyone"
+Return success
+.IP "e. Unset the user/group/other/mask execute bits"
+.IP "f. Return success"
+.RE
+.P
+The action of apply-default ACL largely mimics what the kernel would
+do if you ran \fBmkdir\fR or \fBtouch\fR to create a new file. The one
+point of disagreement is on how to mask group-execute permissions for
+files. The kernel will let the \(dqmask\(dq bits prevent group-execute,
+whereas apply-default-acl will explicitly remove the group-execute bits.
+For example,
+
+.nf
+.I $ mkdir herp
+.I $ setfacl --default --modify user:mjo:rw herp
+.I $ touch herp/derp
+.I $ getfacl --omit-header herp/derp
+user::rw-
+user:mjo:rw-
+group::r-x #effective:r--
+mask::rw-
+other::r--
+.fi
+
+In the same situation, apply-default-acl will mask the group \fBx\fR bit:
+
+.nf
+.I $ apply-default-acl herp/derp
+.I $ getfacl --omit-header herp/derp
+user::rw-
+user:mjo:rw-
+group::r--
+mask::rw-
+other::r--
+.fi
+
+The author is of the opinion that the latter is more sensible, if not
+simply more consistent.
.SH EXIT CODE
.P
one path succeeds and another fails, the overall result will be
failure. If one succeeds, one fails, and one causes an error, then the
overall result will be an error; and so on.
+.P
+When the \fB\-\-recursive\fR flag is used, the exit code is computed
+as if all affected paths were passed, depth-first, on the command-line.
projects / apply-default-acl.git / blobdiff