audit Subroutine

Edit online

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 subroutine, or through the /dev/audit special file interface.

Parameters

Table 1. Parameters
Item Description
Command Defined in the sys/audit.h file, can be one of the following values:
AUDIT_QUERY
Returns a mask that indicates 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. The failure-mode behavior changes if auditing is already enabled. The Argument parameter specifies recovery behavior if there is failure and can be either 0 or the value of 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 are buffered until a total of Argument records are saved, when the audit event records are flushed to disk. An Argument value of zero disables this function.
AUDIT_BYTE_THRESHOLD
Audit event data is buffered until a total of Argument bytes of data is saved, when the audit event data is flushed to disk. An Argument value of zero disables this function.
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 Argument parameter can take the following values:
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 captures the full path name for FILE_Open, FILE_Openxat, FILE_Read, FILE_Write, FILE_Link, FILE_Linkat, FILE_Unlink, FILE_Unlinkat, FILE_Rename, FILE_Renameat, FILE_Owner, FILE_Mode, FILE_Fchmod, FILE_Fchmodat, FILE_Fchown, FILE_Fchownat, FILE_Truncate, FILE_Symlink, FILE_Symlinkat, FILE_Setea, FILE_Removeea, FILE_Utimes, FS_Chroot, FILE_Mknod, FILE_Mknodat, FILE_Acl, FILE_Facl, FILE_Chpriv, FILE_Fchpriv, FILE_WriteXacl, FILE_Revoke, FILE_Frevoke, PROC_Execute, and PROC_LPExecute auditing events.
BufferSize
The number of bytes or audit event records that are buffered. This parameter is valid only with the command AUDIT_BYTE_THRESHOLD and AUDIT_EVENT_THRESHOLD. A value of zero disables either byte (for AUDIT_BYTE_THRESHOLD) or event (for AUDIT_EVENT_THRESHOLD) buffering.
start of changeAUDIT_SET_DEFAULT_USER_CLASSend of change
start of changeSets the default audit classes of the user based on the classes that are defined within the kernel. The AUDIT_SET_DEFAULT_USER_CLASS parameter overrides the user stanza values in the /etc/security/audit/config file.end of change
start of changeAUDIT_ENABLE_ALL_TCPK_EVENTSend of change
start of changeEnables the operating system to capture the TCP/IP auditing events by default even when the corresponding socket descriptor is created before the auditing is enabled. The TCP/IP audit events covered as part of this argument are TCP_kbind, TCP_klisten, TCP_kaccept, TCP_kconnect, TCP_ksend, TCP_kreceive, TCP_kshutdown, TCP_ksetopt, and TCP_kclose.end of change

Return Values

For a Command value of AUDIT_QUERY, the audit subroutine returns, upon successful completion, a mask that indicates 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 any of the following error codes are true:

Table 2. Error codes
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

Table 3. Files
Item Description
dev/audit Specifies the audit pseudo-device from which the audit records are read.