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 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 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 69An ACL is constructed from a fixed size array of ACL entries, 70each of which consists of a set of permissions, principal namespace, 71and principal identifier. 72In this implementation, the 73.Vt acl_maxcnt 74field is always set to 75.Dv ACL_MAX_ENTRIES . 76.Pp 77Each individual ACL entry is of the type 78.Vt acl_entry_t , 79which is a structure with the following members: 80.Bl -tag -width 2n 81.It Vt acl_tag_t Va ae_tag 82The following is a list of definitions of ACL types 83to 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 88Undefined ACL type. 89.It Dv ACL_USER_OBJ 90Discretionary access rights for processes whose effective user ID 91matches the user ID of the file's owner. 92.It Dv ACL_USER 93Discretionary access rights for processes whose effective user ID 94matches the ACL entry qualifier. 95.It Dv ACL_GROUP_OBJ 96Discretionary access rights for processes whose effective group ID 97or any supplemental groups 98match the group ID of the file's owner. 99.It Dv ACL_GROUP 100Discretionary access rights for processes whose effective group ID 101or any supplemental groups 102match the ACL entry qualifier. 103.It Dv ACL_MASK 104The maximum discretionary access rights that can be granted 105to a process in the file group class. 106This is only valid for POSIX.1e ACLs. 107.It Dv ACL_OTHER 108Discretionary access rights for processes not covered by any other ACL 109entry. 110This is only valid for POSIX.1e ACLs. 111.It Dv ACL_OTHER_OBJ 112Same as 113.Dv ACL_OTHER . 114.It Dv ACL_EVERYONE 115Discretionary access rights for all users. 116This is only valid for NFSv4 ACLs. 117.El 118.Pp 119Each POSIX.1e ACL must contain exactly one 120.Dv ACL_USER_OBJ , 121one 122.Dv ACL_GROUP_OBJ , 123and one 124.Dv ACL_OTHER . 125If any of 126.Dv ACL_USER , 127.Dv ACL_GROUP , 128or 129.Dv ACL_OTHER 130are present, then exactly one 131.Dv ACL_MASK 132entry should be present. 133.It Vt uid_t Va ae_id 134The ID of user for whom this ACL describes access permissions. 135For entries other than 136.Dv ACL_USER 137and 138.Dv ACL_GROUP , 139this field should be set to 140.Dv ACL_UNDEFINED_ID . 141.It Vt acl_perm_t Va ae_perm 142This field defines what kind of access the process matching this ACL has 143for accessing the associated file. 144For POSIX.1e ACLs, the following are valid: 145.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" 146.It Dv ACL_EXECUTE 147The process may execute the associated file. 148.It Dv ACL_WRITE 149The process may write to the associated file. 150.It Dv ACL_READ 151The process may read from the associated file. 152.It Dv ACL_PERM_NONE 153The process has no read, write or execute permissions 154to the associated file. 155.El 156.Pp 157For NFSv4 ACLs, the following are valid: 158.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" 159.It Dv ACL_READ_DATA 160The process may read from the associated file. 161.It Dv ACL_LIST_DIRECTORY 162Same as 163.Dv ACL_READ_DATA . 164.It Dv ACL_WRITE_DATA 165The process may write to the associated file. 166.It Dv ACL_ADD_FILE 167Same as 168.Dv ACL_ACL_WRITE_DATA . 169.It Dv ACL_APPEND_DATA 170.It Dv ACL_ADD_SUBDIRECTORY 171Same as 172.Dv ACL_APPEND_DATA . 173.It Dv ACL_READ_NAMED_ATTRS 174Ignored. 175.It Dv ACL_WRITE_NAMED_ATTRS 176Ignored. 177.It Dv ACL_EXECUTE 178The 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 187Ignored. 188.El 189.It Vt acl_entry_type_t Va ae_entry_type 190This field defines the type of NFSv4 ACL entry. 191It is not used with POSIX.1e ACLs. 192The 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 198This field defines the inheritance flags of NFSv4 ACL entry. 199It is not used with POSIX.1e ACLs. 200The 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 218This manual page was written by 219.An Robert Watson . 220