From d6a67a1edd2041ed28d6e31df2a5bbb5c7408318 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Tue, 27 Mar 2018 20:23:16 -0400
Subject: [PATCH] doc: document the apply-default-acl algorithm.

It's nice to have a high-level overview of what the ACL application
actually does, so I have added one to the man page in a new section
titled "ALGORITHM". The manual now also explains how apply-default-acl
differs from the kernel when, for example, you "touch" a file in a
directory with a default ACL.
---
 doc/man/apply-default-acl.1 | 59 +++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/doc/man/apply-default-acl.1 b/doc/man/apply-default-acl.1
index 87e9803..e6a6799 100644
--- a/doc/man/apply-default-acl.1
+++ b/doc/man/apply-default-acl.1
@@ -35,6 +35,65 @@ 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's 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. If \fB--no-exec-mask\fR was given"
+Return success
+.IP "f. Unset the user/group/other/mask execute bits"
+.IP "g. Return success"
+.RE
+.P
+The action of apply-default ACL largely mimics what the kernel would
+do if you ran \fImkdir\fR or \fItouch\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
 When given a single path, the following codes correspond directly to
-- 
2.43.2