dg_auditctl(2) DG/UX B2 Security R4.12MU02 dg_auditctl(2)
NAME
dgauditctl - configure and control system auditing
SYNOPSIS
#include <sys/audit.h>
int dgauditctl (int command, int argument, int sizearg);
where:
command One of the audit control commands listed below.
argument Additional information needed by the command. The type of
argument depends upon the command, but it is generally an
integer or a pointer to a command-specific data structure.
sizearg The size of the object given by argument when its size is
not fixed. sizearg is usually an integer variable
containing the byte size of the object given by argument.
DESCRIPTION
The dgauditctl system call queries or changes the current audit
state.
When the caller does not have appropriate privilege, dgauditctl
fails and sets errno to EPERM. When command is not one of those
listed below, errno is set to EINVAL.
Audit Control Commands
The following describes the dgauditctl commands and the error codes
returned by each:
AUDSTART Turn auditing on and write an audit trail header record.
When auditing is on, audit records are created for
auditable events (as determined by the effective audit
mask of each process), and are written to the current
audit trail file.
When argument is NULL the current trail file is used.
The current trail file is the one in use when auditing
was last stopped unless changed by the AUDSETTRAILSPEC
command (see below).
When argument is not NULL, it must be a pointer to a
structure of type audtrailspect. If the specified
file can be successfully opened, its MAC label will be
set to the current audit MAC label (as defined by the
AUDSETTRAILMACLABEL command described below,
ADMINAUDITDATA being the default value), and it will
replace the current trail file prior to starting
auditing.
The size of the audtrailspect structure pointed to by
argument is given by sizearg.
The trail specification (audtrailspect) contains the
following members:
uint maxkbytes;
timet endtime;
booleant recycle;
booleant truncate;
sizet actualtrailspecsize;
char filename [];
The entries maxkbytes, endtime and recycle are currently
not supported but should all be set to zero. When
truncate is set to BTRUE the trail file (if it exists)
is opened and truncated, otherwise it is opened and
appended to. The actualtrailspecsize is the size [in
bytes] of this structure, including the pathname string
(including the terminating NULL). The pathname of the
trail file, given by filename, must begin at the
system's root filesystem (/).
On failure, errno is set to one of the following values:
EINVAL Auditing is already started.
EINVAL sizearg does not match the size field in
trail-specification pointed to by argument.
EINVAL A current trail specification does not
exist and argument is NULL.
EINVAL The trail pathname does not begin with /.
ENOMEM Unable to allocate enough memory to
complete the request.
EFAULT The caller does not have read access to one
or more bytes of the block of memory
specified by argument and sizearg.
EACCES filename is a directory or an unsupported
file type.
ENOSPC Insufficient contiguous space to create a
file entry or inode.
ENOENT A non-terminal component of the pathname
does not exist.
ENOTDIR A non-terminal component of the pathname
was not a directory.
ENAMETOOLONG The pathname exceeds the length limit for
pathnames or a component of the pathname
exceeds the length limit for filenames.
EPERM The pathname contains a character not in
the allowed character set.
AUDSTOP Stop auditing and write a trail tail record to the
current audit trail. On failure, errno is set to one of
the following values:
EINVAL Auditing is already off.
AUDSWITCH When auditing is on, flush all cached records to the
current trail file, write a trail tail record, and close
the file. The trail file given by argument becomes the
current trail file, it is opened, its MAC label is set
to the default audit data MAC label, and a trail header
record is written to it. The parameters sizearg and
the audtrailspect structure are as described above for
the AUDSTART command. When a new file cannot be
switched to, for any reason, auditing continues to the
current trail file.
Note that switching to the current file with truncate
TRUE deletes the contents of the file before the trail
header record is written.
On failure, errno is set to one of the following values:
EINVAL Auditing is not on.
EINVAL argument is NULL.
EINVAL The trail pathname does not begin with /.
EINVAL sizearg does not match the
actualtrailspecsize field in the
structure pointed to by argument.
ENOMEM Unable to allocate memory to complete the
request.
EACCES filename is a directory or an unsupported
file type.
ENOSPC Insufficient contiguous space to create a
file entry or inode.
ENOENT A non-terminal component of the pathname
does not exist.
ENOTDIR A non-terminal component of the pathname
was not a directory.
ENAMETOOLONG The pathname exceeds the length limit for
pathnames or a component of the pathname
exceeds the length limit for filenames.
EPERM The pathname contains a character not in
the allowed character set.
AUDFLUSH Flush all cached audit records to the current trail
file. There is no guarantee that on return from this
request the record cache is empty, only that records
stored there before the request have been written to the
file. On failure, errno is set to one of the following
values:
EINVAL Auditing is not on.
AUDMUSTSTART
Specify the action to be taken when auditing cannot be
started at system boot time. When argument is BTRUE,
init(1M) will not exit single-user level when auditing
is not on. When argument is BFALSE, the audit state
does not affect the init process's decision to exit
single-user level.
AUDMUSTAUDIT
Specify the action to be taken when auditing fails and
the system is in multiuser mode. When argument is
BTRUE the system signals init to change state to
single-user state if auditing cannot continue due to a
failure. When argument is BFALSE, the system turns
auditing off and continues.
AUDSETMASK Replace the system-wide audit mask with the audit mask
pointed to by argument. An audit mask, type audmaskt,
is an array of AUDCLASSCOUNT reason codes. A reason
code is of type audreasont and specifies the reason
for auditing a class of events--see sys/audit.h.
sizearg is ignored. On failure, errno is set to one of
the following values:
EFAULT The caller does not have read access to one or
more bytes of the mask.
AUDGETSTATUS
Return the audit state in the structure pointed to by
argument. argument points to a structure of type
audconfigurationt containing the following fields:
booleant auditingison;
booleant shutdownonstartupfailure;
booleant shutdownonauditfailure;
booleant stoppedbysystem;
audmaskt systemauditmask;
When the booleant types are BTRUE the conditions
described by their names are enabled. systemauditmask
contains a copy of the system-wide audit mask. On
failure, errno is set to the following value:
EFAULT The caller does not have read/write access to
one or more bytes of the structure pointed to by
argument.
AUDGETTRAILSPECSIZE
Return the size of a buffer that will hold the current
trail specification structure. This structure contains
the trail filename and is therefore of variable size.
The return value from the command is the minimum number
of bytes of memory needed to hold the current trail
specification structure. A zero (0) is returned when
there is no current trail specification.
AUDGETTRAILSPEC
Copy the current trailspec into the structure, of type
audtrailspect, pointed to by argument. On failure,
errno is set to one of the following values and argument
is not changed:
EFAULT The caller does not have read/write access to
the block of memory given by argument and
sizearg.
EINVAL The sizearg is less than the size of the
current trail specification structure.
ENOENT There is no trail specification.
AUDSETTRAILSPEC
Replace the current trail specification by the one
pointed to by argument. Auditing must currently be off.
Whenever auditing is started without specifying a trail
specification, the current trail is used.
This command verifies that the trail file is on a
writable file system that currently has room for a file
of at least maxkbytes kilobytes. On failure, errno is
set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and sizearg.
EINVAL The trail pathname does not begin with /.
EINVAL Auditing is on.
EINVAL The trail file is in a read-only file system.
EINVAL Not enough room exists on the file system for a
file of size maxkbytes.
AUDSETCMDSETMAP
When auditing is off, replace the array of audit classes
used to map user-level DG Command events to their
designated classes. The new map pointed to by argument
is an array of audclasst, containing sizearg entries.
The class to which an event is mapped is found by
indexing into the class map given an event number. The
index is calculated by subtracting AUDETCOMMANDSBASE
from the user-level event number.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and sizearg.
EINVAL sizearg is less than AUDMINIMUMAAEVENTS or
greater than AUDMAXCMDEVENTS.
ENOMEM Could not allocate memory for the new map.
AUDSETKERNELETMAP
When auditing is off, replace the array of audit classes
used to map kernel-level events to their designated
classes. The new map pointed to by argument is an array
of audclasst, containing sizearg entries.
The class to which an event is mapped is found by
indexing into the class map given an event number. The
index is calculated by subtracting AUDETKERNELBASE
from the kernel event number.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and sizearg.
EINVAL sizearg is not equal to the size corresponding
to AUDNUMKERNELEVENTS.
ENOMEM Could not allocate memory for the new map.
AUDSETISVETMAP
When auditing is off, replace the array of audit classes
used to map user-level ISV events to their designated
classes. The new map pointed to by argument is an array
of audclasst, containing sizearg entries.
The class to which an event is mapped is found by
indexing into the class map given an event number. The
index is calculated by subtracting AUDETISVBASE from
the user-level event number.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and sizearg.
EFAULT Auditing is on.
EINVAL sizearg is less than AUDMINIMUMISVEVENTS or
greater than AUDMAXIMUMISVEVENTS.
ENOMEM Could not allocate memory for the new map.
AUDSETSITEETMAP
When auditing is off, replace the array of audit classes
used to map user-level site-specific events to their
designated classes. The new map pointed to by argument
is an array of audclasst, containing sizearg entries.
The class to which an event is mapped is found by
indexing into the class map given an event number. The
index is calculated by subtracting AUDETSITEBASE from
the user-level event number.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument and sizearg.
EFAULT Auditing is on.
EINVAL sizearg is less than AUDMINIMUMSITEEVENTS or
greater than AUDMAXIMUMSITEEVENTS.
ENOMEM Could not allocate memory for the new map.
AUDGETCMDSETMAP
Get the current map of DG Commands events to classes.
The maximum number of entries to be returned is given by
sizearg.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument and sizearg.
AUDGETKERNELETMAP
Get the current map of kernel events to classes. The
maximum number of entries to be returned is given by
sizearg.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument and sizearg.
AUDGETISVETMAP
Get the current map of ISV events to classes. The
maximum number of entries to be returned is given by
sizearg.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument and sizearg.
AUDGETSITEETMAP
Get the current map of site-specific events to classes.
The maximum number of entries to be returned is given by
sizearg.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument and sizearg.
AUDSETFILTERSUBJTUPLE
Set the subject MAC range tuple filter limits. The new
subject filter MAC range tuple is a macfilterstructt
pointed to by argument, and its size is specified by
sizearg.
If subject filtering is enabled, only audit records
generated by subjects with MAC labels within this range
tuple will be included in the audit trail.
Setting the filter limits with this command does not
enable or disable use of the filter. This is controlled
using the AUDUSESUBJTUPLEFILTER command described
below.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument.
EINVAL The specified MAC range tuple is invalid or the
value of sizearg is not valid as the size of a
MAC range tuple.
AUDSETFILTEROBJTUPLE
Set the object MAC range tuple filter limits. The new
object filter MAC range tuple is a mactuplestructt
pointed to by argument, and its size is specified by
sizearg.
If object filtering is enabled, only audit records
generated for events that accessed an object with a MAC
label within this range tuple will be included in the
audit trail. For objects governed by a MAC range tuple,
the audit record is included if the object's MAC range
tuple and the filter range tuple have at least one label
in common.
Setting the filter limits with this command does not
enable or disable use of the filter. This is controlled
using the AUDUSEOBJTUPLEFILTER command described
below.
On failure, errno is set to one of the following values:
EFAULT The caller does not have read access to the
block of memory given by argument.
EINVAL The specified MAC range tuple is invalid, or the
value of sizearg is not valid as the size of a
MAC range tuple.
AUDUSESUBJTUPLEFILTER
Enable or disable the use of the subject MAC range tuple
filter. When argument is BTRUE, the subject MAC range
tuple filter is applied to all future audit records.
When argument is BFALSE, further use of the subject
filter is disabled.
AUDUSEOBJTUPLEFILTER
Enable or disable the use of the object MAC range tuple
filter. When argument is BTRUE, the object MAC range
tuple filter is applied to all future audit records.
When argument is BFALSE, further use of the object
filter is disabled.
AUDGETFILTERVALUES
Get the status of the subject and object MAC range tuple
filters, and the MAC range tuples currently being used
for each one. argument points to a audtuplefiltert
structure to receive the information.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument.
AUDGETTRAILMACLABEL
Get the MAC label being applied to audit trails.
argument points to a maclabelstructt structure to
receive the binary MAC label.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument.
AUDSETTRAILMACLABEL
Set the MAC label being applied to audit trails.
argument points to a maclabelstructt structure that
contains the new MAC label. The MAC label must be in the
administrative MAC region.
On failure, errno is set to one of the following values:
EFAULT The caller does not have write access to the
block of memory given by argument.
EINVAL The specified binary MAC label is invalid, the
value of sizearg is not valid for a MAC label,
or the specified MAC label is not in the
administrative MAC region.
ACCESS CONTROL
The caller must have appropriate privilege.
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having one or more specific capabilities
enabled in the effective capability set of the calling process. See
capdefaults(5) for the default capability for this system call.
On systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
RETURN VALUE
Unless specified otherwise above, the return value from dgauditctl
is 0 upon success and -1 upon failure with errno set as indicated.
SEE ALSO
audadmin(1M), init(1M), capdefaults(5).
Licensed material--property of copyright holder(s)