xref: /titanic_44/usr/src/man/man4/audit_control.4 (revision 56b2bdd1f04d465cfe4a95b88ae5cba5884154e4)
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]
AUDIT_CONTROL 4 "Apr 16, 2009"
NAME
audit_control - control information for system audit daemon
SYNOPSIS

/etc/security/audit_control
DESCRIPTION

The audit_control file contains audit control information used by auditd(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 `#' is a comment. A line can be continued with the use of the backslash (\e) convention. (See EXAMPLES.)

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:

dir:directory-name

directory-name is where the audit files will be created. Any valid writable directory can be specified.

The following configuration is recommended:

/etc/security/audit/server/files

where server 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 server be a directory on a server machine, and all clients mount /etc/security/audit/server at the same location in their local file systems. If the same server exports several different file systems for auditing, their server names will, of course, be different.

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.

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:

minfree:percentage

where percentage is indicates the amount of free space required. If free space falls below this threshold, the audit daemon auditd(1M) invokes the shell script audit_warn(1M). If no threshold is specified, the default is 0%.

The plugin definition line selects a plugin to be loaded by the audit daemon for processing audit records.

The format of a plugin line is:

plugin: keyword1=value1;keyword2=value2;

The following keywords are defined: name

The value is the pathname of the plugin. This specification is required.

qsize

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 -getqctrl of auditconfig(1M)) is used. When this maximum is reached, auditd will either block or discard data, depending on the audit policy cnt. See auditconfig(1M).

p_*

A keyword with the prefix p_ is passed to the plugin defined by the value associated with the name attribute. These attributes are defined for each plugin. By convention, if the value associated with a plugin attribute is a list, the list items are separated with commas.

If pathname is a relative path (it does not start with /) the library path will be taken as relative to /usr/lib/security/$ISA. The $ISA token is replaced by an implementation-defined directory name that defines the path relative to the auditd(1M) instruction set architecture.

See audit_syslog(5) for the attributes expected for plugin: name=audit_syslog.so.

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 name=audit_binfile.so can be used as described in audit_binfile(5).

You must specify one or more plugins. (In the case of audit_binfile.so, use of dir: or plugin: suffices.)

The audit flags line specifies the default system audit value. This value is combined with the user audit value read from audit_user(4) to form a user's process preselection mask.

The algorithm for obtaining the process preselection mask is as follows: the audit flags from the flags: line in the audit_control file are added to the flags from the always-audit field in the user's entry in the audit_user file. The flags from the never-audit field from the user's entry in the audit_user file are then subtracted from the total:

user's process preselection mask =
 (flags: line + always audit flags) - never audit flags

The format of a flags line is:

flags:audit-flags

where audit-flags specifies which event classes are to be audited. The character string representation of audit-flags contains a series of flag names, each one identifying a single audit class, separated by commas. A name preceded by `-' means that the class should be audited for failure only; successful attempts are not audited. A name preceded by `+' 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 all indicates that all events should be audited; -all indicates that all failed attempts are to be audited, and +all all successful attempts. The prefixes ^, ^-, and ^+ turn off flags specified earlier in the string (^- and ^+ for failing and successful attempts, ^ for both). They are typically used to reset flags.

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 naflags line is:

naflags:audit-flags

The flags are separated by commas, with no spaces. See audit_class(4) for a list of the predefined audit classes. Note that the classes are configurable as also described in audit_class(4).

A line can be continued by appending a backslash (\e).

EXAMPLES

Example 1 Sample audit_control File for Specific Host

The following is a sample /etc/security/audit_control file for the machine eggplant.

The file's contents identify server jedgar with two file systems normally used for audit data, another server, global, used only when jedgar 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.

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

Example 2 Sample audit_control File for syslog and Local Storage

Shown below is a sample /etc/security/audit_control file for syslog and local storage. For the binary log, the output is all lo and ad records, all failures of class fm and any classes specified by means of audit_user(4). For syslog output, all lo records are output, only failure ad records are output, and no fm records are output. The specification for the plugin is given in two lines.

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

Example 3 Overriding the Default Queue Size

Shown below is a sample /etc/security/audit_control file that overrides the default queue size for binary audit log file generation.

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
FILES

/etc/security/audit_control

/etc/security/audit_warn

/etc/security/audit/*/*/*

/etc/security/audit_user

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Obsolete Committed
SEE ALSO

audit(1M), audit_warn(1M), auditd(1M), bsmconv(1M), audit(2), getfauditflags(3BSM), audit.log(4), audit_class(4), audit_user(4), attributes(5), audit_binfile(5), audit_syslog(5)

Part VII, Solaris Auditing, in System Administration Guide: Security Services

NOTES

Use of the plugin configuration line to include audit_syslog.so requires that /etc/syslog.conf be configured for audit data. See audit_syslog(5) for more details.

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 -setpmask option of the auditconfig command (see auditconfig(1M)). If the user logs out and logs back in, the new configuration changes will be reflected in the next audit session.

This file is Obsolete and may be removed and replaced with equivalent functionality in a future release of Solaris.