Purpose
Enables
and disables system auditing.
Library
Standard
C Library (libc.a)
Syntax
#include <sys/audit.h>
int audit ( Command, Argument)
int Command;
int Argument;
Description
The audit subroutine
enables or disables system auditing.
When
auditing is enabled, audit records are created for security-relevant
events. These records can be collected through the auditbin (auditbin Subroutine) subroutine, or through the /dev/audit special
file interface.
Parameters
Item |
Description |
Command |
Defined in the sys/audit.h file, can be one of the
following values: - AUDIT_QUERY
- Returns a mask indicating the state of the auditing subsystem.
The mask is a logical ORing of the AUDIT_ON, AUDIT_OFF, AUDIT_PANIC,
and AUDIT_FULLPATH flags.
- AUDIT_ON
- Enables auditing. If auditing is already enabled, only the failure-mode
behavior changes. The Argument parameter specifies recovery
behavior in the event of failure and may be either 0 or the value AUDIT_PANIC or AUDIT_FULLPATH.
Note: If AUDIT_PANIC is specified, bin-mode auditing must
be enabled before the audit subroutine call.
- AUDIT_OFF
- Disables the auditing system if auditing is enabled. If the
auditing system is disabled, the audit subroutine does nothing.
The Argument parameter is ignored.
- AUDIT_RESET
- Disables the auditing system and resets the auditing system.
If auditing is already disabled, only the system configuration is
reset. Resetting the audit configuration involves clearing the audit
events and audited objects table, and terminating bin auditing and
stream auditing.
- AUDIT_EVENT_THRESHOLD
- Audit event records will be buffered until a total of Argument records
have been saved, at which time the audit event records will be flushed
to disk. An Argument value of zero disables this functionality.
This parameter only applies to AIX® 4.1.4 and later.
- AUDIT_BYTE_THRESHOLD
- Audit event data will be buffered until a total of Argument bytes
of data have been saved, at which time the audit event data will be
flushed to disk. An Argument value of zero disables this functionality.
This parameter only applies to AIX 4.1.4 and later.
|
Argument |
Specifies the behavior when a bin write fails (for AUDIT_ON)
or specifies the size of the audit event buffer (for AUDIT_EVENT_THRESHOLD and AUDIT_BYTE_THRESHOLD).
For AUDIT_RESET and AUDIT_QUERY, the value of the Argument is
the WPAR ID. For all other commands, the value of Argument is
ignored. The valid values are: - AUDIT_PANIC
- The operating system halts abruptly if an audit record cannot
be written to a bin.
Note: If AUDIT_PANIC is specified, bin-mode
auditing must be enabled before the audit subroutine call.
- AUDIT_FULLPATH
- The operating system starts capturing full path name for the FILE_Open,
FILE_Read, FILE_Write auditing events.
- BufferSize
- The number of bytes or audit event records which will be buffered.
This parameter is valid only with the command AUDIT_BYTE_THRESHOLD and AUDIT_EVENT_THRESHOLD.
A value of zero will disable either byte (for AUDIT_BYTE_THRESHOLD)
or event (for AUDIT_EVENT_THRESHOLD) buffering.
|
Return Values
For
a Command value of AUDIT_QUERY, the audit subroutine
returns, upon successful completion, a mask indicating the state of
the auditing subsystem. The mask is a logical ORing of the AUDIT_ON, AUDIT_OFF, AUDIT_PANIC, AUDIT_NO_PANIC,
and AUDIT_FULLPATH flags. For any other Command value,
the audit subroutine returns 0 on successful completion.
If the audit subroutine fails, a value of
-1 is returned and the errno global variable is set to indicate
the error.
Error Codes
The audit subroutine
fails if either of the following is true:
Item |
Description |
EINVAL |
The Command parameter is not one of AUDIT_ON, AUDIT_OFF, AUDIT_RESET,
or AUDIT_QUERY. |
EINVAL |
The Command parameter is AUDIT_ON and the Argument parameter
specifies values other than AUDIT_PANIC or AUDIT_FULLPATH. |
EPERM |
The calling process does not have root user authority. |
Files
Item |
Description |
dev/audit |
Specifies the audit pseudo-device from which the audit records
are read. |