Tribblix: manual page: auditon.2

AUDITON(2) System Calls AUDITON(2)

NAME

auditon - manipulate auditing

SYNOPSIS

cc [ flag... ] file... -lbsm -lsocket -lnsl [ library... ]
#include <sys/param.h>
#include <bsm/libbsm.h>

int auditon(int cmd, caddr_t data, int length);

DESCRIPTION

The auditon() function performs various audit subsystem control
operations. The cmd argument designates the particular audit control
command. The data argument is a pointer to command-specific data. The
length argument is the length in bytes of the command-specific data.

The following commands are supported:

A_GETCOND

Return the system audit condition in the integer pointed to by
data. The following values can be returned:

AUC_AUDITING
Audit daemon is active.

AUC_INIT_AUDIT
Audit is ready but auditd has not run.

AUC_NOAUDIT
Audit daemon is not active.

AUC_NOSPACE
Auditing has blocked due to lack of space in
audit partition.

A_SETCOND

Set the system's audit on/off condition to the value in the
integer pointed to by data. The following audit states can be
set:

AUC_AUDITING
Turns on audit record generation.

AUC_NOAUDIT
Turns off audit record generation.

A_GETCLASS

Return the event to class mapping for the designated audit event.
The data argument points to the au_evclass_map structure
containing the event number. The preselection class mask is
returned in the same structure.

A_SETCLASS

Set the event class preselection mask for the designated audit
event. The data argument points to the au_evclass_map structure
containing the event number and class mask.

A_GETKMASK

Return the kernel preselection mask in the au_mask structure
pointed to by data. This is the mask used to preselect non-
attributable audit events.

A_SETKMASK

Set the kernel preselection mask. The data argument points to the
au_mask structure containing the class mask. This is the mask
used to preselect non-attributable audit events.

A_GETPINFO

Return the audit ID, preselection mask, terminal ID and audit
session ID of the specified process in the auditpinfo structure
pointed to by data.

Note that A_GETPINFO can fail if the terminal ID contains a
network address longer than 32 bits. In this case, the
A_GETPINFO_ADDR command should be used.

A_GETPINFO_ADDR

Returns the audit ID, preselection mask, terminal ID and audit
session ID of the specified process in the auditpinfo_addr
structure pointed to by data.

A_SETPMASK

Set the preselection mask of the specified process. The data
argument points to the auditpinfo structure containing the
process ID and the preselection mask. The other fields of the
structure are ignored and should be set to NULL.

A_SETUMASK

Set the preselection mask for all processes with the specified
audit ID. The data argument points to the auditinfo structure
containing the audit ID and the preselection mask. The other
fields of the structure are ignored and should be set to NULL.

A_SETSMASK

Set the preselection mask for all processes with the specified
audit session ID. The data argument points to the auditinfo
structure containing the audit session ID and the preselection
mask. The other fields of the structure are ignored and should be
set to NULL.

A_GETQCTRL

Return the kernel audit queue control parameters. These control
the high and low water marks of the number of audit records
allowed in the audit queue. The high water mark is the maximum
allowed number of undelivered audit records. The low water mark
determines when threads blocked on the queue are wakened.
Another parameter controls the size of the data buffer used to
write data to the audit trail. There is also a parameter that
specifies a maximum delay before data is attempted to be written
to the audit trail. The audit queue parameters are returned in
the au_qctrl structure pointed to by data.

A_SETQCTRL

Set the kernel audit queue control parameters as described above
in the A_GETQCTRL command. The data argument points to the
au_qctrl structure containing the audit queue control parameters.
The default and maximum values 'A/B' for the audit queue control
parameters are:

high water
100/10000 (audit records)

low water
10/1024 (audit records)

output buffer size
1024/1048576 (bytes)

delay
20/20000 (hundredths second)

A_GETCWD

Return the current working directory as kept by the audit
subsystem. This is a path anchored on the real root, rather than
on the active root. The data argument points to a buffer into
which the path is copied. The length argument is the length of
the buffer.

A_GETCAR

Return the current active root as kept by the audit subsystem.
This path can be used to anchor an absolute path for a path token
generated by an application. The data argument points to a
buffer into which the path is copied. The length argument is the
length of the buffer.

A_GETSTAT

Return the system audit statistics in the audit_stat structure
pointed to by data.

A_SETSTAT

Reset system audit statistics values. The kernel statistics value
is reset if the corresponding field in the statistics structure
pointed to by the data argument is CLEAR_VAL. Otherwise, the
value is not changed.

A_GETPOLICY

Return the audit policy flags in the integer pointed to by data.

A_SETPOLICY

Set the audit policy flags to the values in the integer pointed
to by data. The following policy flags are recognized:

AUDIT_CNT

Do not suspend processes when audit storage is full or
inaccessible. The default action is to suspend processes
until storage becomes available.

AUDIT_AHLT

Halt the machine when a non-attributable audit record can not
be delivered. The default action is to count the number of
events that could not be recorded.

AUDIT_ARGV

Include in the audit record the argument list for a member of
the exec(2) family of functions. The default action is not to
include this information.

AUDIT_ARGE

Include the environment variables for the execv(2) function
in the audit record. The default action is not to include
this information.

AUDIT_SEQ

Add a sequence token to each audit record. The default action
is not to include it.

AUDIT_TRAIL

Append a trailer token to each audit record. The default
action is not to include it.

AUDIT_GROUP

Include the supplementary groups list in audit records. The
default action is not to include it.

AUDIT_PATH

Include secondary paths in audit records. Examples of
secondary paths are dynamically loaded shared library modules
and the command shell path for executable scripts. The
default action is to include only the primary path from the
system call.

AUDIT_WINDATA_DOWN

Include in an audit record any downgraded data moved between
windows. This policy is available only if the system is
configured with Trusted Extensions. By default, this
information is not included.

AUDIT_WINDATA_UP

Include in an audit record any upgraded data moved between
windows. This policy is available only if the system is
configured with Trusted Extensions. By default, this
information is not included.

AUDIT_PERZONE

Enable auditing for each local zone. If not set, audit
records from all zones are collected in a single log
accessible in the global zone and certain auditconfig(8)
operations are disallowed. This policy can be set only from
the global zone.

AUDIT_ZONENAME

Generate a zone ID token with each audit record.

RETURN VALUES

Upon successful completion, auditon() returns 0. Otherwise, -1 is
returned and errno is set to indicate the error.

ERRORS

The auditon() function will fail if:

E2BIG
The length field for the command was too small to hold the
returned value.

EFAULT
The copy of data to/from the kernel failed.

EINVAL
One of the arguments was illegal, Audit has not been
installed, or the operation is not valid from a local zone.

EPERM
The {PRIV_SYS_AUDIT} privilege is not asserted in the
effective set of the calling process.

Neither the {PRIV_PROC_AUDIT} nor the {PRIV_SYS_AUDIT}
privilege is asserted in the effective set of the calling
process and the command is one of A_GETCAR, A_GETCLASS,
A_GETCOND, A_GETCWD, A_GETPINFO, A_GETPOLICY.

USAGE

The auditon() function can be invoked only by processes with
appropriate privileges.

The use of auditon() to change system audit state is permitted only
in the global zone. From any other zone auditon() returns -1 with
errno set to EPERM. The following auditon() commands are permitted
only in the global zone: A_SETCOND, A_SETCLASS, A_SETKMASK,
A_SETQCTRL, A_SETSTAT, A_SETFSIZE, and A_SETPOLICY. All other
auditon() commands are valid from any zone.

ATTRIBUTES

NOTES

The auditon options that modify or display process-based information
are not affected by the "perzone" audit policy. Those that modify
system audit data such as the terminal ID and audit queue parameters
are valid only in the global zone unless the "perzone" policy is set.
The "get" options for system audit data reflect the local zone if
"perzone" is set; otherwise they reflects the settings of the global
zone.

March 6, 2017 AUDITON(2)