bin/setfacl/setfacl.1

   1 .\"-
   2 .\" Copyright (c) 2001 Chris D. Faulhaber
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR THE VOICES IN HIS HEAD BE
  18 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  19 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  20 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  21 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  22 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  23 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  24 .\" POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 7, 2001
  29 .Dt SETFACL 1
  30 .Os
  31 .Sh NAME
  32 .Nm setfacl
  33 .Nd set ACL information
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl bdhkn
  37 .Op Fl m Ar entries
  38 .Op Fl M Ar file
  39 .Op Fl x Ar entries
  40 .Op Fl X Ar file
  41 .Op Ar
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 utility sets discretionary access control information on
  46 the specified file(s).
  47 If no files are specified, or the list consists of the
  48 only "-", the file names are taken from the standard input.
  49 .Pp
  50 The following options are available:
  51 .Bl -tag -width indent
  52 .It Fl b
  53 Remove all ACL entries except for the three required entries.
  54 If the ACL contains a
  55 .Dq Li mask
  56 entry, the permissions of the
  57 .Dq Li group
  58 entry in the resulting ACL will be set to the permission
  59 associated with both the
  60 .Dq Li group
  61 and
  62 .Dq Li mask
  63 entries of the current ACL.
  64 .It Fl d
  65 The operations apply to the default ACL entries instead of
  66 access ACL entries.
  67 Currently only directories may have
  68 default ACL's.
  69 .It Fl h
  70 If the target of the operation is a symbolic link, perform the operation
  71 on the symbolic link itself, rather than following the link.
  72 .It Fl k
  73 Delete any default ACL entries on the specified files.
  74 It
  75 is not considered an error if the specified files do not have
  76 any default ACL entries.
  77 An error will be reported if any of
  78 the specified files cannot have a default entry (i.e.\&
  79 non-directories).
  80 .It Fl m Ar entries
  81 Modify the ACL entries on the specified files by adding new
  82 entries and modifying existing ACL entries with the ACL entries
  83 specified in
  84 .Ar entries .
  85 .It Fl M Ar file
  86 Modify the ACL entries on the specified files by adding new
  87 ACL entries and modifying existing ACL entries with the ACL
  88 entries specified in the file
  89 .Ar file .
  90 If
  91 .Ar file
  92 is
  93 .Fl ,
  94 the input is taken from stdin.
  95 .It Fl n
  96 Do not recalculate the permissions associated with the ACL
  97 mask entry.
  98 .It Fl x Ar entries
  99 Remove the ACL entries specified in
 100 .Ar entries
 101 from the access or default ACL of the specified files.
 102 .It Fl X Ar file
 103 Remove the ACL entries specified in the file
 104 .Ar file
 105 from the access or default ACL of the specified files.
 106 .El
 107 .Pp
 108 The above options are evaluated in the order specified
 109 on the command-line.
 110 .Sh ACL ENTRIES
 111 An ACL entry contains three colon-separated fields:
 112 an ACL tag, an ACL qualifier, and discretionary access
 113 permissions:
 114 .Bl -tag -width indent
 115 .It Ar "ACL tag"
 116 The ACL tag specifies the ACL entry type and consists of
 117 one of the following:
 118 .Dq Li user
 119 or
 120 .Ql u
 121 specifying the access
 122 granted to the owner of the file or a specified user;
 123 .Dq Li group
 124 or
 125 .Ql g
 126 specifying the access granted to the file owning group
 127 or a specified group;
 128 .Dq Li other
 129 or
 130 .Ql o
 131 specifying the access
 132 granted to any process that does not match any user or group
 133 ACL entry;
 134 .Dq Li mask
 135 or
 136 .Ql m
 137 specifying the maximum access
 138 granted to any ACL entry except the
 139 .Dq Li user
 140 ACL entry for the file owner and the
 141 .Dq Li other
 142 ACL entry.
 143 .It Ar "ACL qualifier"
 144 The ACL qualifier field describes the user or group associated with
 145 the ACL entry.
 146 It may consist of one of the following: uid or
 147 user name, gid or group name, or empty.
 148 For
 149 .Dq Li user
 150 ACL entries, an empty field specifies access granted to the
 151 file owner.
 152 For
 153 .Dq Li group
 154 ACL entries, an empty field specifies access granted to the
 155 file owning group.
 156 .Dq Li mask
 157 and
 158 .Dq Li other
 159 ACL entries do not use this field.
 160 .It Ar "access permissions"
 161 The access permissions field contains up to one of each of
 162 the following:
 163 .Ql r ,
 164 .Ql w ,
 165 and
 166 .Ql x
 167 to set read, write, and
 168 execute permissions, respectively.
 169 Each of these may be excluded
 170 or replaced with a
 171 .Ql -
 172 character to indicate no access.
 173 .El
 174 .Pp
 175 A
 176 .Dq Li mask
 177 ACL entry is required on a file with any ACL entries other than
 178 the default
 179 .Dq Li user ,
 180 .Dq Li group ,
 181 and
 182 .Dq Li other
 183 ACL entries.
 184 If the
 185 .Fl n
 186 option is not specified and no
 187 .Dq Li mask
 188 ACL entry was specified, the
 189 .Nm
 190 utility
 191 will apply a
 192 .Dq Li mask
 193 ACL entry consisting of the union of the permissions associated
 194 with all
 195 .Dq Li group
 196 ACL entries in the resulting ACL.
 197 .Pp
 198 Traditional POSIX interfaces acting on file system object modes have
 199 modified semantics in the presence of POSIX.1e extended ACLs.
 200 When a mask entry is present on the access ACL of an object, the mask
 201 entry is substituted for the group bits; this occurs in programs such
 202 as
 203 .Xr stat 1
 204 or
 205 .Xr ls 1 .
 206 When the mode is modified on an object that has a mask entry, the
 207 changes applied to the group bits will actually be applied to the
 208 mask entry.
 209 These semantics provide for greater application compatibility:
 210 applications modifying the mode instead of the ACL will see
 211 conservative behavior, limiting the effective rights granted by all
 212 of the additional user and group entries; this occurs in programs
 213 such as
 214 .Xr chmod 1 .
 215 .Pp
 216 ACL entries applied from a file using the
 217 .Fl M
 218 or
 219 .Fl X
 220 options shall be of the following form: one ACL entry per line, as
 221 previously specified; whitespace is ignored; any text after a
 222 .Ql #
 223 is ignored (comments).
 224 .Pp
 225 When ACL entries are evaluated, the access check algorithm checks
 226 the ACL entries in the following order: file owner,
 227 .Dq Li user
 228 ACL entries, file owning group,
 229 .Dq Li group
 230 ACL entries, and
 231 .Dq Li other
 232 ACL entry.
 233 .Pp
 234 Multiple ACL entries specified on the command line are
 235 separated by commas.
 236 .Sh EXIT STATUS
 237 .Ex -std
 238 .Sh EXAMPLES
 239 .Dl setfacl -m u::rwx,g:mail:rw file
 240 .Pp
 241 Sets read, write, and execute permissions for the
 242 .Pa file
 243 owner's ACL entry and read and write permissions for group mail on
 244 .Pa file .
 245 .Pp
 246 .Dl setfacl -M file1 file2
 247 .Pp
 248 Sets/updates the ACL entries contained in
 249 .Pa file1
 250 on
 251 .Pa file2 .
 252 .Pp
 253 .Dl setfacl -x g:mail:rw file
 254 .Pp
 255 Remove the group mail ACL entry containing read/write permissions
 256 from
 257 .Pa file.
 258 .Pp
 259 .Dl setfacl -bn file
 260 .Pp
 261 Remove all
 262 .Dq Li access
 263 ACL entries except for the three required from
 264 .Pa file .
 265 .Pp
 266 .Dl getfacl file1 | setfacl -b -n -M - file2
 267 .Pp
 268 Copy ACL entries from
 269 .Pa file1
 270 to
 271 .Pa file2 .
 272 .Sh SEE ALSO
 273 .Xr getfacl 1 ,
 274 .Xr acl 3 ,
 275 .Xr getextattr 8 ,
 276 .Xr setextattr 8 ,
 277 .Xr acl 9 ,
 278 .Xr extattr 9
 279 .Sh STANDARDS
 280 The
 281 .Nm
 282 utility is expected to be
 283 .Tn IEEE
 284 Std 1003.2c compliant.
 285 .Sh HISTORY
 286 Extended Attribute and Access Control List support was developed
 287 as part of the
 288 .Tn TrustedBSD
 289 Project and introduced in
 290 .Fx 5.0 .
 291 .Sh AUTHORS
 292 The
 293 .Nm
 294 utility was written by
 295 .An Chris D. Faulhaber Aq jedgar@fxp.org .