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 December 23, 1999
  29 .Os
  30 .Dt ACL 9
  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         int                     acl_cnt;
  63         struct acl_entry        acl_entry[ACL_MAX_ENTRIES];
  64 };
  65 .Ed
  66 .Pp
  67 An ACL is constructed from a fixed size array of ACL entries,
  68 each of which consists of a set of permissions, principal namespace,
  69 and principal identifier.
  70 .Pp
  71 Each individual ACL entry is of the type
  72 .Vt acl_entry_t ,
  73 which is a structure with the following members:
  74 .Bl -tag -width 2n
  75 .It Vt acl_tag_t Va ae_tag
  76 The following is a list of definitions of ACL types
  77 to be set in
  78 .Va ae_tag :
  79 .Pp
  80 .Bl -tag -width ".Dv ACL_UNDEFINED_FIELD" -offset indent -compact
  81 .It Dv ACL_UNDEFINED_FIELD
  82 Undefined ACL type.
  83 .It Dv ACL_USER_OBJ
  84 Discretionary access rights for processes whose effective user ID
  85 matches the user ID of the file's owner.
  86 .It Dv ACL_USER
  87 Discretionary access rights for processes whose effective user ID
  88 matches the ACL entry qualifier.
  89 .It Dv ACL_GROUP_OBJ
  90 Discretionary access rights for processes whose effective group ID
  91 or any supplemental groups
  92 match the group ID of the file's owner.
  93 .It Dv ACL_GROUP
  94 Discretionary access rights for processes whose effective group ID
  95 or any supplemental groups
  96 match the ACL entry qualifier.
  97 .It Dv ACL_MASK
  98 The maximum discretionary access rights that can be granted
  99 to a process in the file group class.
 100 .It Dv ACL_OTHER
 101 Discretionary access rights for processes not covered by any other ACL
 102 entry.
 103 .It Dv ACL_OTHER_OBJ
 104 Same as
 105 .Dv ACL_OTHER .
 106 Each ACL entry must contain exactly one
 107 .Dv ACL_USER_OBJ ,
 108 one
 109 .Dv ACL_GROUP_OBJ ,
 110 and one
 111 .Dv ACL_OTHER .
 112 If any of
 113 .Dv ACL_USER ,
 114 .Dv ACL_GROUP ,
 115 or
 116 .Dv ACL_OTHER
 117 are present, then exactly one
 118 .Dv ACL_MASK
 119 entry should be present.
 120 .El
 121 .It Vt uid_t Va ae_id
 122 The ID of user for whom this ACL describes access permissions.
 123 .It Vt acl_perm_t Va ae_perm
 124 This field defines what kind of access the process matching this ACL has
 125 for accessing the associated file.
 126 .Bl -tag -width ".Dv ACL_POSIX1E_BITS"
 127 .It Dv ACL_EXECUTE
 128 The process may execute the associated file.
 129 .It Dv ACL_WRITE
 130 The process may write to the associated file.
 131 .It Dv ACL_READ
 132 The process may read from the associated file.
 133 .It Dv ACL_PERM_NONE
 134 The process has no read, write or execute permissions
 135 to the associated file.
 136 .El
 137 .El
 138 .Sh IMPLEMENTATION NOTES
 139 .Bd -literal
 140 typedef mode_t  *acl_permset_t;
 141
 142 /* internal ACL structure */
 143 struct acl {
 144         int                     acl_cnt;
 145         struct acl_entry        acl_entry[ACL_MAX_ENTRIES];
 146 };
 147
 148 /* external ACL structure */
 149 struct acl_t_struct {
 150         struct acl              ats_acl;
 151         int                     ats_cur_entry;
 152 };
 153 typedef struct acl_t_struct *acl_t;
 154
 155 /*
 156  * Possible valid values for ae_tag field.
 157  */
 158 #define ACL_UNDEFINED_TAG       0x00000000
 159 #define ACL_USER_OBJ            0x00000001
 160 #define ACL_USER                0x00000002
 161 #define ACL_GROUP_OBJ           0x00000004
 162 #define ACL_GROUP               0x00000008
 163 #define ACL_MASK                0x00000010
 164 #define ACL_OTHER               0x00000020
 165 #define ACL_OTHER_OBJ           ACL_OTHER
 166
 167 /*
 168  * Possible valid values for acl_type_t arguments.
 169  */
 170 #define ACL_TYPE_ACCESS         0x00000000
 171 #define ACL_TYPE_DEFAULT        0x00000001
 172 #define ACL_TYPE_AFS            0x00000002
 173 #define ACL_TYPE_CODA           0x00000003
 174 #define ACL_TYPE_NTFS           0x00000004
 175 #define ACL_TYPE_NWFS           0x00000005
 176
 177 /*
 178  * Possible flags in ae_perm field.
 179  */
 180 #define ACL_EXECUTE             0x0001
 181 #define ACL_WRITE               0x0002
 182 #define ACL_READ                0x0004
 183 #define ACL_PERM_NONE           0x0000
 184 #define ACL_PERM_BITS           (ACL_EXECUTE | ACL_WRITE | ACL_READ)
 185 #define ACL_POSIX1E_BITS        (ACL_EXECUTE | ACL_WRITE | ACL_READ)
 186
 187 /*
 188  * Possible entry_id values for acl_get_entry()
 189  */
 190 #define ACL_FIRST_ENTRY         0
 191 #define ACL_NEXT_ENTRY          1
 192
 193 /*
 194  * Undefined value in ae_id field
 195  */
 196 #define ACL_UNDEFINED_ID        ((uid_t)-1)
 197 .Ed
 198 .Sh SEE ALSO
 199 .Xr acl 3 ,
 200 .Xr vaccess_acl_posix1e 9 ,
 201 .Xr VFS 9 ,
 202 .Xr vnaccess 9 ,
 203 .Xr VOP_ACLCHECK 9 ,
 204 .Xr VOP_GETACL 9 ,
 205 .Xr VOP_SETACL 9
 206 .Sh AUTHORS
 207 This manual page was written by
 208 .An Robert Watson .