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