'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH AUDIT_CONTROL 4 "Apr 16, 2009"
.SH NAME
audit_control \- control information for system audit daemon
.SH SYNOPSIS
.LP
.nf
\fB/etc/security/audit_control\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBaudit_control\fR file contains audit control information used by
\fBauditd\fR(1M). Each line consists of a title and a string, separated by a
colon. There are no restrictions on the order of lines in the file, although
some lines must appear only once. A line beginning with `\fB#\fR' is a comment.
A line can be continued with the use of the backslash (\fB\e\fR) convention.
(See EXAMPLES.)
.sp
.LP
Directory definition lines list the directories to be used when creating audit
files, in the order in which they are to be used. The format of a directory
line is:
.sp
.LP
\fBdir:\fR\fIdirectory-name\fR
.sp
.LP
\fIdirectory-name\fR is where the audit files will be created. Any valid
writable directory can be specified.
.sp
.LP
The following configuration is recommended:
.sp
.LP
\fB/etc/security/audit/\fIserver\fR/files\fR
.sp
.LP
where \fIserver\fR is the name of a central machine, since audit files
belonging to different servers are usually stored in separate subdirectories of
a single audit directory. The naming convention normally has \fIserver\fR be a
directory on a server machine, and all clients mount
\fB/etc/security/audit/\fR\fIserver\fR at the same location in their local file
systems. If the same server exports several different file systems for
auditing, their \fIserver\fR names will, of course, be different.
.sp
.LP
There are several other ways for audit data to be arranged: some sites may have
needs more in line with storing each host's audit data in separate
subdirectories. The audit structure used will depend on each individual site.
.sp
.LP
The audit threshold line specifies the percentage of free space that must be
present in the file system containing the current audit file. The format of the
threshold line is:
.sp
.LP
\fBminfree:\fR\fIpercentage\fR
.sp
.LP
where \fIpercentage\fR is indicates the amount of free space required. If free
space falls below this threshold, the audit daemon \fBauditd\fR(1M) invokes the
shell script \fBaudit_warn\fR(1M). If no threshold is specified, the default is
0%.
.sp
.LP
The \fBplugin\fR definition line selects a plugin to be loaded by the audit
daemon for processing audit records.
.sp
.LP
The format of a plugin line is:
.sp
.in +2
.nf
plugin: \fIkeyword1\fR=\fIvalue1\fR;\fIkeyword2\fR=\fIvalue2\fR;
.fi
.in -2
.sp

.sp
.LP
The following keywords are defined:
.sp
.ne 2
.na
\fB\fBname\fR\fR
.ad
.RS 9n
The value is the pathname of the plugin. This specification is required.
.RE

.sp
.ne 2
.na
\fB\fBqsize\fR\fR
.ad
.RS 9n
The value is the maximum number of records to queue for audit data sent to the
plugin. If omitted, the current hiwater mark (see the \fB-getqctrl\fR of
\fBauditconfig\fR(1M)) is used. When this maximum is reached, \fBauditd\fR will
either block or discard data, depending on the audit policy \fBcnt\fR. See
\fBauditconfig\fR(1M).
.RE

.sp
.ne 2
.na
\fB\fBp_*\fR\fR
.ad
.RS 9n
A keyword with the prefix \fBp_\fR is passed to the plugin defined by the value
associated with the \fBname\fR attribute. These attributes are defined for each
plugin. By convention, if the value associated with a \fBplugin\fR attribute is
a list, the list items are separated with commas.
.RE

.sp
.LP
If pathname is a relative path (it does not start with \fB/\fR) the library
path will be taken as relative to \fB/usr/lib/security/$ISA\fR. The \fB$ISA\fR
token is replaced by an implementation-defined directory name that defines the
path relative to the \fBauditd\fR(1M) instruction set architecture.
.sp
.LP
See \fBaudit_syslog\fR(5) for the attributes expected for \fBplugin:
name=audit_syslog.so\fR.
.sp
.LP
No plugin specifier is required for generation of a binary audit log. However,
to set a queue size of other than the default, a plugin line with
\fBname=audit_binfile.so\fR can be used as described in \fBaudit_binfile\fR(5).
.sp
.LP
You must specify one or more plugins. (In the case of \fBaudit_binfile.so\fR,
use of \fBdir:\fR or \fBplugin:\fR suffices.)
.sp
.LP
The audit flags line specifies the default system audit value. This value is
combined with the user audit value read from \fBaudit_user\fR(4) to form a
user's process preselection mask.
.sp
.LP
The algorithm for obtaining the process preselection mask is as follows: the
audit flags from the \fBflags:\fR line in the \fBaudit_control\fR file are
added to the flags from the \fBalways-audit\fR field in the user's entry in the
\fBaudit_user\fR file. The flags from the \fBnever-audit\fR field from the
user's entry in the \fBaudit_user\fR file are then subtracted from the total:
.sp
.in +2
.nf
user's process preselection mask =
   (flags: line + always audit flags) - never audit flags
.fi
.in -2
.sp

.sp
.LP
The format of a flags line is:
.sp
.LP
\fBflags:\fR\fIaudit-flags\fR
.sp
.LP
where \fIaudit-flags\fR specifies which event classes are to be audited. The
character string representation of \fIaudit-flags\fR contains a series of flag
names, each one identifying a single audit class, separated by commas. A name
preceded by `\fB\(mi\fR\&' means that the class should be audited for failure
only; successful attempts are not audited. A name preceded by `\fB+\fR' means
that the class should be audited for success only; failing attempts are not
audited. Without a prefix, the name indicates that the class is to be audited
for both successes and failures. The special string \fBall\fR indicates that
all events should be audited; \fB\(miall\fR indicates that all failed attempts
are to be audited, and \fB+all\fR all successful attempts. The prefixes
\fB^\fR, \fB^\(mi\fR, and \fB^+\fR turn off flags specified earlier in the
string (\fB^\(mi\fR and \fB^+\fR for failing and successful attempts, \fB^\fR
for both). They are typically used to reset flags.
.sp
.LP
The non-attributable flags line is similar to the flags line, but this one
contain the audit flags that define what classes of events are audited when an
action cannot be attributed to a specific user. The format of a \fBnaflags\fR
line is:
.sp
.LP
\fBnaflags:\fR\fIaudit-flags\fR
.sp
.LP
The flags are separated by commas, with no spaces. See \fBaudit_class\fR(4) for
a list of the predefined audit classes. Note that the classes are configurable
as also described in \fBaudit_class\fR(4).
.sp
.LP
A line can be continued by appending a backslash (\fB\e\fR).
.SH EXAMPLES
.LP
\fBExample 1 \fRSample \fBaudit_control\fR File for Specific Host
.sp
.LP
The following is a sample \fB/etc/security/audit_control\fR file for the
machine \fBeggplant\fR.

.sp
.LP
The file's contents identify server \fBjedgar\fR with two file systems normally
used for audit data, another server, \fBglobal\fR, used only when \fBjedgar\fR
fills up or breaks, and specifies that the warning script is run when the file
systems are 80% filled. It also specifies that all logins, administrative
operations are to be audited, whether or not they succeed. All failures except
failures to access object attributes are to be audited.

.sp
.in +2
.nf
dir: /etc/security/jedgar/eggplant
dir: /etc/security/jedgar.aux/eggplant
#
# Last-ditch audit file system when jedgar fills up.
#
dir: /etc/security/global/eggplant
minfree: 20
flags: lo,ad,-all,^-fm
naflags: lo,ad
.fi
.in -2
.sp

.LP
\fBExample 2 \fRSample \fBaudit_control\fR File for syslog and Local Storage
.sp
.LP
Shown below is a sample \fB/etc/security/audit_control\fR file for syslog and
local storage. For the binary log, the output is all \fBlo\fR and \fBad\fR
records, all failures of class \fBfm\fR and any classes specified by means of
\fBaudit_user\fR(4). For syslog output, all \fBlo\fR records are output, only
failure \fBad\fR records are output, and no \fBfm\fR records are output. The
specification for the plugin is given in two lines.

.sp
.in +2
.nf
dir: /etc/security/jedgar/eggplant
dir: /etc/security/jedgar.aux/eggplant
#
# Last-ditch audit file system when jedgar fills up.
#
dir: /etc/security/global/eggplant
minfree: 20
flags: lo,ad,-fm
naflags: lo,ad
plugin: name=audit_syslog.so;p_flags=lo,+ad;\e
qsize=512
.fi
.in -2
.sp

.LP
\fBExample 3 \fROverriding the Default Queue Size
.sp
.LP
Shown below is a sample \fB/etc/security/audit_control\fR file that overrides
the default queue size for binary audit log file generation.

.sp
.in +2
.nf
dir: /etc/security/jedgar/eggplant
dir: /etc/security/jedgar.aux/eggplant
#
# Last-ditch audit file system when jedgar fills up.
#
dir: /etc/security/global/eggplant
minfree: 20
flags: lo,ad,-fm
naflags: lo,ad
plugin: name=audit_binfile.so; qsize=256
.fi
.in -2
.sp

.SH FILES
.sp
.LP
\fB/etc/security/audit_control\fR
.sp
.LP
\fB/etc/security/audit_warn\fR
.sp
.LP
\fB/etc/security/audit/*/*/*\fR
.sp
.LP
\fB/etc/security/audit_user\fR
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability 	Obsolete Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBaudit\fR(1M), \fBaudit_warn\fR(1M), \fBauditd\fR(1M), \fBbsmconv\fR(1M),
\fBaudit\fR(2), \fBgetfauditflags\fR(3BSM), \fBaudit.log\fR(4),
\fBaudit_class\fR(4), \fBaudit_user\fR(4), \fBattributes\fR(5),
\fBaudit_binfile\fR(5), \fBaudit_syslog\fR(5)
.sp
.LP
Part\ VII, \fISolaris Auditing,\fR in \fISystem Administration Guide: Security
Services\fR
.SH NOTES
.sp
.LP
Use of the plugin configuration line to include \fBaudit_syslog.so\fR requires
that \fB/etc/syslog.conf\fR be configured for audit data. See
\fBaudit_syslog\fR(5) for more details.
.sp
.LP
Configuration changes do not affect audit sessions that are currently running,
as the changes do not modify a process's preselection mask. To change the
preselection mask on a running process, use the \fB-setpmask\fR option of the
\fBauditconfig\fR command (see \fBauditconfig\fR(1M)). If the user logs out and
logs back in, the new configuration changes will be reflected in the next audit
session.
.sp
.LP
This file is Obsolete and may be removed and replaced with equivalent
functionality in a future release of Solaris.