'\" te
.\"  Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" 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 AUDITCONFIG 1M "Sep 14, 2009"
.SH NAME
auditconfig \- configure auditing
.SH SYNOPSIS
.LP
.nf
\fBauditconfig\fR \fIoption\fR...
.fi

.SH DESCRIPTION
.sp
.LP
\fBauditconfig\fR provides a command line interface to get and set kernel audit
parameters.
.sp
.LP
This functionality is available only if the Solaris Auditing feature has been
enabled. See \fBbsmconv\fR(1M) for more information.
.sp
.LP
The setting of the \fBperzone\fR policy determines the scope of the audit
setting controlled by \fBauditconfig\fR. If \fBperzone\fR is set, then the
values reflect the local zone except as noted. Otherwise, the settings are for
the entire system. Any restriction based on the \fBperzone\fR setting is noted
for each option to which it applies.
.sp
.LP
A non-global zone administrator can set all audit policy options except
\fBperzone\fR and \fBahlt\fR. \fBperzone\fR and \fBahlt\fR apply only to the
global zone; setting these policies requires the privileges of a global zone
administrator. \fBperzone\fR and \fBahlt\fR are described under the
\fB-setpolicy\fR option, below.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-aconf\fR\fR
.ad
.sp .6
.RS 4n
Set the non-attributable audit mask from the \fBaudit_control\fR(4) file. For
example:
.sp
.in +2
.nf
# auditconfig -aconf
Configured non-attributable events.
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-audit\fR \fIevent\fR \fIsorf\fR \fIretval\fR \fIstring\fR\fR
.ad
.sp .6
.RS 4n
This command constructs an audit record for audit event \fIevent\fR using the
process's audit characteristics containing a text token \fIstring\fR. The
return token is constructed from the \fIsorf\fR (success/failure flag) and the
\fIretval\fR (return value). The event is type \fBchar*\fR, the \fIsorf\fR is
0/1 for success/failure, \fIretval\fR is an errno value, \fIstring\fR is type
\fB*char\fR. This command is useful for constructing an audit record with a
shell script. An example of this option:
.sp
.in +2
.nf
# auditconfig -audit AUE_ftpd 0 0 "test string"
#

audit record from audit trail:
    header,76,2,ftp access,,Fri Dec 08 08:44:02 2000, + 669 msec
    subject,abc,root,other,root,other,104449,102336,235 197121 elbow
    text,test string
    return,success,0
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-chkaconf\fR\fR
.ad
.sp .6
.RS 4n
Checks the configuration of the non-attributable events set in the kernel
against the entries in \fBaudit_control\fR(4). If the runtime class mask of a
kernel audit event does not match the configured class mask, a mismatch is
reported.
.RE

.sp
.ne 2
.na
\fB\fB-chkconf\fR\fR
.ad
.sp .6
.RS 4n
Check the configuration of kernel audit event to class mappings. If the runtime
class mask of a kernel audit event does not match the configured class mask, a
mismatch is reported.
.RE

.sp
.ne 2
.na
\fB\fB-conf\fR\fR
.ad
.sp .6
.RS 4n
Configure kernel audit event to class mappings. Runtime class mappings are
changed to match those in the audit event to class database file.
.RE

.sp
.ne 2
.na
\fB\fB-getasid\fR\fR
.ad
.sp .6
.RS 4n
Prints the audit session ID of the current process. For example:
.sp
.in +2
.nf
# auditconfig -getasid
audit session id = 102336
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getaudit\fR\fR
.ad
.sp .6
.RS 4n
Returns the audit characteristics of the current process.
.sp
.in +2
.nf
# auditconfig -getaudit
audit id = abc(666)
process preselection mask = lo(0x1000,0x1000)
terminal id (maj,min,host) = 235,197121,elbow(172.146.89.77)
audit session id = 102336
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getauid\fR\fR
.ad
.sp .6
.RS 4n
Prints the audit ID of the current process. For example:
.sp
.in +2
.nf
# auditconfig -getauid
audit id = abc(666)
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getcar\fR\fR
.ad
.sp .6
.RS 4n
Prints current active root location (anchored from root [or local zone root] at
system boot). For example:
.sp
.in +2
.nf
# auditconfig -getcar
current active root = /
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getclass\fR \fIevent\fR\fR
.ad
.sp .6
.RS 4n
Display the preselection mask associated with the specified kernel audit event.
\fIevent\fR is the kernel event number or event name.
.RE

.sp
.ne 2
.na
\fB\fB-getcond\fR\fR
.ad
.sp .6
.RS 4n
Display the kernel audit condition. The condition displayed is the literal
string \fBauditing\fR meaning auditing is enabled and turned on (the kernel
audit module is constructing and queuing audit records); \fBnoaudit\fR, meaning
auditing is enabled but turned off (the kernel audit module is not constructing
and queuing audit records); \fBdisabled\fR, meaning that the audit module has
not been enabled; or \fBnospace\fR, meaning there is no space for saving audit
records. See \fBauditon\fR(2) and \fBauditd\fR(1M) for further information.
.RE

.sp
.ne 2
.na
\fB\fB-getestate\fR \fIevent\fR\fR
.ad
.sp .6
.RS 4n
For the specified event (string or event number), print out classes \fIevent\fR
has been assigned. For example:
.sp
.in +2
.nf
# auditconfig -getestate 20
audit class mask for event AUE_REBOOT(20) = 0x800
# auditconfig -getestate AUE_RENAME
audit class mask for event AUE_RENAME(42) = 0x30
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getkaudit\fR\fR
.ad
.sp .6
.RS 4n
Get audit characteristics of the current zone. For example:
.sp
.in +2
.nf
# auditconfig -getkaudit
audit id = unknown(-2)
process preselection mask = lo,na(0x1400,0x1400)
terminal id (maj,min,host) = 0,0,(0.0.0.0)
audit session id = 0
.fi
.in -2
.sp

If the audit policy \fBperzone\fR is not set, the terminal id is that of the
global zone. Otherwise, it is the terminal id of the local zone.
.RE

.sp
.ne 2
.na
\fB\fB-getkmask\fR\fR
.ad
.sp .6
.RS 4n
Get non-attributable pre-selection mask for the current zone. For example:
.sp
.in +2
.nf
# auditconfig -getkmask
audit flags for non-attributable events = lo,na(0x1400,0x1400)
.fi
.in -2
.sp

If the audit policy \fBperzone\fR is not set, the kernel mask is that of the
global zone. Otherwise, it is that of the local zone.
.RE

.sp
.ne 2
.na
\fB\fB-getpinfo\fR \fIpid\fR\fR
.ad
.sp .6
.RS 4n
Display the audit ID, preselection mask, terminal ID, and audit session ID for
the specified process.
.RE

.sp
.ne 2
.na
\fB\fB-getpolicy\fR\fR
.ad
.sp .6
.RS 4n
Display the kernel audit policy. The \fBahlt\fR and \fBperzone\fR policies
reflect the settings from the global zone. If \fBperzone\fR is set, all other
policies reflect the local zone's settings. If \fBperzone\fR is not set, the
policies are machine-wide.
.RE

.sp
.ne 2
.na
\fB\fB-getcwd\fR\fR
.ad
.sp .6
.RS 4n
Prints current working directory (anchored from zone root at system boot). For
example:
.sp
.in +2
.nf
# cd /usr/tmp
# auditconfig -getcwd
current working directory = /var/tmp
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getqbufsz\fR\fR
.ad
.sp .6
.RS 4n
Get audit queue write buffer size. For example:
.sp
.in +2
.nf
# auditconfig -getqbufsz
        audit queue buffer size (bytes) = 1024
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getqctrl\fR\fR
.ad
.sp .6
.RS 4n
Get audit queue write buffer size, audit queue \fBhiwater\fR mark, audit queue
\fBlowater\fR mark, audit queue \fBprod\fR interval (ticks).
.sp
.in +2
.nf
# auditconfig -getqctrl
audit queue hiwater mark (records) = 100
audit queue lowater mark (records) = 10
audit queue buffer size (bytes) = 1024
audit queue delay (ticks) = 20
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getqdelay\fR\fR
.ad
.sp .6
.RS 4n
Get interval at which audit queue is prodded to start output. For example:
.sp
.in +2
.nf
# auditconfig -getqdelay
audit queue delay (ticks) = 20
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getqhiwater\fR\fR
.ad
.sp .6
.RS 4n
Get high water point in undelivered audit records when audit generation will
block. For example:
.sp
.in +2
.nf
# ./auditconfig -getqhiwater
audit queue hiwater mark (records) = 100
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getqlowater\fR\fR
.ad
.sp .6
.RS 4n
Get low water point in undelivered audit records where blocked processes will
resume. For example:
.sp
.in +2
.nf
# auditconfig -getqlowater
audit queue lowater mark (records) = 10
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-getstat\fR\fR
.ad
.sp .6
.RS 4n
Print current audit statistics information. For example:
.sp
.in +2
.nf
# auditconfig -getstat
gen nona kern  aud  ctl  enq wrtn wblk rblk drop  tot  mem
910    1  725  184    0  910  910    0  231    0   88   48
.fi
.in -2
.sp

See \fBauditstat\fR(1M) for a description of the headings in \fB-getstat\fR
output.
.RE

.sp
.ne 2
.na
\fB\fB-gettid\fR\fR
.ad
.sp .6
.RS 4n
Print audit terminal ID for current process. For example:
.sp
.in +2
.nf
# auditconfig -gettid
terminal id (maj,min,host) = 235,197121,elbow(172.146.89.77)
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-lsevent\fR\fR
.ad
.sp .6
.RS 4n
Display the currently configured (runtime) kernel and user level audit event
information.
.RE

.sp
.ne 2
.na
\fB\fB-lspolicy\fR\fR
.ad
.sp .6
.RS 4n
Display the kernel audit policies with a description of each policy.
.RE

.sp
.ne 2
.na
\fB\fB-setasid\fR \fIsession-ID\fR [\fIcmd\fR]\fR
.ad
.sp .6
.RS 4n
Execute shell or \fIcmd\fR with specified \fIsession-ID\fR. For example:
.sp
.in +2
.nf
# ./auditconfig -setasid 2000 /bin/ksh
#
# ./auditconfig -getpinfo 104485
audit id = abc(666)
process preselection mask = lo(0x1000,0x1000)
terminal id (maj,min,host) = 235,197121,elbow(172.146.89.77)
audit session id = 2000
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-setaudit\fR \fIaudit-ID\fR \fIpreselect_flags\fR \fIterm-ID\fR
\fIsession-ID\fR [\fIcmd\fR]\fR
.ad
.sp .6
.RS 4n
Execute shell or \fIcmd\fR with the specified audit characteristics.
.RE

.sp
.ne 2
.na
\fB\fB-setauid\fR \fIaudit-ID\fR [\fIcmd\fR]\fR
.ad
.sp .6
.RS 4n
Execute shell or \fIcmd\fR with the specified \fIaudit-ID\fR.
.RE

.sp
.ne 2
.na
\fB\fB-setclass\fR \fIevent audit_flag\fR[\fI,audit_flag .\|.\|.\fR]\fR
.ad
.sp .6
.RS 4n
Map the kernel event \fIevent\fR to the classes specified by \fIaudit_flags\fR.
\fIevent\fR is an event number or name. An \fIaudit_flag\fR is a two character
string representing an audit class. See \fBaudit_control\fR(4) for further
information. If \fBperzone\fR is not set, this option is valid only in the
global zone.
.RE

.sp
.ne 2
.na
\fB\fB-setkaudit\fR \fIIP-address_type\fR \fIIP_address\fR\fR
.ad
.sp .6
.RS 4n
Set IP address of machine to specified values. \fIIP-address_type\fR is
\fBipv6\fR or \fBipv4\fR.
.sp
If \fBperzone\fR is not set, this option is valid only in the global zone.
.RE

.sp
.ne 2
.na
\fB\fB-setkmask\fR \fIaudit_flags\fR\fR
.ad
.sp .6
.RS 4n
Set non-attributes selection flags of machine.
.sp
If \fBperzone\fR is not set, this option is valid only in the global zone.
.RE

.sp
.ne 2
.na
\fB\fB-setpmask\fR \fIpid flags\fR\fR
.ad
.sp .6
.RS 4n
Set the preselection mask of the specified process. \fBflags\fR is the ASCII
representation of the flags similar to that in \fBaudit_control\fR(4).
.sp
If \fBperzone\fR is not set, this option is valid only in the global zone.
.RE

.sp
.ne 2
.na
\fB\fB-setpolicy\fR
[\fI+\fR|\fI-\fR]\fIpolicy_flag\fR[\fI,policy_flag ...\fR]\fR
.ad
.sp .6
.RS 4n
Set the kernel audit policy. A policy \fIpolicy_flag\fR is literal strings that
denotes an audit policy. A prefix of \fB+\fR adds the policies specified to the
current audit policies. A prefix of \fB-\fR removes the policies specified from
the current audit policies. No policies can be set from a local zone unless the
\fBperzone\fR policy is first set from the global zone. The following are the
valid policy flag strings (\fBauditconfig\fR \fB-lspolicy\fR also lists the
current valid audit policy flag strings):
.sp
.ne 2
.na
\fB\fBall\fR\fR
.ad
.RS 16n
Include all policies that apply to the current zone.
.RE

.sp
.ne 2
.na
\fB\fBahlt\fR\fR
.ad
.RS 16n
Panic is called and the system dumps core if an asynchronous audit event occurs
that cannot be delivered because the audit queue has reached the high-water
mark or because there are insufficient resources to construct an audit record.
By default, records are dropped and a count is kept of the number of dropped
records.
.RE

.sp
.ne 2
.na
\fB\fBarge\fR\fR
.ad
.RS 16n
Include the \fBexecv\fR(2) system call environment arguments to the audit
record. This information is not included by default.
.RE

.sp
.ne 2
.na
\fB\fBargv\fR\fR
.ad
.RS 16n
Include the \fBexecv\fR(2) system call parameter arguments to the audit record.
This information is not included by default.
.RE

.sp
.ne 2
.na
\fB\fBcnt\fR\fR
.ad
.RS 16n
Do not suspend processes when audit resources are exhausted. Instead, drop
audit records and keep a count of the number of records dropped. By default,
process are suspended until audit resources become available.
.RE

.sp
.ne 2
.na
\fB\fBgroup\fR\fR
.ad
.RS 16n
Include the supplementary group token in audit records. By default, the group
token is not included.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 16n
Include no policies. If used in other than the global zone, the \fBahlt\fR and
\fBperzone\fR policies are not changed.
.RE

.sp
.ne 2
.na
\fB\fBpath\fR\fR
.ad
.RS 16n
Add secondary path tokens to audit record. These are typically the pathnames of
dynamically linked shared libraries or command interpreters for shell scripts.
By default, they are not included.
.RE

.sp
.ne 2
.na
\fB\fBperzone\fR\fR
.ad
.RS 16n
Maintain separate configuration, queues, and logs for each zone and execute a
separate version of \fBauditd\fR(1M) for each zone.
.RE

.sp
.ne 2
.na
\fB\fBpublic\fR\fR
.ad
.RS 16n
Audit public files. By default, read-type operations are not audited for
certain files which meet \fBpublic\fR characteristics: owned by root, readable
by all, and not writable by all.
.RE

.sp
.ne 2
.na
\fB\fBtrail\fR\fR
.ad
.RS 16n
Include the trailer token in every audit record. By default, the trailer token
is not included.
.RE

.sp
.ne 2
.na
\fB\fBseq\fR\fR
.ad
.RS 16n
Include the sequence token as part of every audit record. By default, the
sequence token is not included. The sequence token attaches a sequence number
to every audit record.
.RE

.sp
.ne 2
.na
\fB\fBwindata_down\fR\fR
.ad
.RS 16n
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.
.RE

.sp
.ne 2
.na
\fB\fBwindata_up\fR\fR
.ad
.RS 16n
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.
.RE

.sp
.ne 2
.na
\fB\fBzonename\fR\fR
.ad
.RS 16n
Include the \fBzonename\fR token as part of every audit record. By default, the
\fBzonename\fR token is not included. The \fBzonename\fR token gives the name
of the zone from which the audit record was generated.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-setqbufsz\fR \fIbuffer_size\fR\fR
.ad
.sp .6
.RS 4n
Set the audit queue write buffer size (bytes).
.RE

.sp
.ne 2
.na
\fB\fB-setqctrl\fR \fIhiwater\fR \fIlowater\fR \fIbufsz\fR \fIinterval\fR\fR
.ad
.sp .6
.RS 4n
Set the audit queue write buffer size (bytes), hiwater audit record count,
lowater audit record count, and wakeup interval (ticks). Valid within a local
zone only if \fBperzone\fR is set.
.RE

.sp
.ne 2
.na
\fB\fB-setqdelay\fR \fIinterval\fR\fR
.ad
.sp .6
.RS 4n
Set the audit queue wakeup interval (ticks). This determines the interval at
which the kernel pokes the audit queue, to write audit records to the audit
trail. Valid within a local zone only if \fBperzone\fR is set.
.RE

.sp
.ne 2
.na
\fB\fB-setqhiwater\fR \fIhiwater\fR\fR
.ad
.sp .6
.RS 4n
Set the number of undelivered audit records in the audit queue at which audit
record generation blocks. Valid within a local zone only if \fBperzone\fR is
set.
.RE

.sp
.ne 2
.na
\fB\fB-setqlowater\fR \fIlowater\fR\fR
.ad
.sp .6
.RS 4n
Set the number of undelivered audit records in the audit queue at which blocked
auditing processes unblock. Valid within a local zone only if \fBperzone\fR is
set.
.RE

.sp
.ne 2
.na
\fB\fB-setsmask\fR \fIasid flags\fR\fR
.ad
.sp .6
.RS 4n
Set the preselection mask of all processes with the specified audit session ID.
Valid within a local zone only if \fBperzone\fR is set.
.RE

.sp
.ne 2
.na
\fB\fB-setstat\fR\fR
.ad
.sp .6
.RS 4n
Reset audit statistics counters. Valid within a local zone only if
\fBperzone\fR is set.
.RE

.sp
.ne 2
.na
\fB\fB-setumask\fR \fIauid flags\fR\fR
.ad
.sp .6
.RS 4n
Set the preselection mask of all processes with the specified audit ID. Valid
within a local zone only if \fBperzone\fR is set.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBauditconfig\fR
.sp
.LP
The following is an example of an \fBauditconfig\fR program:

.sp
.in +2
.nf
#
# map kernel audit event number 10 to the "fr" audit class
#
% auditconfig -setclass 10 fr

#
# turn on inclusion of exec arguments in exec audit records
#
% auditconfig -setpolicy +argv
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/security/audit_event\fR\fR
.ad
.RS 29n
Stores event definitions used in the audit system.
.RE

.sp
.ne 2
.na
\fB\fB/etc/security/audit_class\fR\fR
.ad
.RS 29n
Stores class definitions used in the audit system.
.RE

.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	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBaudit\fR(1M), \fBauditd\fR(1M), \fBauditstat\fR(1M), \fBbsmconv\fR(1M),
\fBpraudit\fR(1M), \fBauditon\fR(2), \fBexecv\fR(2), \fBaudit_class\fR(4),
\fBaudit_control\fR(4), \fBaudit_event\fR(4), \fBattributes\fR(5),
\fBaudit_binfile\fR(5)
.sp
.LP
See the section on Solaris Auditing in \fISystem Administration Guide: Security
Services\fR.
.SH NOTES
.sp
.LP
If plugin output is selected using \fBaudit_control\fR(4), the behavior of the
system with respect to the \fB-setpolicy\fR \fB+cnt\fR and the
\fB-setqhiwater\fR options is modified slightly. If \fB-setpolicy\fR \fB+cnt\fR
is set, data will continue to be sent to the selected plugin, even though
output to the binary audit log is stopped, pending the freeing of disk space.
If \fB-setpolicy\fR \fB-cnt\fR is used, the blocking behavior is as described
under OPTIONS, above. The value set for the queue high water mark is used
within \fBauditd\fR as the default value for its queue limits unless overridden
by means of the \fBqsize\fR attribute as described in \fBaudit_control\fR(4).
.sp
.LP
The \fBauditconfig\fR options that modify or display process-based information
are not affected by the \fBperzone\fR 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 \fBperzone\fR policy is set. The display of a system
audit reflects the local zone if \fBperzone\fR is set. Otherwise, it reflects
the settings of the global zone.
.sp
.LP
The \fB-setcond\fR option has been removed. Use \fBaudit\fR(1M) to enable or
disable auditing.
.sp
.LP
The \fB-getfsize\fR and \fB-setfsize\fR options have been removed. Use
\fBaudit_binfile\fR(5) \fBp_fsize\fR to set the audit file size.