1.\"- 2.\" Copyright (c) 2008-2009 Apple Inc. 3.\" Copyright (c) 2005 Robert N. M. Watson 4.\" Copyright (c) 2005 Tom Rhodes 5.\" Copyright (c) 2005 Wayne J. Salamon 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd April 7, 2016 30.Dt AUDITON 2 31.Os 32.Sh NAME 33.Nm auditon 34.Nd "configure system audit parameters" 35.Sh SYNOPSIS 36.In bsm/audit.h 37.Ft int 38.Fn auditon "int cmd" "void *data" "u_int length" 39.Sh DESCRIPTION 40The 41.Fn auditon 42system call is used to manipulate various audit control operations. 43The 44.Fa data 45argument 46should point to a structure whose type depends on the command. 47The 48.Fa length 49argument 50specifies the size of 51.Fa *data 52in bytes. 53The 54.Fa cmd 55argument 56may be any of the following: 57.Bl -tag -width ".It Dv A_GETPINFO_ADDR" 58.It Dv A_SETPOLICY 59Set audit policy flags. 60The 61.Fa data 62argument 63must point to a 64.Vt int 65value set to one or more the following audit 66policy control values bitwise OR'ed together: 67.Dv AUDIT_CNT , 68.Dv AUDIT_AHLT , 69.Dv AUDIT_ARGV , 70and 71.Dv AUDIT_ARGE . 72If 73.Dv AUDIT_CNT is set, the system will continue even if it becomes low 74on space and discontinue logging events until the low space condition is 75remedied. 76If it is not set, audited events will block until the low space 77condition is remedied. 78Unaudited events, however, are unaffected. 79If 80.Dv AUDIT_AHLT is set, a 81.Xr panic 9 82if it cannot write an event to the global audit log file. 83If 84.Dv AUDIT_ARGV 85is set, then the argument list passed to the 86.Xr execve 2 87system call will be audited. 88If 89.Dv AUDIT_ARGE 90is set, then the environment variables passed to the 91.Xr execve 2 92system call will be audited. 93The default policy is none of the audit policy 94control flags set. 95.It Dv A_SETKAUDIT 96Set the host information. 97The 98.Fa data 99argument 100must point to a 101.Vt auditinfo_addr_t 102structure containing the host IP address information. 103After setting, audit records 104that are created as a result of kernel events will contain 105this information. 106.It Dv A_SETKMASK 107Set the kernel preselection masks (success and failure). 108The 109.Fa data 110argument 111must point to a 112.Vt au_mask_t 113structure containing the mask values as defined in 114.In bsm/audit.h . 115These masks are used for non-attributable audit event preselection. 116The field 117.Fa am_success 118specifies which classes of successful audit events are to be logged to the 119audit trail. 120The field 121.Fa am_failure 122specifies which classes of failed audit events are to be logged. 123The value of 124both fields is the bitwise OR'ing of the audit event classes specified in 125.Fa bsm/audit.h . 126The various audit classes are described more fully in 127.Xr audit_class 5 . 128.It Dv A_SETQCTRL 129Set kernel audit queue parameters. 130The 131.Fa data 132argument 133must point to a 134.Vt au_qctrl_t 135structure (defined in 136.In bsm/audit.h ) 137containing the kernel audit queue control settings: 138.Fa aq_hiwater , 139.Fa aq_lowater , 140.Fa aq_bufsz , 141.Fa aq_delay , 142and 143.Fa aq_minfree . 144The field 145.Fa aq_hiwater 146defines the maximum number of audit record entries in the queue used to store 147the audit records ready for delivery to disk. 148New records are inserted at the tail of the queue and removed from the head. 149For new records which would exceed the 150high water mark, the calling thread is inserted into the wait queue, waiting 151for the audit queue to have enough space available as defined with the field 152.Fa aq_lowater . 153The field 154.Fa aq_bufsz 155defines the maximum length of the audit record that can be supplied with 156.Xr audit 2 . 157The field 158.Fa aq_delay 159is unused. 160The field 161.Fa aq_minfree 162specifies the minimum amount of free blocks on the disk device used to store 163audit records. 164If the value of free blocks falls below the configured 165minimum amount, the kernel informs the audit daemon about low disk space. 166The value is to be specified in percent of free file system blocks. 167A value of 0 results in a disabling of the check. 168The default and maximum values (default/maximum) for the 169audit queue control parameters are: 170.Pp 171.Bl -column aq_hiwater -offset indent -compact 172.It aq_hiwater Ta 100/10000 (audit records) 173.It aq_lowater Ta 10/aq_hiwater (audit records) 174.It aq_bufsz Ta 32767/1048576 (bytes) 175.It aq_delay Ta (Not currently used.) 176.El 177.It Dv A_SETSTAT 178Return 179.Er ENOSYS . 180(Not implemented.) 181.It Dv A_SETUMASK 182Return 183.Er ENOSYS . 184(Not implemented.) 185.It Dv A_SETSMASK 186Return 187.Er ENOSYS . 188(Not implemented.) 189.It Dv A_SETCOND 190Set the current auditing condition. 191The 192.Fa data 193argument 194must point to a 195.Vt int 196value containing the new 197audit condition, one of 198.Dv AUC_AUDITING , 199.Dv AUC_NOAUDIT , 200or 201.Dv AUC_DISABLED . 202If 203.Dv AUC_NOAUDIT 204is set, then auditing is temporarily suspended. 205If 206.Dv AUC_AUDITING 207is set, auditing is resumed. 208If 209.Dv AUC_DISABLED 210is set, the auditing system will 211shutdown, draining all audit records and closing out the audit trail file. 212.It Dv A_SETCLASS 213Set the event class preselection mask for an audit event. 214The 215.Fa data 216argument 217must point to a 218.Vt au_evclass_map_t 219structure containing the audit event and mask. 220The field 221.Fa ec_number 222is the audit event and 223.Fa ec_class 224is the audit class mask. 225See 226.Xr audit_event 5 227for more information on audit event to class mapping. 228.It Dv A_SETPMASK 229Set the preselection masks for a process. 230The 231.Fa data 232argument 233must point to a 234.Vt auditpinfo_t 235structure that contains the given process's audit 236preselection masks for both success and failure. 237The field 238.Fa ap_pid 239is the process id of the target process. 240The field 241.Fa ap_mask 242must point to a 243.Fa au_mask_t 244structure which holds the preselection masks as described in the 245.Dv A_SETKMASK 246section above. 247.It Dv A_SETFSIZE 248Set the maximum size of the audit log file. 249The 250.Fa data 251argument 252must point to a 253.Vt au_fstat_t 254structure with the 255.Va af_filesz 256field set to the maximum audit log file size. 257A value of 0 258indicates no limit to the size. 259.It Dv A_GETCLASS 260Return the event to class mapping for the designated audit event. 261The 262.Fa data 263argument 264must point to a 265.Vt au_evclass_map_t 266structure. 267See the 268.Dv A_SETCLASS 269section above for more information. 270.It Dv A_GETKAUDIT 271Get the current host information. 272The 273.Fa data 274argument 275must point to a 276.Vt auditinfo_addr_t 277structure. 278.It Dv A_GETPINFO 279Return the audit settings for a process. 280The 281.Fa data 282argument 283must point to a 284.Vt auditpinfo_t 285structure which will be set to contain 286.Fa ap_auid 287(the audit ID), 288.Fa ap_mask 289(the preselection mask), 290.Fa ap_termid 291(the terminal ID), and 292.Fa ap_asid 293(the audit session ID) 294of the given target process. 295The process ID of the target process is passed 296into the kernel using the 297.Fa ap_pid 298field. 299See the section 300.Dv A_SETPMASK 301above and 302.Xr getaudit 2 303for more information. 304.It Dv A_GETPINFO_ADDR 305Return the extended audit settings for a process. 306The 307.Fa data 308argument 309must point to a 310.Vt auditpinfo_addr_t 311structure which is similar to the 312.Vt auditpinfo_t 313structure described above. 314The exception is the 315.Fa ap_termid 316(the terminal ID) field which points to a 317.Vt au_tid_addr_t 318structure can hold much a larger terminal address and an address type. 319The process ID of the target process is passed into the kernel using the 320.Fa ap_pid 321field. 322See the section 323.Dv A_SETPMASK 324above and 325.Xr getaudit 2 326for more information. 327.It Dv A_GETSINFO_ADDR 328Return the extended audit settings for a session. 329The 330.Fa data 331argument 332must point to a 333.Vt auditinfo_addr_t 334structure. 335The audit session ID of the target session is passed 336into the kernel using the 337.Fa ai_asid 338field. 339See 340.Xr getaudit_addr 2 341for more information about the 342.Vt auditinfo_addr_t 343structure. 344.It Dv A_GETKMASK 345Return the current kernel preselection masks. 346The 347.Fa data 348argument 349must point to a 350.Vt au_mask_t 351structure which will be set to 352the current kernel preselection masks for non-attributable events. 353.It Dv A_GETPOLICY 354Return the current audit policy setting. 355The 356.Fa data 357argument 358must point to a 359.Vt int 360value which will be set to 361one of the current audit policy flags. 362The audit policy flags are 363described in the 364.Dv A_SETPOLICY 365section above. 366.It Dv A_GETQCTRL 367Return the current kernel audit queue control parameters. 368The 369.Fa data 370argument 371must point to a 372.Vt au_qctrl_t 373structure which will be set to the current 374kernel audit queue control parameters. 375See the 376.Dv A_SETQCTL 377section above for more information. 378.It Dv A_GETFSIZE 379Returns the maximum size of the audit log file. 380The 381.Fa data 382argument 383must point to a 384.Vt au_fstat_t 385structure. 386The 387.Va af_filesz 388field will be set to the maximum audit log file size. 389A value of 0 indicates no limit to the size. 390The 391.Va af_currsz 392field 393will be set to the current audit log file size. 394.It Dv A_GETCWD 395.\" [COMMENTED OUT]: Valid description, not yet implemented. 396.\" Return the current working directory as stored in the audit subsystem. 397Return 398.Er ENOSYS . 399(Not implemented.) 400.It Dv A_GETCAR 401.\" [COMMENTED OUT]: Valid description, not yet implemented. 402.\"Stores and returns the current active root as stored in the audit 403.\"subsystem. 404Return 405.Er ENOSYS . 406(Not implemented.) 407.It Dv A_GETSTAT 408.\" [COMMENTED OUT]: Valid description, not yet implemented. 409.\"Return the statistics stored in the audit system. 410Return 411.Er ENOSYS . 412(Not implemented.) 413.It Dv A_GETCOND 414Return the current auditing condition. 415The 416.Fa data 417argument 418must point to a 419.Vt int 420value which will be set to 421the current audit condition, one of 422.Dv AUC_AUDITING , 423.Dv AUC_NOAUDIT 424or 425.Dv AUC_DISABLED . 426See the 427.Dv A_SETCOND 428section above for more information. 429.It Dv A_SENDTRIGGER 430Send a trigger to the audit daemon. 431The 432.Fa data 433argument 434must point to a 435.Vt int 436value set to one of the acceptable 437trigger values: 438.Dv AUDIT_TRIGGER_LOW_SPACE 439(low disk space where the audit log resides), 440.Dv AUDIT_TRIGGER_OPEN_NEW 441(open a new audit log file), 442.Dv AUDIT_TRIGGER_READ_FILE 443(read the 444.Pa audit_control 445file), 446.Dv AUDIT_TRIGGER_CLOSE_AND_DIE 447(close the current log file and exit), 448.Dv AUDIT_TRIGGER_NO_SPACE 449(no disk space left for audit log file). 450.Dv AUDIT_TRIGGER_ROTATE_USER 451(request audit log file rotation). 452.Dv AUDIT_TRIGGER_INITIALIZE 453(initialize audit subsystem for Mac OS X only). 454or 455.Dv AUDIT_TRIGGER_EXPIRE_TRAILS 456(request audit log file expiration). 457.El 458.Sh RETURN VALUES 459.Rv -std 460.Sh ERRORS 461The 462.Fn auditon 463function will fail if: 464.Bl -tag -width Er 465.It Bq Er ENOSYS 466Returned by options not yet implemented. 467.It Bq Er EFAULT 468A failure occurred while data transferred to or from 469the kernel failed. 470.It Bq Er EINVAL 471Illegal argument was passed by a system call. 472.It Bq Er EPERM 473The process does not have sufficient permission to complete 474the operation. 475.El 476.Pp 477The 478.Dv A_SENDTRIGGER 479command is specific to the 480.Fx 481and Mac OS X implementations, and is not present in Solaris. 482.Sh SEE ALSO 483.Xr audit 2 , 484.Xr auditctl 2 , 485.Xr getaudit 2 , 486.Xr getaudit_addr 2 , 487.Xr getauid 2 , 488.Xr setaudit 2 , 489.Xr setaudit_addr 2 , 490.Xr setauid 2 , 491.Xr libbsm 3 492.Sh HISTORY 493The OpenBSM implementation was created by McAfee Research, the security 494division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. 495It was subsequently adopted by the TrustedBSD Project as the foundation for 496the OpenBSM distribution. 497.Sh AUTHORS 498.An -nosplit 499This software was created by McAfee Research, the security research division 500of McAfee, Inc., under contract to Apple Computer Inc. 501Additional authors include 502.An Wayne Salamon , 503.An Robert Watson , 504and SPARTA Inc. 505.Pp 506The Basic Security Module (BSM) interface to audit records and audit event 507stream format were defined by Sun Microsystems. 508.Pp 509This manual page was written by 510.An Tom Rhodes Aq trhodes@FreeBSD.org , 511.An Robert Watson Aq rwatson@FreeBSD.org , 512and 513.An Wayne Salamon Aq wsalamon@FreeBSD.org . 514