doc/man/apply-default-acl.1

   1 .TH apply-default-acl 1
   2
   3 .SH NAME
   4 apply-default-acl \- Apply default POSIX ACLs to files and directories.
   5
   6 .SH SYNOPSIS
   7
   8 \fBapply-default-acl\fR [\fB-r\fR] \fIpath\fR [\fIpath2 ...\fR]
   9
  10 .SH DESCRIPTION
  11
  12 .P
  13 If the directory containing \fIpath\fR has a default ACL, the ACL on
  14 \fIpath\fR is replaced with that default. Neither symbolic nor hard
  15 links are followed; symbolic links are ignored in all \fIpath\fR
  16 components to avoid a dangerous race condition.
  17 .P
  18 A heuristic is used to determine whether or not the execute bits are
  19 removed from \fIpath\fR. If \fIpath\fR is a directory or if some user
  20 or group can execute \fIpath\fR, then the execute bits are left alone.
  21 Otherwise, they are removed. In effect, we pretend that the \fBx\fR
  22 permission in the parent's default ACL acts like the \fBX\fR (note the
  23 case difference) permission used by \fBsetfacl\fR.
  24
  25 .SH RATIONALE
  26
  27 .P
  28 Why would you need this? When you change the default ACL on a
  29 directory, it doesn't affect any of the files in that directory. So,
  30 if change the default ACL on a directory to allow group-read access,
  31 then you still have to manually allow group-read access on every file
  32 in that directory. That wouldn't be so bad, except that you need to do
  33 it recursively, and the \fBsetfacl\fR command is different for files
  34 and directories. Instead, once you've set the default ACL, you can use
  35 apply-default-acl to \(dqreset\(dq the permissions on everything in
  36 the directory. The differences between files and directories are
  37 handled for you.
  38 .P
  39 Another reason is that several common utilities like \fBcp\fR and
  40 \fBtar\fR will call \fBchmod\fR on the files that they create without
  41 regard for your default ACLs. When those utilities try to preserve
  42 group permissions, they are actually affecting your ACL mask, and this
  43 can prevent your default permissions from taking effect. For example,
  44 if you \fBcp\fR a file that is not group-writable into a directory
  45 that has a default ACL, the effective write permissions will all be
  46 masked when \fBcp\fR clears the group-write (that is, the mask-write)
  47 bit. Calling apply-default-acl on the files created by these utilities
  48 fixes the permissions.
  49
  50 .SH OPTIONS
  51 .IP \fB\-\-recursive\fR,\ \fB\-r\fR
  52 Apply default ACLs recursively. This works top-down, so if directory
  53 \fBfoo\fR is in another directory \fBbar\fR which has a default ACL,
  54 then \fBbar\fR's default ACL will be applied to \fBfoo\fR before the
  55 contents of \fBfoo\fR are processed.
  56
  57 .SH ALGORITHM
  58 .IP "I. Argument validation" 0.4i
  59 .RS
  60 .IP "a. If any part of the target path contains a symlink" 0.4i
  61 Return failure
  62 .IP "b. If there is no default ACL to apply"
  63 Return success
  64 .IP "c. If the target is not a (non-hardlink) regular file or directory"
  65 Return failure
  66 .RE
  67 .IP "II. ACL application"
  68 .RS
  69 .IP "a. If the target is a directory" 0.4i
  70 Set the target's default ACL equal to its parent's default ACL
  71 .IP "b. Set the target's access ACL equal to its parent's default ACL"
  72 .IP "c. If the target is a directory"
  73 Return success
  74 .IP "d. If the target was executable by anyone"
  75 Return success
  76 .IP "e. Unset the user/group/other/mask execute bits"
  77 .IP "f. Return success"
  78 .RE
  79 .P
  80 The action of apply-default ACL largely mimics what the kernel would
  81 do if you ran \fBmkdir\fR or \fBtouch\fR to create a new file. The one
  82 point of disagreement is on how to mask group-execute permissions for
  83 files. The kernel will let the \(dqmask\(dq bits prevent group-execute,
  84 whereas apply-default-acl will explicitly remove the group-execute bits.
  85 For example,
  86
  87 .nf
  88 .I $ mkdir herp
  89 .I $ setfacl --default --modify user:mjo:rw herp
  90 .I $ touch herp/derp
  91 .I $ getfacl --omit-header herp/derp
  92 user::rw-
  93 user:mjo:rw-
  94 group::r-x                      #effective:r--
  95 mask::rw-
  96 other::r--
  97 .fi
  98
  99 In the same situation, apply-default-acl will mask the group \fBx\fR bit:
 100
 101 .nf
 102 .I $ apply-default-acl herp/derp
 103 .I $ getfacl --omit-header herp/derp
 104 user::rw-
 105 user:mjo:rw-
 106 group::r--
 107 mask::rw-
 108 other::r--
 109 .fi
 110
 111 The author is of the opinion that the latter is more sensible, if not
 112 simply more consistent.
 113
 114 .SH EXIT CODE
 115 .P
 116 When given a single path, the following codes correspond directly to
 117 the action of the program on that path:
 118 .IP \fB0\ (EXIT_SUCCESS)\fR
 119 Success
 120 .IP \fB1\ (EXIT_FAILURE)\fR
 121 Failure due to a symlink, hardlink, or invalid/inaccessible path
 122 .IP \fB2\fP
 123 Other unexpected library error
 124 .P
 125 When called on multiple paths, the results from all paths are
 126 collected and the \(dqworst\(dq result is returned. For example, if
 127 one path succeeds and another fails, the overall result will be
 128 failure. If one succeeds, one fails, and one causes an error, then the
 129 overall result will be an error; and so on.
 130 .P
 131 When the \fB\-\-recursive\fR flag is used, the exit code is computed
 132 as if all affected paths were passed, depth-first, on the command-line.