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 39In the kernel configuration file: 40.Cd "options UFS_ACL" 41.Sh DESCRIPTION 42Access control lists, or ACLs, 43allow fine-grained specification of rights 44for vnodes representing files and directories. 45However, as there are a plethora of file systems with differing ACL semantics, 46the vnode interface is aware only of the syntax of ACLs, 47relying on the underlying file system to implement the details. 48Depending on the underlying file system, each file or directory 49may have zero or more ACLs associated with it, named using the 50.Fa type 51field of the appropriate vnode ACL calls: 52.Xr VOP_ACLCHECK 9 , 53.Xr VOP_GETACL 9 , 54and 55.Xr VOP_SETACL 9 . 56.Pp 57Currently, each ACL is represented in-kernel by a fixed-size 58.Vt acl 59structure, defined as follows: 60.Bd -literal -offset indent 61struct acl { 62 int acl_cnt; 63 struct acl_entry acl_entry[ACL_MAX_ENTRIES]; 64}; 65.Ed 66.Pp 67An ACL is constructed from a fixed size array of ACL entries, 68each of which consists of a set of permissions, principal namespace, 69and principal identifier. 70.Pp 71Each individual ACL entry is of the type 72.Vt acl_entry_t , 73which is a structure with the following members: 74.Bl -tag -width 2n 75.It Vt acl_tag_t Va ae_tag 76The following is a list of definitions of ACL types 77to 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 82Undefined ACL type. 83.It Dv ACL_USER_OBJ 84Discretionary access rights for processes whose effective user ID 85matches the user ID of the file's owner. 86.It Dv ACL_USER 87Discretionary access rights for processes whose effective user ID 88matches the ACL entry qualifier. 89.It Dv ACL_GROUP_OBJ 90Discretionary access rights for processes whose effective group ID 91or any supplemental groups 92match the group ID of the file's owner. 93.It Dv ACL_GROUP 94Discretionary access rights for processes whose effective group ID 95or any supplemental groups 96match the ACL entry qualifier. 97.It Dv ACL_MASK 98The maximum discretionary access rights that can be granted 99to a process in the file group class. 100.It Dv ACL_OTHER 101Discretionary access rights for processes not covered by any other ACL 102entry. 103.It Dv ACL_OTHER_OBJ 104Same as 105.Dv ACL_OTHER . 106Each ACL entry must contain exactly one 107.Dv ACL_USER_OBJ , 108one 109.Dv ACL_GROUP_OBJ , 110and one 111.Dv ACL_OTHER . 112If any of 113.Dv ACL_USER , 114.Dv ACL_GROUP , 115or 116.Dv ACL_OTHER 117are present, then exactly one 118.Dv ACL_MASK 119entry should be present. 120.El 121.It Vt uid_t Va ae_id 122The ID of user for whom this ACL describes access permissions. 123.It Vt acl_perm_t Va ae_perm 124This field defines what kind of access the process matching this ACL has 125for accessing the associated file. 126.Bl -tag -width ".Dv ACL_POSIX1E_BITS" 127.It Dv ACL_EXECUTE 128The process may execute the associated file. 129.It Dv ACL_WRITE 130The process may write to the associated file. 131.It Dv ACL_READ 132The process may read from the associated file. 133.It Dv ACL_PERM_NONE 134The process has no read, write or execute permissions 135to the associated file. 136.El 137.El 138.Pp 139.Sh IMPLEMENTATION NOTES 140.Bd -literal 141typedef mode_t *acl_permset_t; 142 143/* internal ACL structure */ 144struct acl { 145 int acl_cnt; 146 struct acl_entry acl_entry[ACL_MAX_ENTRIES]; 147}; 148 149/* external ACL structure */ 150struct acl_t_struct { 151 struct acl ats_acl; 152 int ats_cur_entry; 153}; 154typedef struct acl_t_struct *acl_t; 155 156/* 157 * Possible valid values for ae_tag field. 158 */ 159#define ACL_UNDEFINED_TAG 0x00000000 160#define ACL_USER_OBJ 0x00000001 161#define ACL_USER 0x00000002 162#define ACL_GROUP_OBJ 0x00000004 163#define ACL_GROUP 0x00000008 164#define ACL_MASK 0x00000010 165#define ACL_OTHER 0x00000020 166#define ACL_OTHER_OBJ ACL_OTHER 167 168/* 169 * Possible valid values for acl_type_t arguments. 170 */ 171#define ACL_TYPE_ACCESS 0x00000000 172#define ACL_TYPE_DEFAULT 0x00000001 173#define ACL_TYPE_AFS 0x00000002 174#define ACL_TYPE_CODA 0x00000003 175#define ACL_TYPE_NTFS 0x00000004 176#define ACL_TYPE_NWFS 0x00000005 177 178/* 179 * Possible flags in ae_perm field. 180 */ 181#define ACL_EXECUTE 0x0001 182#define ACL_WRITE 0x0002 183#define ACL_READ 0x0004 184#define ACL_PERM_NONE 0x0000 185#define ACL_PERM_BITS (ACL_EXECUTE | ACL_WRITE | ACL_READ) 186#define ACL_POSIX1E_BITS (ACL_EXECUTE | ACL_WRITE | ACL_READ) 187 188/* 189 * Possible entry_id values for acl_get_entry() 190 */ 191#define ACL_FIRST_ENTRY 0 192#define ACL_NEXT_ENTRY 1 193 194/* 195 * Undefined value in ae_id field 196 */ 197#define ACL_UNDEFINED_ID ((uid_t)-1) 198.Ed 199.Sh SEE ALSO 200.Xr acl 3 , 201.Xr vaccess_acl_posix1e 9 , 202.Xr VFS 9 , 203.Xr vnaccess 9 , 204.Xr VOP_ACLCHECK 9 , 205.Xr VOP_GETACL 9 , 206.Xr VOP_SETACL 9 207.Sh AUTHORS 208This man page was written by 209.An Robert Watson . 210