auditctl(2)

auditctl -- get or set the status of auditing

Synopsis

   #include <sys/types.h>
   #include <audit.h>
   
   int auditctl(int cmd, struct actl *actlp, int size);

Description

The auditctl system call fills the appropriate audit control structures or reports the status of auditing, depending on the values of cmd. Three values of cmd are supported: AUDITON, AUDITOFF, and ASTATUS.

When the specified cmd is AUDITON, the auditctl system call performs the following actions:

It copies in the offset in seconds from Greenwich Mean Time (GMT).
It initializes the vnode for the primary audit log file.
It initializes the audit buffer and log control structures.
It exempts system resident processes and /sbin/init from auditing.
It writes a machine-specific header record.
It sets the auditon flag to 1.

When the specified cmd is AUDITOFF, the auditctl system call sets the auditon field to zero; frees all process audit structures; and locks, flushes, and releases the audit buffers.

When the specified cmd is ASTATUS, the auditctl system call returns the current status of auditing. A zero value for auditon in the actl structure indicates that auditing is disabled, and a value of one indicates that auditing is enabled.

The actlp argument points to a structure of type actl that contains the following elements:

   struct actl {
       int auditon;                /* audit status variable */
       char version[ADT_VERLEN];   /* audit version         */
       long gmtsecoff;             /* UTC offset in seconds */
   }

The size argument is used to verify the size of the actl structure being passed to determine the version of auditing.

Auditing must be installed on the system for this system call to be used. The use of the auditctl system call requires the appropriate privilege(P_AUDIT).

Return values

On success, auditctl returns 0. On failure, auditctl returns -1 and sets errno to identify the error.

Errors

In the following conditions, auditctl fails and sets errno to:

EEXIST: All the possible log files exist when attempting to enable auditing.
EFAULT: The cmd is AUDITON and the actlp argument is invalid.
EFAULT: The cmd is ASTATUS and the actlp argument is invalid.
EINVAL: The size of actl is not equal to size.
EINVAL: An attempt was made to disable auditing while it was already disabled.
EINVAL: An attempt was made to enable auditing while it was already enabled.
EINVAL: The cmd is invalid.
EINVAL: The cmd is AUDITON and it is not possible to initialize the audit buffers.
EINVAL: The cmd is AUDITOFF and it is not possible to lock the audit buffers, because auditing is already disabled.
ENOENT: It is not possible to access the primary event log path.
EPERM: The invoking subject does not have the appropriate privilege(P_AUDIT).
EROFS: The primary audit log file resides within a file system that is mounted read-only.
EIO: An I/O error occurred while performing a write to the audit log file.
ENOPKG: The audit package is not installed.

References

auditbuf(2), auditdmp(2), auditevt(2), auditlog(2)