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 only
  48 .Sq Fl ,
  49 the file names are taken from the standard input.
  50 .Pp
  51 The following options are available:
  52 .Bl -tag -width indent
  53 .It Fl b
  54 Remove all ACL entries except for the three required entries.
  55 If the ACL contains a
  56 .Dq Li mask
  57 entry, the permissions of the
  58 .Dq Li group
  59 entry in the resulting ACL will be set to the permission
  60 associated with both the
  61 .Dq Li group
  62 and
  63 .Dq Li mask
  64 entries of the current ACL.
  65 .It Fl d
  66 The operations apply to the default ACL entries instead of
  67 access ACL entries.
  68 Currently only directories may have
  69 default ACL's.
  70 .It Fl h
  71 If the target of the operation is a symbolic link, perform the operation
  72 on the symbolic link itself, rather than following the link.
  73 .It Fl k
  74 Delete any default ACL entries on the specified files.
  75 It
  76 is not considered an error if the specified files do not have
  77 any default ACL entries.
  78 An error will be reported if any of
  79 the specified files cannot have a default entry (i.e.\&
  80 non-directories).
  81 .It Fl m Ar entries
  82 Modify the ACL entries on the specified files by adding new
  83 entries and modifying existing ACL entries with the ACL entries
  84 specified in
  85 .Ar entries .
  86 .It Fl M Ar file
  87 Modify the ACL entries on the specified files by adding new
  88 ACL entries and modifying existing ACL entries with the ACL
  89 entries specified in the file
  90 .Ar file .
  91 If
  92 .Ar file
  93 is
  94 .Fl ,
  95 the input is taken from stdin.
  96 .It Fl n
  97 Do not recalculate the permissions associated with the ACL
  98 mask entry.
  99 .It Fl x Ar entries
 100 Remove the ACL entries specified in
 101 .Ar entries
 102 from the access or default ACL of the specified files.
 103 .It Fl X Ar file
 104 Remove the ACL entries specified in the file
 105 .Ar file
 106 from the access or default ACL of the specified files.
 107 .El
 108 .Pp
 109 The above options are evaluated in the order specified
 110 on the command-line.
 111 .Sh ACL ENTRIES
 112 An ACL entry contains three colon-separated fields:
 113 an ACL tag, an ACL qualifier, and discretionary access
 114 permissions:
 115 .Bl -tag -width indent
 116 .It Ar "ACL tag"
 117 The ACL tag specifies the ACL entry type and consists of
 118 one of the following:
 119 .Dq Li user
 120 or
 121 .Ql u
 122 specifying the access
 123 granted to the owner of the file or a specified user;
 124 .Dq Li group
 125 or
 126 .Ql g
 127 specifying the access granted to the file owning group
 128 or a specified group;
 129 .Dq Li other
 130 or
 131 .Ql o
 132 specifying the access
 133 granted to any process that does not match any user or group
 134 ACL entry;
 135 .Dq Li mask
 136 or
 137 .Ql m
 138 specifying the maximum access
 139 granted to any ACL entry except the
 140 .Dq Li user
 141 ACL entry for the file owner and the
 142 .Dq Li other
 143 ACL entry.
 144 .It Ar "ACL qualifier"
 145 The ACL qualifier field describes the user or group associated with
 146 the ACL entry.
 147 It may consist of one of the following: uid or
 148 user name, gid or group name, or empty.
 149 For
 150 .Dq Li user
 151 ACL entries, an empty field specifies access granted to the
 152 file owner.
 153 For
 154 .Dq Li group
 155 ACL entries, an empty field specifies access granted to the
 156 file owning group.
 157 .Dq Li mask
 158 and
 159 .Dq Li other
 160 ACL entries do not use this field.
 161 .It Ar "access permissions"
 162 The access permissions field contains up to one of each of
 163 the following:
 164 .Ql r ,
 165 .Ql w ,
 166 and
 167 .Ql x
 168 to set read, write, and
 169 execute permissions, respectively.
 170 Each of these may be excluded
 171 or replaced with a
 172 .Ql -
 173 character to indicate no access.
 174 .El
 175 .Pp
 176 A
 177 .Dq Li mask
 178 ACL entry is required on a file with any ACL entries other than
 179 the default
 180 .Dq Li user ,
 181 .Dq Li group ,
 182 and
 183 .Dq Li other
 184 ACL entries.
 185 If the
 186 .Fl n
 187 option is not specified and no
 188 .Dq Li mask
 189 ACL entry was specified, the
 190 .Nm
 191 utility
 192 will apply a
 193 .Dq Li mask
 194 ACL entry consisting of the union of the permissions associated
 195 with all
 196 .Dq Li group
 197 ACL entries in the resulting ACL.
 198 .Pp
 199 Traditional POSIX interfaces acting on file system object modes have
 200 modified semantics in the presence of POSIX.1e extended ACLs.
 201 When a mask entry is present on the access ACL of an object, the mask
 202 entry is substituted for the group bits; this occurs in programs such
 203 as
 204 .Xr stat 1
 205 or
 206 .Xr ls 1 .
 207 When the mode is modified on an object that has a mask entry, the
 208 changes applied to the group bits will actually be applied to the
 209 mask entry.
 210 These semantics provide for greater application compatibility:
 211 applications modifying the mode instead of the ACL will see
 212 conservative behavior, limiting the effective rights granted by all
 213 of the additional user and group entries; this occurs in programs
 214 such as
 215 .Xr chmod 1 .
 216 .Pp
 217 ACL entries applied from a file using the
 218 .Fl M
 219 or
 220 .Fl X
 221 options shall be of the following form: one ACL entry per line, as
 222 previously specified; whitespace is ignored; any text after a
 223 .Ql #
 224 is ignored (comments).
 225 .Pp
 226 When ACL entries are evaluated, the access check algorithm checks
 227 the ACL entries in the following order: file owner,
 228 .Dq Li user
 229 ACL entries, file owning group,
 230 .Dq Li group
 231 ACL entries, and
 232 .Dq Li other
 233 ACL entry.
 234 .Pp
 235 Multiple ACL entries specified on the command line are
 236 separated by commas.
 237 .Sh EXIT STATUS
 238 .Ex -std
 239 .Sh EXAMPLES
 240 .Dl setfacl -m u::rwx,g:mail:rw file
 241 .Pp
 242 Sets read, write, and execute permissions for the
 243 .Pa file
 244 owner's ACL entry and read and write permissions for group mail on
 245 .Pa file .
 246 .Pp
 247 .Dl setfacl -M file1 file2
 248 .Pp
 249 Sets/updates the ACL entries contained in
 250 .Pa file1
 251 on
 252 .Pa file2 .
 253 .Pp
 254 .Dl setfacl -x g:mail:rw file
 255 .Pp
 256 Remove the group mail ACL entry containing read/write permissions
 257 from
 258 .Pa file .
 259 .Pp
 260 .Dl setfacl -bn file
 261 .Pp
 262 Remove all
 263 .Dq Li access
 264 ACL entries except for the three required from
 265 .Pa file .
 266 .Pp
 267 .Dl getfacl file1 | setfacl -b -n -M - file2
 268 .Pp
 269 Copy ACL entries from
 270 .Pa file1
 271 to
 272 .Pa file2 .
 273 .Sh SEE ALSO
 274 .Xr getfacl 1 ,
 275 .Xr acl 3 ,
 276 .Xr getextattr 8 ,
 277 .Xr setextattr 8 ,
 278 .Xr acl 9 ,
 279 .Xr extattr 9
 280 .Sh STANDARDS
 281 The
 282 .Nm
 283 utility is expected to be
 284 .Tn IEEE
 285 Std 1003.2c compliant.
 286 .Sh HISTORY
 287 Extended Attribute and Access Control List support was developed
 288 as part of the
 289 .Tn TrustedBSD
 290 Project and introduced in
 291 .Fx 5.0 .
 292 .Sh AUTHORS
 293 The
 294 .Nm
 295 utility was written by
 296 .An Chris D. Faulhaber Aq jedgar@fxp.org .