X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/2d21ac55c334faf3a56e5634905ed6987fc787d4..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/auditon.2 diff --git a/bsd/man/man2/auditon.2 b/bsd/man/man2/auditon.2 index bfd9bad2e..4d551ba7a 100644 --- a/bsd/man/man2/auditon.2 +++ b/bsd/man/man2/auditon.2 @@ -1,5 +1,5 @@ .\" -.\" Copyright (c) 2007 Apple Inc. All rights reserved. +.\" Copyright (c) 2008-2009 Apple Inc. All rights reserved. .\" .\" @APPLE_LICENSE_HEADER_START@ .\" @@ -20,176 +20,495 @@ .\" .\" @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 +.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 .