share/man/man9/acl.9

   1 .\"-
   2 .\" Copyright (c) 1999-2001 Robert N. M. Watson
   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 CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 18, 2009
  29 .Dt ACL 9
  30 .Os
  31 .Sh NAME
  32 .Nm acl
  33 .Nd virtual file system access control lists
  34 .Sh SYNOPSIS
  35 .In sys/param.h
  36 .In sys/vnode.h
  37 .In sys/acl.h
  38 .Pp
  39 In the kernel configuration file:
  40 .Cd "options UFS_ACL"
  41 .Sh DESCRIPTION
  42 Access control lists, or ACLs,
  43 allow fine-grained specification of rights
  44 for vnodes representing files and directories.
  45 However, as there are a plethora of file systems with differing ACL semantics,
  46 the vnode interface is aware only of the syntax of ACLs,
  47 relying on the underlying file system to implement the details.
  48 Depending on the underlying file system, each file or directory
  49 may have zero or more ACLs associated with it, named using the
  50 .Fa type
  51 field of the appropriate vnode ACL calls:
  52 .Xr VOP_ACLCHECK 9 ,
  53 .Xr VOP_GETACL 9 ,
  54 and
  55 .Xr VOP_SETACL 9 .
  56 .Pp
  57 Currently, each ACL is represented in-kernel by a fixed-size
  58 .Vt acl
  59 structure, defined as follows:
  60 .Bd -literal -offset indent
  61 struct acl {
  62         unsigned int            acl_maxcnt;
  63         unsigned int            acl_cnt;
  64         int                     acl_spare[4];
  65         struct acl_entry        acl_entry[ACL_MAX_ENTRIES];
  66 };
  67 .Ed
  68 .Pp
  69 An ACL is constructed from a fixed size array of ACL entries,
  70 each of which consists of a set of permissions, principal namespace,
  71 and principal identifier.
  72 In this implementation, the
  73 .Vt acl_maxcnt
  74 field is always set to
  75 .Dv ACL_MAX_ENTRIES .
  76 .Pp
  77 Each individual ACL entry is of the type
  78 .Vt acl_entry_t ,
  79 which is a structure with the following members:
  80 .Bl -tag -width 2n
  81 .It Vt acl_tag_t Va ae_tag
  82 The following is a list of definitions of ACL types
  83 to be set in
  84 .Va ae_tag :
  85 .Pp
  86 .Bl -tag -width ".Dv ACL_UNDEFINED_FIELD" -offset indent -compact
  87 .It Dv ACL_UNDEFINED_FIELD
  88 Undefined ACL type.
  89 .It Dv ACL_USER_OBJ
  90 Discretionary access rights for processes whose effective user ID
  91 matches the user ID of the file's owner.
  92 .It Dv ACL_USER
  93 Discretionary access rights for processes whose effective user ID
  94 matches the ACL entry qualifier.
  95 .It Dv ACL_GROUP_OBJ
  96 Discretionary access rights for processes whose effective group ID
  97 or any supplemental groups
  98 match the group ID of the file's owner.
  99 .It Dv ACL_GROUP
 100 Discretionary access rights for processes whose effective group ID
 101 or any supplemental groups
 102 match the ACL entry qualifier.
 103 .It Dv ACL_MASK
 104 The maximum discretionary access rights that can be granted
 105 to a process in the file group class.
 106 This is only valid for POSIX.1e ACLs.
 107 .It Dv ACL_OTHER
 108 Discretionary access rights for processes not covered by any other ACL
 109 entry.
 110 This is only valid for POSIX.1e ACLs.
 111 .It Dv ACL_OTHER_OBJ
 112 Same as
 113 .Dv ACL_OTHER .
 114 .It Dv ACL_EVERYONE
 115 Discretionary access rights for all users.
 116 This is only valid for NFSv4 ACLs.
 117 .El
 118 .Pp
 119 Each POSIX.1e ACL must contain exactly one
 120 .Dv ACL_USER_OBJ ,
 121 one
 122 .Dv ACL_GROUP_OBJ ,
 123 and one
 124 .Dv ACL_OTHER .
 125 If any of
 126 .Dv ACL_USER ,
 127 .Dv ACL_GROUP ,
 128 or
 129 .Dv ACL_OTHER
 130 are present, then exactly one
 131 .Dv ACL_MASK
 132 entry should be present.
 133 .It Vt uid_t Va ae_id
 134 The ID of user for whom this ACL describes access permissions.
 135 For entries other than
 136 .Dv ACL_USER
 137 and
 138 .Dv ACL_GROUP ,
 139 this field should be set to
 140 .Dv ACL_UNDEFINED_ID .
 141 .It Vt acl_perm_t Va ae_perm
 142 This field defines what kind of access the process matching this ACL has
 143 for accessing the associated file.
 144 For POSIX.1e ACLs, the following are valid:
 145 .Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS"
 146 .It Dv ACL_EXECUTE
 147 The process may execute the associated file.
 148 .It Dv ACL_WRITE
 149 The process may write to the associated file.
 150 .It Dv ACL_READ
 151 The process may read from the associated file.
 152 .It Dv ACL_PERM_NONE
 153 The process has no read, write or execute permissions
 154 to the associated file.
 155 .El
 156 .Pp
 157 For NFSv4 ACLs, the following are valid:
 158 .Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS"
 159 .It Dv ACL_READ_DATA
 160 The process may read from the associated file.
 161 .It Dv ACL_LIST_DIRECTORY
 162 Same as
 163 .Dv ACL_READ_DATA .
 164 .It Dv ACL_WRITE_DATA
 165 The process may write to the associated file.
 166 .It Dv ACL_ADD_FILE
 167 Same as
 168 .Dv ACL_ACL_WRITE_DATA .
 169 .It Dv ACL_APPEND_DATA
 170 .It Dv ACL_ADD_SUBDIRECTORY
 171 Same as
 172 .Dv ACL_APPEND_DATA .
 173 .It Dv ACL_READ_NAMED_ATTRS
 174 Ignored.
 175 .It Dv ACL_WRITE_NAMED_ATTRS
 176 Ignored.
 177 .It Dv ACL_EXECUTE
 178 The process may execute the associated file.
 179 .It Dv ACL_DELETE_CHILD
 180 .It Dv ACL_READ_ATTRIBUTES
 181 .It Dv ACL_WRITE_ATTRIBUTES
 182 .It Dv ACL_DELETE
 183 .It Dv ACL_READ_ACL
 184 .It Dv ACL_WRITE_ACL
 185 .It Dv ACL_WRITE_OWNER
 186 .It Dv ACL_SYNCHRONIZE
 187 Ignored.
 188 .El
 189 .It Vt acl_entry_type_t Va ae_entry_type
 190 This field defines the type of NFSv4 ACL entry.
 191 It is not used with POSIX.1e ACLs.
 192 The following values are valid:
 193 .Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS"
 194 .It Dv ACL_ENTRY_TYPE_ALLOW
 195 .It Dv ACL_ENTRY_TYPE_DENY
 196 .El
 197 .It Vt acl_flag_t Va ae_flags
 198 This field defines the inheritance flags of NFSv4 ACL entry.
 199 It is not used with POSIX.1e ACLs.
 200 The following values are valid:
 201 .Bl -tag -width ".Dv ACL_ENTRY_DIRECTORY_INHERIT"
 202 .It Dv ACL_ENTRY_FILE_INHERIT
 203 .It Dv ACL_ENTRY_DIRECTORY_INHERIT
 204 .It Dv ACL_ENTRY_NO_PROPAGATE_INHERIT
 205 .It Dv ACL_ENTRY_INHERIT_ONLY
 206 .El
 207 .El
 208 .Sh SEE ALSO
 209 .Xr acl 3 ,
 210 .Xr vaccess_acl_nfs4 9 ,
 211 .Xr vaccess_acl_posix1e 9 ,
 212 .Xr VFS 9 ,
 213 .Xr vaccess 9 ,
 214 .Xr VOP_ACLCHECK 9 ,
 215 .Xr VOP_GETACL 9 ,
 216 .Xr VOP_SETACL 9
 217 .Sh AUTHORS
 218 This manual page was written by
 219 .An Robert Watson .