From eff465edd88f0a93afb82d3107163897851b4342 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Wed, 28 Mar 2018 10:35:00 -0400 Subject: [PATCH] doc: add a RATIONALE section to the man page. --- doc/man/apply-default-acl.1 | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/doc/man/apply-default-acl.1 b/doc/man/apply-default-acl.1 index 42233f1..2c30862 100644 --- a/doc/man/apply-default-acl.1 +++ b/doc/man/apply-default-acl.1 @@ -12,15 +12,40 @@ apply-default-acl \- Apply default POSIX ACLs to files and directories. .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 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 has \fBeffective\fR execute permissions on \fIpath\fR, then -the execute bits will be left alone. Otherwise, they will be -removed. In effect we pretend that the \fBx\fR permission acts like -the \fBX\fR (note the case difference) permission of \fBsetfacl\fR. +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 +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 -- 2.43.2