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 January 29, 2009 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. If 88.Dv AUDIT_ARGE 89is set, then the environment variables passed to the 90.Xr execve 2 91system call will be audited. The default policy is none of the audit policy 92control flags set. 93.It Dv A_SETKAUDIT 94Set the host information. 95The 96.Fa data 97argument 98must point to a 99.Vt auditinfo_addr_t 100structure containing the host IP address information. 101After setting, audit records 102that are created as a result of kernel events will contain 103this information. 104.It Dv A_SETKMASK 105Set the kernel preselection masks (success and failure). 106The 107.Fa data 108argument 109must point to a 110.Vt au_mask_t 111structure containing the mask values as defined in 112.In bsm/audit.h . 113These masks are used for non-attributable audit event preselection. 114The field 115.Fa am_success 116specifies which classes of successful audit events are to be logged to the 117audit trail. The field 118.Fa am_failure 119specifies which classes of failed audit events are to be logged. The value of 120both fields is the bitwise OR'ing of the audit event classes specified in 121.Fa bsm/audit.h . 122The various audit classes are described more fully in 123.Xr audit_class 5 . 124.It Dv A_SETQCTRL 125Set kernel audit queue parameters. 126The 127.Fa data 128argument 129must point to a 130.Vt au_qctrl_t 131structure (defined in 132.In bsm/audit.h ) 133containing the kernel audit queue control settings: 134.Fa aq_hiwater , 135.Fa aq_lowater , 136.Fa aq_bufsz , 137.Fa aq_delay , 138and 139.Fa aq_minfree . 140The field 141.Fa aq_hiwater 142defines the maximum number of audit record entries in the queue used to store 143the audit records ready for delivery to disk. 144New records are inserted at the tail of the queue and removed from the head. 145For new records which would exceed the 146high water mark, the calling thread is inserted into the wait queue, waiting 147for the audit queue to have enough space available as defined with the field 148.Fa aq_lowater . 149The field 150.Fa aq_bufsz 151defines the maximum length of the audit record that can be supplied with 152.Xr audit 2 . 153The field 154.Fa aq_delay 155is unused. 156The field 157.Fa aq_minfree 158specifies the minimum amount of free blocks on the disk device used to store 159audit records. 160If the value of free blocks falls below the configured 161minimum amount, the kernel informs the audit daemon about low disk space. 162The value is to be specified in percent of free file system blocks. 163A value of 0 results in a disabling of the check. 164The default and maximum values (default/maximum) for the 165audit queue control parameters are: 166.Pp 167.Bl -column aq_hiwater -offset indent -compact 168.It aq_hiwater Ta 100/10000 (audit records) 169.It aq_lowater Ta 10/aq_hiwater (audit records) 170.It aq_bufsz Ta 32767/1048576 (bytes) 171.It aq_delay Ta (Not currently used.) 172.El 173.It Dv A_SETSTAT 174Return 175.Er ENOSYS . 176(Not implemented.) 177.It Dv A_SETUMASK 178Return 179.Er ENOSYS . 180(Not implemented.) 181.It Dv A_SETSMASK 182Return 183.Er ENOSYS . 184(Not implemented.) 185.It Dv A_SETCOND 186Set the current auditing condition. 187The 188.Fa data 189argument 190must point to a 191.Vt int 192value containing the new 193audit condition, one of 194.Dv AUC_AUDITING , 195.Dv AUC_NOAUDIT , 196or 197.Dv AUC_DISABLED . 198If 199.Dv AUC_NOAUDIT 200is set, then auditing is temporarily suspended. If 201.Dv AUC_AUDITING 202is set, auditing is resumed. If 203.Dv AUC_DISABLED 204is set, the auditing system will 205shutdown, draining all audit records and closing out the audit trail file. 206.It Dv A_SETCLASS 207Set the event class preselection mask for an audit event. 208The 209.Fa data 210argument 211must point to a 212.Vt au_evclass_map_t 213structure containing the audit event and mask. 214The field 215.Fa ec_number 216is the audit event and 217.Fa ec_class 218is the audit class mask. See 219.Xr audit_event 5 220for more information on audit event to class mapping. 221.It Dv A_SETPMASK 222Set the preselection masks for a process. 223The 224.Fa data 225argument 226must point to a 227.Vt auditpinfo_t 228structure that contains the given process's audit 229preselection masks for both success and failure. 230The field 231.Fa ap_pid 232is the process id of the target process. 233The field 234.Fa ap_mask 235must point to a 236.Fa au_mask_t 237structure which holds the preselection masks as described in the 238.Dv A_SETKMASK 239section above. 240.It Dv A_SETFSIZE 241Set the maximum size of the audit log file. 242The 243.Fa data 244argument 245must point to a 246.Vt au_fstat_t 247structure with the 248.Va af_filesz 249field set to the maximum audit log file size. 250A value of 0 251indicates no limit to the size. 252.It Dv A_GETCLASS 253Return the event to class mapping for the designated audit event. 254The 255.Fa data 256argument 257must point to a 258.Vt au_evclass_map_t 259structure. See the 260.Dv A_SETCLASS 261section above for more information. 262.It Dv A_GETKAUDIT 263Get the current host information. 264The 265.Fa data 266argument 267must point to a 268.Vt auditinfo_addr_t 269structure. 270.It Dv A_GETPINFO 271Return the audit settings for a process. 272The 273.Fa data 274argument 275must point to a 276.Vt auditpinfo_t 277structure which will be set to contain 278.Fa ap_auid 279(the audit ID), 280.Fa ap_mask 281(the preselection mask), 282.Fa ap_termid 283(the terminal ID), and 284.Fa ap_asid 285(the audit session ID) 286of the given target process. 287The process ID of the target process is passed 288into the kernel using the 289.Fa ap_pid 290field. 291See the section 292.Dv A_SETPMASK 293above and 294.Xr getaudit 2 295for more information. 296.It Dv A_GETPINFO_ADDR 297Return the extended audit settings for a process. 298The 299.Fa data 300argument 301must point to a 302.Vt auditpinfo_addr_t 303structure which is similar to the 304.Vt auditpinfo_addr_t 305structure described above. 306The exception is the 307.Fa ap_termid 308(the terminal ID) field which points to a 309.Vt au_tid_addr_t 310structure can hold much a larger terminal address and an address type. 311The process ID of the target process is passed into the kernel using the 312.Fa ap_pid 313field. 314See the section 315.Dv A_SETPMASK 316above and 317.Xr getaudit 2 318for more information. 319.It Dv A_GETSINFO_ADDR 320Return the extended audit settings for a session. 321The 322.Fa data 323argument 324must point to a 325.Vt auditinfo_addr_t 326structure. 327The audit session ID of the target session is passed 328into the kernel using the 329.Fa ai_asid 330field. See 331.Xr getaudit_addr 2 332for more information about the 333.Vt auditinfo_addr_t 334structure. 335.It Dv A_GETKMASK 336Return the current kernel preselection masks. 337The 338.Fa data 339argument 340must point to a 341.Vt au_mask_t 342structure which will be set to 343the current kernel preselection masks for non-attributable events. 344.It Dv A_GETPOLICY 345Return the current audit policy setting. 346The 347.Fa data 348argument 349must point to a 350.Vt int 351value which will be set to 352one of the current audit policy flags. 353The audit policy flags are 354described in the 355.Dv A_SETPOLICY 356section above. 357.It Dv A_GETQCTRL 358Return the current kernel audit queue control parameters. 359The 360.Fa data 361argument 362must point to a 363.Vt au_qctrl_t 364structure which will be set to the current 365kernel audit queue control parameters. 366See the 367.Dv A_SETQCTL 368section above for more information. 369.It Dv A_GETFSIZE 370Returns the maximum size of the audit log file. 371The 372.Fa data 373argument 374must point to a 375.Vt au_fstat_t 376structure. 377The 378.Va af_filesz 379field will be set to the maximum audit log file size. 380A value of 0 indicates no limit to the size. 381The 382.Va af_currsz 383field 384will be set to the current audit log file size. 385.It Dv A_GETCWD 386.\" [COMMENTED OUT]: Valid description, not yet implemented. 387.\" Return the current working directory as stored in the audit subsystem. 388Return 389.Er ENOSYS . 390(Not implemented.) 391.It Dv A_GETCAR 392.\" [COMMENTED OUT]: Valid description, not yet implemented. 393.\"Stores and returns the current active root as stored in the audit 394.\"subsystem. 395Return 396.Er ENOSYS . 397(Not implemented.) 398.It Dv A_GETSTAT 399.\" [COMMENTED OUT]: Valid description, not yet implemented. 400.\"Return the statistics stored in the audit system. 401Return 402.Er ENOSYS . 403(Not implemented.) 404.It Dv A_GETCOND 405Return the current auditing condition. 406The 407.Fa data 408argument 409must point to a 410.Vt int 411value which will be set to 412the current audit condition, one of 413.Dv AUC_AUDITING , 414.Dv AUC_NOAUDIT 415or 416.Dv AUC_DISABLED . 417See the 418.Dv A_SETCOND 419section above for more information. 420.It Dv A_SENDTRIGGER 421Send a trigger to the audit daemon. 422The 423.Fa data 424argument 425must point to a 426.Vt int 427value set to one of the acceptable 428trigger values: 429.Dv AUDIT_TRIGGER_LOW_SPACE 430(low disk space where the audit log resides), 431.Dv AUDIT_TRIGGER_OPEN_NEW 432(open a new audit log file), 433.Dv AUDIT_TRIGGER_READ_FILE 434(read the 435.Pa audit_control 436file), 437.Dv AUDIT_TRIGGER_CLOSE_AND_DIE 438(close the current log file and exit), 439.Dv AUDIT_TRIGGER_NO_SPACE 440(no disk space left for audit log file). 441.Dv AUDIT_TRIGGER_ROTATE_USER 442(request audit log file rotation). 443.Dv AUDIT_TRIGGER_INITIALIZE 444(initialize audit subsystem for Mac OS X only). 445or 446.Dv AUDIT_TRIGGER_EXPIRE_TRAILS 447(request audit log file expiration). 448.El 449.Sh RETURN VALUES 450.Rv -std 451.Sh ERRORS 452The 453.Fn auditon 454function will fail if: 455.Bl -tag -width Er 456.It Bq Er ENOSYS 457Returned by options not yet implemented. 458.It Bq Er EFAULT 459A failure occurred while data transferred to or from 460the kernel failed. 461.It Bq Er EINVAL 462Illegal argument was passed by a system call. 463.It Bq Er EPERM 464The process does not have sufficient permission to complete 465the operation. 466.El 467.Pp 468The 469.Dv A_SENDTRIGGER 470command is specific to the 471.Fx 472and Mac OS X implementations, and is not present in Solaris. 473.Sh SEE ALSO 474.Xr audit 2 , 475.Xr auditctl 2 , 476.Xr getaudit 2 , 477.Xr getaudit_addr 2 , 478.Xr getauid 2 , 479.Xr setaudit 2 , 480.Xr setaudit_addr 2 , 481.Xr setauid 2 , 482.Xr libbsm 3 483.Sh HISTORY 484The OpenBSM implementation was created by McAfee Research, the security 485division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. 486It was subsequently adopted by the TrustedBSD Project as the foundation for 487the OpenBSM distribution. 488.Sh AUTHORS 489.An -nosplit 490This software was created by McAfee Research, the security research division 491of McAfee, Inc., under contract to Apple Computer Inc. 492Additional authors include 493.An Wayne Salamon , 494.An Robert Watson , 495and SPARTA Inc. 496.Pp 497The Basic Security Module (BSM) interface to audit records and audit event 498stream format were defined by Sun Microsystems. 499.Pp 500This manual page was written by 501.An Tom Rhodes Aq trhodes@FreeBSD.org , 502.An Robert Watson Aq rwatson@FreeBSD.org , 503and 504.An Wayne Salamon Aq wsalamon@FreeBSD.org . 505