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