xnu-1228.9.59.tar.gz

[apple/xnu.git] / bsd / man / man2 / auditon.2

.\"
.\" Copyright (c) 2007 Apple Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\" 
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this
.\" file.
.\" 
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\" 
.\" @APPLE_LICENSE_HEADER_END@
.\"
.Dd July 30, 2007
.Dt AUDITON 2
.Os Darwin
.Sh NAME
.Nm auditon
.Nd configure the current audit parameters on the system
.Sh SYNOPSIS
.Fd #include <bsm/audit.h>
.Ft int
.Fn auditon "int cmd" "void * data" "int length"
.Sh DESCRIPTION
The
.Fn auditon
function manipulates various audit parameters. The 
.Fa data 
argument points to the appropriate structure from the header file.
.Fa Length
is the size of the 
.Fa data 
parameter in bytes. It will typically be the sizeof the the structure.
.Sh PARAMETERS
.Bl -tag -width Er
.It A_GETPOLICY
Get the current audit policy. 
.Fa Data
should point to a long. The policy is the bitwise OR'ing of the 
appropriate flags from 
.Fa bsm/audit.h .
If AUDIT_AHLT is set, the system will kernel panic if it cannot write to the
global audit trail.  If AUDIT_CNT is not set and the system becomes low on
space, audited events will block until the low space condition is remedied.
Unaudited events are unaffected. The other policy flags are not implemented.
.It A_SETPOLICY
Set the current audit policy.
.Fa Data 
should point to a long specifying the desired audit policy, as described in
A_GETPOLICY.
.It A_GETKMASK
Get the current value of the audit preselection mask for non-attributable events.
.Fa Data
should point to an
.Fa au_mask_t .
The field
.Fa am_success
specifies which classes of successful audit events are to be logged to the
audit trail. The field
.Fa am_failure
specifies which classes of failed audit events are to be logged. The value of
both fields is the bitwise OR'ing of the event classes specified in
.Fa bsm/audit.h .
The various audit classes are described more fully in
.Xr audit_class 5 .
.It A_SETKMASK
Set the current value of the audit preselection mask for non-attributable events.
.Fa Data
should point to an
.Fa au_mask_t .
The masks are defined as described in A_GETKMASK.
.It A_GETQCTRL
Get the current settings for the audit queue (specifying in kernel buffer size, 
percentage of free filesystem blocks, and limits to the number of audit records
allowed).
.Fa Data
should point to an
.Fa au_qctrl_t .
.It A_SETQCTRL
Set the current settings for the audit queue.
.Fa Data
should point to an
.Fa au_qctrl_t .
.\" The following are not yet implemented, but as mentioned in the header file.
.\" .It A_GETCWD
.\" .It A_GETCAR
.\" .It A_GETSTAT
.\" .It A_SETSTAT
.\" .It A_SETUMASK
.\" .It A_SETSMASK
.It A_GETCOND
Gets the current condition of the auditing subsystem. If the value is
AUC_AUDITING, then the audit implementation is currently running. If the 
value is AUC_NOAUDIT then the audit implementation is currently turned off.
.Fa Data
should point to a long.
.It A_SETCOND
Sets the condition of the auditing subsystem. If AUC_NOAUDIT is set, then
auditing is temporarily suspended. If AUC_AUDITING is set, auditing is resumed.
If AUC_DISABLED is set, the auditing system will shutdown, draining all audit
records and closing out the audit trail file. 
To re-enable auditing, a call to
.Fa auditctl
is required in addition to setting the condition to AUC_AUDITING. 
.Fa Data
should point to a long.
.It A_GETCLASS
Returns the audit class for the specified audit event. 
.Fa Data
should point to a 
.Fa au_evclassmap_t .
.It A_SETCLASS
Sets the audit class for the specified audit event. 
.Fa Data
should point to a 
.Fa au_evclassmap_t .
.It A_GETPINFO
Returns the audit information stored in the credential for the current process.
.Fa Data
should point to a 
.Fa auditpinfo_t .
.It A_SETPMASK
Sets the audit settings for a process. The audit user ID, preselection masks 
for both success and failure, and terminal IDs must be set.
.Fa Data
should point to a 
.Fa auditpinfo_t 
struct.
.It A_SETFSIZE
Set the limit on audit trail file size. File size is in bytes. The file size 
specified is treated as an advisory limit. The system will make a best effort
attempt to rotate log files before they exceed the requested maximum size, but
makes no guarantees on log file size
.Fa Data
should point to a 
.Fa au_fstat_t 
struct. The
.Fa af_filesz
field is used to specify the new file size, which must be greater than
MIN_AUDIT_FILE_SIZE. A value of 0 indicates no limit on the audit trail's size. The 
.Fa af_currsz
field is ignored. A errno value of EINVAL indicates a maximum file size that is
too small.
.It A_GETFSIZE
Return the maximum allowable size of the audit trail, and the current size of 
the audit trail.
.Fa Data
should point to a
.Fa au_fstat_t
struct. 
.It A_GETPINFO_ADDR
Not implemented, returns ENOSYS.
.It A_GETKAUDIT
Not implemented, returns ENOSYS.
.It A_SETKAUDIT
Not implemented, returns ENOSYS.
.El
.Sh RETURN VALUES
Upon successful completion a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Bl -tag -width Er
Errors are specific to the operation requested. In addition, rhe
.Fn auditon
system call will fail if:
.\" ===========
.It Bq Er EINVAL
.Fa Length
is less than or equal to zero, or if it is greater than any of the expected structures.
.El
.Sh SEE ALSO
.Xr audit 2 ,
.Xr auditctl 2 ,
.Xr getauid 2 ,
.Xr setauid 2 ,
.Xr getaudit 2 ,
.Xr setaudit 2 ,
.Xr getaudit_addr 2 ,
.Xr setaudit_addr 2 ,
.Xr audit_class 5
.Sh HISTORY
The
.Fn auditon
function call first appeared in Mac OS X 10.3 (Panther).