NAME

au_ctl − controls security auditing

SYNOPSIS

#include <sys/param.h>
#include <sys/types.h>
#include <sys/audit.h>
 int au_ctl (path, cmd, thold, incr)
char ∗path;
int cmd;
long thold, incr;

DESCRIPTION

au_ctl provides the following controls for the audit system:

• Starts and stops security auditing. 

• Sets the file into which security audit events are to be recorded. 

• Sets the audit file size and growth rate limits. 

• Sets the configuration options for the logging of additional associated audit event information. 

• Queries the shutdown state (on/off), the status of auditing (on/off), and whether auditing is currently recorded to the specified file. 

• Directs the audit system as to what to do when audit records cannot be written to the audit file. 

au_ctl is intended to be called by one controlling process with effective user ID 0 (root).  The controlling process is the last process to issue a call to au_ctl.  If certain audit system states are encountered (e.g., audit file size thresholds), then the system can signal the current controlling process.  audit_d(1M) is currently the only command which issues au_ctl system calls.  audit(1M) communicates requests to audit_d which are then performed on behalf of the process executing the audit command. 

The parameters are:

path The name of a file for recording audit events.  This file must exist prior to being specified to au_ctl. 

cmd A command to query or control the audit system.  The available commands are listed below

thold The number of disk blocks the audit file is permitted to grow beyond its current size before signaling the controlling process.  If thold has a non-zero value when either the AU_START, AU_SWITCH, or AU_LIMITS command is specified, a SIGAUDWARN signal will be sent to the controlling process after the specified number of blocks are written to the specified audit file.  If thold has a zero value when either the AU_START, AU_SWITCH, or AU_LIMITS command is specified, the audit system will set the value of thold equal to incr.  Once thold blocks have been written to the audit file, the system will signal the controlling process if that process exists.  Otherwise, the system will print the message, "No controlling process and the disk block usage threshold exceeded" on the system console.  If the AU_SHUTDOWN command was specified, the thold argument is the new shutdown setting (AU_ON or AU_OFF).  Refer to the section describing AU_SHUTDOWN for more specific information.  If the AU_REC_PASSWD command is specified, the thold argument will be the new event recording configuration setting (AU_ON or AU_OFF).  Refer to the sections describing AU_REC_PASSWD for more specific information. 

incr The increment value is the number of disk blocks beyond the threshold thold of disk blocks.  If incr has a non-zero value when either the AU_START, AU_SWITCH, or AU_LIMITS command is specified, a SIGAUDWARN signal will be sent to the controlling process each time incr additional blocks are written to the specified file.  If incr has a zero value, no additional signals will be sent to the same process. 

The parameters thold, incr and path may be ignored depending on which cmd is specified.  For example, AU_STOP ignores thold, incr and path. 

If the audit system is enabled and unable to record an audit event, the audit system will go into an audit panic state and a SIGAUDPANIC signal is sent to the controlling process.  Refer to the AU_SHUTDOWN command for more information about the audit panic state. 

The following commands may be specified in cmd:

AU_START If auditing is currently disabled, auditing is enabled and audit events are appended to an existing file path.  AU_START may also be issued to clear an audit panic state and to allow auditing to continue to the specified audit file.  thold additional blocks may be written to the specified audit file before a signal is sent to the controlling process.  Subsequently, an additional signal shall be sent for each incr blocks written. 

AU_SWITCH If auditing is currently enabled, the current audit file is closed and audit events are appended to an existing file path.  AU_SWITCH may also be issued to clear an audit panic state and to allow auditing to continue to the specified audit file.  thold additional blocks may be written to the specified audit file before a signal will be sent to the controlling process.  Subsequently, an additional signal shall be sent for each incr blocks written. 

AU_STOP The current auditing file is closed and auditing stops.  The path, thold, and incr arguments are ignored.  AU_STOP may also be issued to clear an audit panic state and to stop auditing. 

AU_ISPATH This command determines the status of auditing.  If auditing is enabled on the file named by path, the system call will return successfully.  Otherwise, one of the errors listed below will be returned.  The thold and incr arguments are ignored. 

AU_STAT This command determines the status of auditing.  If auditing is enabled, the call will return successfully.  If auditing is not enabled, one of the errors below will be returned.  The path, thold, and incr arguments are ignored. 

AU_LIMITS This command sets new threshhold and increment values while auditing is enabled.  The argument path is ignored. 

AU_CLOSE This command causes the kernel to close the currently selected audit file without clearing the audit panic state.  This command is valid only when the audit system is in an audit panic state.  Processes may be blocked waiting to write to the audit file while the audit system is in the audit panic state.  An AU_START, AU_SWITCH or AU_STOP cmd can be issued to clear the audit panic state. 

AU_REC_PASSWD
This command tells the audit system what to do with passwords when a password check fails. Specifying thold with a value of AU_ON causes bad passwords to be written into the audit trail as additional associated audit event information.  Specifying thold with a value of AU_OFF causes audit events concerning failed passwords to be written without including the passwords.  Specifying thold with a value of AU_QUERY directs the audit system to return the current configuration state.  The configuration state will not be modified. 

AU_SHUTDOWN
This command tells the audit system what to do when auditing is on, the audit system cannot record audit events, and the system cannot signal the controlling process. When the audit system is in an audit panic state (i.e., the audit system cannot record audit events in the specified audit file), the audit system will perform the following procedures in order:

1.  Try to signal the controlling process.  If that process fails to clear the audit panic state within 30 seconds, the system will shutdown if the AU_ON state was previously specified or will halt auditing (as if an AU_STOP had been issued) if the AU_OFF option was specified. 

2.  If the controlling process no longer exists, the system will shutdown if the AU_ON state was previously specified. 

3.  If neither of the above conditions were exercised, the audit system will stop recording audit events.  The default action is to shutdown the system. 

  Specifying thold with a value of AU_ON directs the audit system to shutdown the entire system if the audit system can no longer record audit events, as if a shutdown(1M) were performed.  Specifying a thold value of AU_OFF directs the audit system to allow the system to continue but turn off auditing.  This is the equivalent of issuing an AU_STOP command.  au_ctl will return the old value of the shutdown state (either AU_ON or AU_OFF) as a return value.  Specifying thold with a value of AU_QUERY directs the audit system to return the current shutdown state.  The shutdown state will not be modified. 

The system call will fail if any of the following are true:

[ENOTDIR] The cmd is AU_START, AU_SWITCH, or AU_ISPATH, and a component of the path prefix is not a directory. 

[ENOENT] The cmd is AU_START, AU_SWITCH, or AU_ISPATH, and a component of the path prefix or the file specified by path does not exist. 

[EACCES] The cmd is AU_START, AU_SWITCH, or AU_ISPATH, and search access permission is denied for any component of the pathname. 

[EISDIR] The cmd is AU_START or AU_SWITCH and the named file is a directory. 

[EPERM] The controlling process is not privileged. 

[EINVAL] The cmd is AU_START or AU_SWITCH and path is a device special file on which auditing is not supported. 

[EROFS] The cmd is AU_START or AU_SWITCH and the named file resides on a read-only file system. 

[EINVAL] The cmd is AU_START and auditing is already enabled, or cmd is AU_SWITCH or AU_STOP and auditing is disabled, and the kernel is not in an audit panic state. 

[EINVAL] The cmd is AU_STAT or AU_LIMITS and auditing is disabled. 

[ENOENT] The cmd is AU_ISPATH and auditing is enabled but not for the file named by path. 

[EINVAL] The cmd is AU_ISPATH and auditing is not enabled. 

[EFAULT] path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the system call. 

[EIO] An I/O error has occurred while accessing the file system. 

[EINVAL] path contains a component with the high-order bit set. 

[ENOENT] Pathname length is greater than the maximum allowed. 

[EINVAL] The cmd is AU_START, AU_SWITCH, or AU_LIMITS, and thold or incr is negative. 

[EINVAL] The cmd is AU_CLOSE and the kernel is not in an audit panic state. 

[ENAMETOOLONG]
A component of path exceeded 255 characters, or an entire pathname exceeded 1023 characters. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

DIAGNOSTICS

Upon successful completion, a value of 0 is returned for all cmds except for AU_SHUTDOWN, and AU_REC_PASSWD.  All unsuccessful completions return a value of −1 and errno is set to indicate the error. 

SEE ALSO

audit(1M), audit_d(1M), shutdown(1M)

BUGS

If multiple processes issue au_ctl calls, unpredictable behavior may result. 

(Security Enhancement)