1.\" Copyright (c) 2004-2009 Apple Inc. 2.\" Copyright (c) 2006, 2016 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Portions of this software were developed by BAE Systems, the University of 6.\" Cambridge Computer Laboratory, and Memorial University under DARPA/AFRL 7.\" contract FA8650-15-C-7558 ("CADETS"), as part of the DARPA Transparent 8.\" Computing (TC) research program. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of Apple Inc. ("Apple") nor the names of 19.\" its contributors may be used to endorse or promote products derived 20.\" from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR 26.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 30.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 31.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32.\" POSSIBILITY OF SUCH DAMAGE. 33.\" 34.Dd August 19, 2016 35.Dt AUDIT_CONTROL 5 36.Os 37.Sh NAME 38.Nm audit_control 39.Nd "audit system parameters" 40.Sh DESCRIPTION 41The 42.Nm 43file contains several audit system parameters. 44Each line of this file is of the form: 45.Pp 46.D1 Ar parameter Ns : Ns Ar value 47.Pp 48The parameters are: 49.Bl -tag -width indent 50.It Va dir 51The directory where audit log files are stored. 52There may be more than one of these entries. 53Changes to this entry can only be enacted by restarting the 54audit system. 55See 56.Xr audit 8 57for a description of how to restart the audit system. 58.It Va dist 59When set to 60.Va on 61or 62.Va yes , 63.Xr auditd 8 64will be creating hardlinks to all trail files in 65.Pa /var/audit/dist 66directory. 67Those hardlinks will be consumed by the 68.Xr auditdistd 8 69daemon. 70.It Va flags 71Specifies which audit event classes are audited for all users. 72.Xr audit_user 5 73describes how to audit events for individual users. 74See the information below for the format of the audit flags. 75.It Va host 76Specify the hostname or IP address to be used when setting the local 77systems's audit host information. 78This hostname will be converted into an IP or IPv6 address and will 79be included in the header of each audit record. 80Due to the possibility of transient errors coupled with the 81security issues in the DNS protocol itself, the use of DNS 82should be avoided. 83Instead, it is strongly recommended that the hostname be 84specified in the /etc/hosts file. 85For more information see 86.Xr hosts 5 . 87.It Va naflags 88Contains the audit flags that define what classes of events are audited when 89an action cannot be attributed to a specific user. 90.It Va minfree 91The minimum free space required on the file system audit logs are being written to. 92When the free space falls below this limit a warning will be issued. 93If no value for the minimum free space is set, the default of 20 percent is 94applied by the kernel. 95.It Va policy 96A list of global audit policy flags specifying various behaviors, such as 97fail stop, auditing of paths and arguments, etc. 98.It Va filesz 99Maximum trail size in bytes; if set to a non-0 value, the audit daemon will 100rotate the audit trail file at around this size. 101Sizes less than the minimum trail size (default of 512K) will be rejected as 102invalid. 103If 0, trail files will not be automatically rotated based on file size. 104For convenience, the trail size may be expressed with suffix letters: 105B (Bytes), K (Kilobytes), M (Megabytes), or G (Gigabytes). 106For example, 2M is the same as 2097152. 107.It Va expire-after 108Specifies when audit log files will expire and be removed. 109This may be after a time period has passed since the file was last 110written to or when the aggregate of all the trail files have reached a 111specified size or a combination of both. 112If no expire-after parameter is given then audit log files will not 113expire and be removed by the audit control system. 114See the information below for the format of the expiration 115specification. 116.It Va qsize 117Specifies the maximum number of outstanding committed audit records that can 118be in the kernel's post-commit queue pending write to disk. 119If this number has been reached, user threads performing an auditable event 120will be suspended until the queue has fallen below the limit. 121Depending on the underlying kernel implementation, the number of in-flight 122records can exceed this number, as it does not constrain uncommitted records 123(e.g., those associated with incomplete auditable system calls), and may also 124exclude the set of records extracted from the queue and currently being 125prepared for or undergoing I/O. 126Other operational limits may be affected by this parameter, such as the 127minimum free space on disk required to continue system operation, estimated as 128the maximum number of allowable in-flight records multiplied by the maximum 129audit record size. 130.El 131.Sh AUDIT FLAGS 132Audit flags are a comma-delimited list of audit classes as defined in the 133.Xr audit_class 5 134file. 135Event classes may be preceded by a prefix which changes their interpretation. 136The following prefixes may be used for each class: 137.Pp 138.Bl -tag -width indent -compact -offset indent 139.It (none) 140Record both successful and failed events. 141.It Li + 142Record successful events. 143.It Li - 144Record failed events. 145.It Li ^ 146Record neither successful nor failed events. 147.It Li ^+ 148Do not record successful events. 149.It Li ^- 150Do not record failed events. 151.El 152.Sh AUDIT POLICY FLAGS 153The policy flags field is a comma-delimited list of policy flags from the 154following list: 155.Pp 156.Bl -tag -width ".Cm zonename" -compact -offset indent 157.It Cm cnt 158Allow processes to continue running even though events are not being audited. 159If not set, processes will be suspended when the audit store space is 160exhausted. 161Currently, this is not a recoverable state. 162.It Cm ahlt 163Fail stop the system if unable to audit an event\[em]this consists of first 164draining pending records to disk, and then halting the operating system. 165.It Cm argv 166Audit command line arguments to 167.Xr execve 2 . 168.It Cm arge 169Audit environmental variable arguments to 170.Xr execve 2 . 171.It Cm seq 172Include a unique audit sequence number token in generated audit records (not 173implemented on 174.Fx 175or Darwin). 176.It Cm group 177Include supplementary groups list in generated audit records (not implemented 178on 179.Fx 180or Darwin; supplementary groups are never included in records on 181these systems). 182.It Cm trail 183Append a trailer token to each audit record (not implemented on 184.Fx 185or 186Darwin; trailers are always included in records on these systems). 187.It Cm path 188Include secondary file paths in audit records (not implemented on 189.Fx 190or 191Darwin; secondary paths are never included in records on these systems). 192.It Cm zonename 193Include a zone ID token with each audit record (not implemented on 194.Fx 195or 196Darwin; 197.Fx 198audit records do not currently include the jail ID or name). 199.It Cm perzone 200Enable auditing for each local zone (not implemented on 201.Fx 202or Darwin; on 203.Fx , 204audit records are collected from all jails and placed in a single 205global trail, and only limited audit controls are permitted within a jail). 206.El 207.Pp 208It is recommended that installations set the 209.Cm cnt 210flag but not 211.Cm ahlt 212flag unless it is intended that audit logs exceeding available disk space 213halt the system. 214.Sh AUDIT LOG EXPIRATION SPECIFICATION 215The expiration specification can be one value or two values with the 216logical conjunction of AND/OR between them. 217Values for the audit log file age are numbers with the following 218suffixes: 219.Pp 220.Bl -tag -width "(space) or" -compact -offset indent 221.It Li s 222Log file age in seconds. 223.It Li h 224Log file age in hours. 225.It Li d 226Log file age in days. 227.It Li y 228Log file age in years. 229.El 230.Pp 231Values for the disk space used are numbers with the following suffixes: 232.Pp 233.Bl -tag -width "(space) or" -compact -offset indent 234.It (space) or 235.It Li B 236Disk space used in Bytes. 237.It Li K 238Disk space used in Kilobytes. 239.It Li M 240Disk space used in Megabytes. 241.It Li G 242Disk space used in Gigabytes. 243.El 244.Pp 245The suffixes on the values are case sensitive. 246If both an age and disk space value are used they are separated by 247AND or OR and both values are used to determine when audit 248log files expire. 249In the case of AND, both the age and disk space conditions must be met 250before the log file is removed. 251In the case of OR, either condition may expire the log file. 252For example: 253.Bd -literal -offset indent 254expire-after: 60d AND 1G 255.Ed 256.Pp 257will expire files that are older than 60 days but only if 1 258gigabyte of disk space total is being used by the audit logs. 259.Sh DEFAULT 260The following settings appear in the default 261.Nm 262file: 263.Bd -literal -offset indent 264dir:/var/audit 265flags:lo,aa 266minfree:5 267naflags:lo,aa 268policy:cnt,argv 269filesz:2M 270expire-after:10M 271.Ed 272.Pp 273The 274.Va flags 275parameter above specifies the system-wide mask corresponding to login/logout 276as well as authentication and authorization events. 277The 278.Va policy 279parameter specifies that the system should neither fail stop nor suspend 280processes when the audit store fills and that command line arguments should 281be audited for 282.Dv AUE_EXECVE 283events. 284The trail file will be automatically rotated by the audit daemon when the 285file size reaches approximately 2MB. 286Trail files will expire when their aggregate size exceeds 10MB. 287.Sh FILES 288.Bl -tag -width ".Pa /etc/security/audit_control" -compact 289.It Pa /etc/security/audit_control 290.El 291.Sh SEE ALSO 292.Xr auditon 2 , 293.Xr audit 4 , 294.Xr audit_class 5 , 295.Xr audit_event 5 , 296.Xr audit_user 5 , 297.Xr audit 8 , 298.Xr auditd 8 299.Sh HISTORY 300The OpenBSM implementation was created by McAfee Research, the security 301division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. 302It was subsequently adopted by the TrustedBSD Project as the foundation for 303the OpenBSM distribution. 304.Sh AUTHORS 305.An -nosplit 306This software was created by McAfee Research, the security research division 307of McAfee, Inc., under contract to Apple Computer Inc. 308Additional authors include 309.An Wayne Salamon , 310.An Robert Watson , 311and SPARTA Inc. 312.Pp 313The Basic Security Module (BSM) interface to audit records and audit event 314stream format were defined by Sun Microsystems. 315