X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=doc%2Fman%2Fapply-default-acl.1;h=2c30862f921b66659692c726ae6b3743f5d4642e;hb=eff465edd88f0a93afb82d3107163897851b4342;hp=87e9803c916f514f5e34020d97c8e7caf0486042;hpb=f8819ed634c7dac594755c37f3dc3bbf9d7926fe;p=apply-default-acl.git diff --git a/doc/man/apply-default-acl.1 b/doc/man/apply-default-acl.1 index 87e9803..2c30862 100644 --- a/doc/man/apply-default-acl.1 +++ b/doc/man/apply-default-acl.1 @@ -5,24 +5,47 @@ apply-default-acl \- Apply default POSIX ACLs to files and directories. .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 @@ -30,10 +53,63 @@ Apply default ACLs recursively. This works top-down, so if directory \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