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