configure.ac: place build artifacts in the "build-aux" directory.

[apply-default-acl.git] / doc / man / apply-default-acl.1

diff --git a/doc/man/apply-default-acl.1 b/doc/man/apply-default-acl.1
index e6a67995dc23e929b1ae2269075bb70e53453314..2c30862f921b66659692c726ae6b3743f5d4642e 100644 (file)
--- 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
 
 
 .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
 
 .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
 .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
 .P

-This behavior can be modified with the \fB--no-exec-mask\fR flag.
+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
 
 .SH OPTIONS
 .IP \fB\-\-recursive\fR,\ \fB\-r\fR


@@ -30,17 +53,13 @@ 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.
 \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
 
 .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"
+.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
 Return success
 .IP "c. If the target is not a (non-hardlink) regular file or directory"
 Return failure


@@ -54,14 +73,12 @@ Set the target's default ACL equal to its parent's default ACL
 Return success
 .IP "d. If the target was executable by anyone"
 Return success
 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"
+.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
 .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
+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.
 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.