.\"
-.\" Copyright (c) 2007 Apple Inc. All rights reserved.
+.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\"
.\"
.\" @APPLE_LICENSE_HEADER_END@
.\"
-.Dd July 30, 2007
+.Dd January 29, 2009
.Dt AUDITON 2
-.Os Darwin
+.Os
.Sh NAME
.Nm auditon
-.Nd configure the current audit parameters on the system
+.Nd "configure system audit parameters"
.Sh SYNOPSIS
-.Fd #include <bsm/audit.h>
+.In bsm/audit.h
.Ft int
-.Fn auditon "int cmd" "void * data" "int length"
+.Fn auditon "int cmd" "void *data" "u_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 .
+system call is used to manipulate various audit control operations.
+The
+.Fa data
+argument
+should point to a structure whose type depends on the command.
+The
+.Fa length
+argument
+specifies the size of
+.Fa *data
+in bytes.
+The
+.Fa cmd
+argument
+may be any of the following:
+.Bl -tag -width ".It Dv A_GETPINFO_ADDR"
+.It Dv A_SETPOLICY
+Set audit policy flags.
+The
+.Fa data
+argument
+must point to a
+.Vt int
+value set to one or more the following audit
+policy control values bitwise OR'ed together:
+.Dv AUDIT_CNT ,
+.Dv AUDIT_AHLT ,
+.Dv AUDIT_ARGV ,
+and
+.Dv AUDIT_ARGE .
+If
+.Dv AUDIT_CNT is set, the system will continue even if it becomes low
+on space and discontinue logging events until the low space condition is
+remedied.
+If it is not set, audited events will block until the low space
+condition is remedied.
+Unaudited events, however, are unaffected.
+If
+.Dv AUDIT_AHLT is set, a
+.Xr panic 9
+if it cannot write an event to the global audit log file.
+If
+.Dv AUDIT_ARGV
+is set, then the argument list passed to the
+.Xr execve 2
+system call will be audited. If
+.Dv AUDIT_ARGE
+is set, then the environment variables passed to the
+.Xr execve 2
+system call will be audited. The default policy is none of the audit policy
+control flags set.
+.It Dv A_SETKAUDIT
+Set the host information.
+The
+.Fa data
+argument
+must point to a
+.Vt auditinfo_addr_t
+structure containing the host IP address information.
+After setting, audit records
+that are created as a result of kernel events will contain
+this information.
+.It Dv A_SETKMASK
+Set the kernel preselection masks (success and failure).
+The
+.Fa data
+argument
+must point to a
+.Vt au_mask_t
+structure containing the mask values as defined in
+.In bsm/audit.h .
+These masks are used for non-attributable audit event preselection.
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
+both fields is the bitwise OR'ing of the audit 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.
+.It Dv A_SETQCTRL
+Set kernel audit queue parameters.
+The
+.Fa data
+argument
+must point to a
+.Vt au_qctrl_t
+structure (defined in
+.In bsm/audit.h )
+containing the kernel audit queue control settings:
+.Fa aq_hiwater ,
+.Fa aq_lowater ,
+.Fa aq_bufsz ,
+.Fa aq_delay ,
+and
+.Fa aq_minfree .
+The field
+.Fa aq_hiwater
+defines the maximum number of audit record entries in the queue used to store
+the audit records ready for delivery to disk.
+New records are inserted at the tail of the queue and removed from the head.
+For new records which would exceed the
+high water mark, the calling thread is inserted into the wait queue, waiting
+for the audit queue to have enough space available as defined with the field
+.Fa aq_lowater .
+The field
+.Fa aq_bufsz
+defines the maximum length of the audit record that can be supplied with
+.Xr audit 2 .
+The field
+.Fa aq_delay
+is unused.
+The field
+.Fa aq_minfree
+specifies the minimum amount of free blocks on the disk device used to store
+audit records.
+If the value of free blocks falls below the configured
+minimum amount, the kernel informs the audit daemon about low disk space.
+The value is to be specified in percent of free file system blocks.
+A value of 0 results in a disabling of the check.
+The default and maximum values (default/maximum) for the
+audit queue control parameters are:
+.Pp
+.Bl -column aq_hiwater -offset indent -compact
+.It aq_hiwater Ta 100/10000 (audit records)
+.It aq_lowater Ta 10/aq_hiwater (audit records)
+.It aq_bufsz Ta 32767/1048576 (bytes)
+.It aq_delay Ta (Not currently used.)
+.El
+.It Dv A_SETSTAT
+Return
+.Er ENOSYS .
+(Not implemented.)
+.It Dv A_SETUMASK
+Return
+.Er ENOSYS .
+(Not implemented.)
+.It Dv A_SETSMASK
+Return
+.Er ENOSYS .
+(Not implemented.)
+.It Dv A_SETCOND
+Set the current auditing condition.
+The
+.Fa data
+argument
+must point to a
+.Vt int
+value containing the new
+audit condition, one of
+.Dv AUC_AUDITING ,
+.Dv AUC_NOAUDIT ,
+or
+.Dv AUC_DISABLED .
+If
+.Dv AUC_NOAUDIT
+is set, then auditing is temporarily suspended. If
+.Dv AUC_AUDITING
+is set, auditing is resumed. If
+.Dv AUC_DISABLED
+is set, the auditing system will
+shutdown, draining all audit records and closing out the audit trail file.
+.It Dv A_SETCLASS
+Set the event class preselection mask for an audit event.
+The
+.Fa data
+argument
+must point to a
+.Vt au_evclass_map_t
+structure containing the audit event and mask.
+The field
+.Fa ec_number
+is the audit event and
+.Fa ec_class
+is the audit class mask. See
+.Xr audit_event 5
+for more information on audit event to class mapping.
+.It Dv A_SETPMASK
+Set the preselection masks for a process.
+The
+.Fa data
+argument
+must point to a
+.Vt auditpinfo_t
+structure that contains the given process's audit
+preselection masks for both success and failure.
+The field
+.Fa ap_pid
+is the process id of the target process.
+The field
+.Fa ap_mask
+must point to a
+.Fa au_mask_t
+structure which holds the preselection masks as described in the
+.Da A_SETKMASK
+section above.
+.It Dv A_SETFSIZE
+Set the maximum size of the audit log file.
+The
+.Fa data
+argument
+must point to a
+.Vt au_fstat_t
+structure with the
+.Va af_filesz
+field set to the maximum audit log file size.
+A value of 0
+indicates no limit to the size.
+.It Dv A_SETSFLAGS
+Set the audit sessions flags for the current session.
+The
+.Fa data
+argument must point to an
+.Vt au_asflgs_t
+value containing the new audit session flags.
+Audit session flags may be updated only according to local
+access control policy.
+.It Dv A_GETCLASS
+Return the event to class mapping for the designated audit event.
+The
+.Fa data
+argument
+must point to a
+.Vt au_evclass_map_t
+structure. See the
+.Dv A_SETCLASS
+section above for more information.
+.It Dv A_GETKAUDIT
+Get the current host information.
+The
+.Fa data
+argument
+must point to a
+.Vt auditinfo_addr_t
+structure.
+.It Dv A_GETPINFO
+Return the audit settings for a process.
+The
+.Fa data
+argument
+must point to a
+.Vt auditpinfo_t
+structure which will be set to contain
+.Fa ap_auid
+(the audit ID),
+.Fa ap_mask
+(the preselection mask),
+.Fa ap_termid
+(the terminal ID), and
+.Fa ap_asid
+(the audit session ID)
+of the given target process.
+The process ID of the target process is passed
+into the kernel using the
+.Fa ap_pid
+field.
+See the section
+.Dv A_SETPMASK
+above and
+.Xr getaudit 2
+for more information.
+.It Dv A_GETPINFO_ADDR
+Return the extended audit settings for a process.
+The
+.Fa data
+argument
+must point to a
+.Vt auditpinfo_addr_t
+structure which is similar to the
+.Vt auditpinfo_addr_t
+structure described above.
+The exception is the
+.Fa ap_termid
+(the terminal ID) field which points to a
+.Vt au_tid_addr_t
+structure can hold much a larger terminal address and an address type.
+The process ID of the target process is passed into the kernel using the
+.Fa ap_pid
+field.
+See the section
+.Dv A_SETPMASK
+above and
+.Xr getaudit 2
+for more information.
+.It Dv A_GETSINFO_ADDR
+Return the extended audit settings for a session.
+The
+.Fa data
+argument
+must point to a
+.Vt auditinfo_addr_t
+structure.
+The audit session ID of the target session is passed
+into the kernel using the
+.Fa ai_asid
+field. See
+.Xr getaudit_addr 2
+for more information about the
+.Vt auditinfo_addr_t
+structure.
+.It Dv A_GETKMASK
+Return the current kernel preselection masks.
+The
+.Fa data
+argument
+must point to a
+.Vt au_mask_t
+structure which will be set to
+the current kernel preselection masks for non-attributable events.
+.It Dv A_GETPOLICY
+Return the current audit policy setting.
+The
+.Fa data
+argument
+must point to a
+.Vt int
+value which will be set to
+one of the current audit policy flags.
+The audit policy flags are
+described in the
+.Dv A_SETPOLICY
+section above.
+.It Dv A_GETQCTRL
+Return the current kernel audit queue control parameters.
+The
+.Fa data
+argument
+must point to a
+.Vt au_qctrl_t
+structure which will be set to the current
+kernel audit queue control parameters.
+See the
+.Dv A_SETQCTL
+section above for more information.
+.It Dv A_GETFSIZE
+Returns the maximum size of the audit log file.
+The
+.Fa data
+argument
+must point to a
+.Vt au_fstat_t
+structure.
+The
+.Va af_filesz
+field will be set to the maximum audit log file size.
+A value of 0 indicates no limit to the size.
+The
+.Va af_currsz
+field
+will be set to the current audit log file size.
+.It Dv A_GETSFLAGS
+Returns the audit session flags for the current session.
+The
+.Fa data
+argument must point to an
+.Vt au_asflgs_t
+value which will be set with the current session flags.
+.It Dv A_GETCWD
+.\" [COMMENTED OUT]: Valid description, not yet implemented.
+.\" Return the current working directory as stored in the audit subsystem.
+Return
+.Er ENOSYS .
+(Not implemented.)
+.It Dv A_GETCAR
+.\" [COMMENTED OUT]: Valid description, not yet implemented.
+.\"Stores and returns the current active root as stored in the audit
+.\"subsystem.
+Return
+.Er ENOSYS .
+(Not implemented.)
+.It Dv A_GETSTAT
+.\" [COMMENTED OUT]: Valid description, not yet implemented.
+.\"Return the statistics stored in the audit system.
+Return
+.Er ENOSYS .
+(Not implemented.)
+.It Dv A_GETCOND
+Return the current auditing condition.
+The
+.Fa data
+argument
+must point to a
+.Vt int
+value which will be set to
+the current audit condition, one of
+.Dv AUC_AUDITING ,
+.Dv AUC_NOAUDIT
+or
+.Dv AUC_DISABLED .
+See the
+.Dv A_SETCOND
+section above for more information.
+.It Dv A_SENDTRIGGER
+Send a trigger to the audit daemon.
+The
+.Fa data
+argument
+must point to a
+.Vt int
+value set to one of the acceptable
+trigger values:
+.Dv AUDIT_TRIGGER_LOW_SPACE
+(low disk space where the audit log resides),
+.Dv AUDIT_TRIGGER_OPEN_NEW
+(open a new audit log file),
+.Dv AUDIT_TRIGGER_READ_FILE
+(read the
+.Pa audit_control
+file),
+.Dv AUDIT_TRIGGER_CLOSE_AND_DIE
+(close the current log file and exit),
+.Dv AUDIT_TRIGGER_NO_SPACE
+(no disk space left for audit log file).
+.Dv AUDIT_TRIGGER_ROTATE_USER
+(request audit log file rotation).
+.Dv AUDIT_TRIGGER_INITIALIZE
+(initialize audit subsystem for Mac OS X only).
+or
+.Dv AUDIT_TRIGGER_EXPIRE_TRAILS
+(request audit log file expiration).
.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.
+.Rv -std
.Sh ERRORS
-.Bl -tag -width Er
-Errors are specific to the operation requested. In addition, rhe
+The
.Fn auditon
-system call will fail if:
-.\" ===========
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er ENOSYS
+Returned by options not yet implemented.
+.It Bq Er EFAULT
+A failure occurred while data transferred to or from
+the kernel failed.
.It Bq Er EINVAL
-.Fa Length
-is less than or equal to zero, or if it is greater than any of the expected structures.
+Illegal argument was passed by a system call.
+.It Bq Er EPERM
+The process does not have sufficient permission to complete
+the operation.
.El
+.Pp
+The
+.Dv A_SENDTRIGGER
+command is specific to the
+.Fx
+and Mac OS X implementations, and is not present in Solaris.
.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 getauid 2 ,
+.Xr setaudit 2 ,
.Xr setaudit_addr 2 ,
-.Xr audit_class 5
+.Xr setauid 2 ,
+.Xr libbsm 3
.Sh HISTORY
-The
-.Fn auditon
-function call first appeared in Mac OS X 10.3 (Panther).
+The OpenBSM implementation was created by McAfee Research, the security
+division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
+It was subsequently adopted by the TrustedBSD Project as the foundation for
+the OpenBSM distribution.
+.Sh AUTHORS
+.An -nosplit
+This software was created by McAfee Research, the security research division
+of McAfee, Inc., under contract to Apple Computer Inc.
+Additional authors include
+.An Wayne Salamon ,
+.An Robert Watson ,
+and SPARTA Inc.
+.Pp
+The Basic Security Module (BSM) interface to audit records and audit event
+stream format were defined by Sun Microsystems.
+.Pp
+This manual page was written by
+.An Tom Rhodes Aq trhodes@FreeBSD.org ,
+.An Robert Watson Aq rwatson@FreeBSD.org ,
+and
+.An Wayne Salamon Aq wsalamon@FreeBSD.org .
projects / apple / xnu.git / blobdiff