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