xref: /freebsd/contrib/openbsm/man/audit_control.5 (revision bc168a6cdd45ba809a5580b6e67ebc6806b5aeb3)
1ca0716f5SRobert Watson.\" Copyright (c) 2004 Apple Computer, Inc.
24bd0c025SRobert Watson.\" Copyright (c) 2006 Robert N. M. Watson
3ca0716f5SRobert Watson.\" All rights reserved.
4ca0716f5SRobert Watson.\"
5ca0716f5SRobert Watson.\" Redistribution and use in source and binary forms, with or without
6ca0716f5SRobert Watson.\" modification, are permitted provided that the following conditions
7ca0716f5SRobert Watson.\" are met:
8ca0716f5SRobert Watson.\" 1.  Redistributions of source code must retain the above copyright
9ca0716f5SRobert Watson.\"     notice, this list of conditions and the following disclaimer.
10ca0716f5SRobert Watson.\" 2.  Redistributions in binary form must reproduce the above copyright
11ca0716f5SRobert Watson.\"     notice, this list of conditions and the following disclaimer in the
12ca0716f5SRobert Watson.\"     documentation and/or other materials provided with the distribution.
13ca0716f5SRobert Watson.\" 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
14ca0716f5SRobert Watson.\"     its contributors may be used to endorse or promote products derived
15ca0716f5SRobert Watson.\"     from this software without specific prior written permission.
16ca0716f5SRobert Watson.\"
17ca0716f5SRobert Watson.\" THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND
18ca0716f5SRobert Watson.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19ca0716f5SRobert Watson.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20ca0716f5SRobert Watson.\" ARE DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR
21ca0716f5SRobert Watson.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22ca0716f5SRobert Watson.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23ca0716f5SRobert Watson.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24ca0716f5SRobert Watson.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
25ca0716f5SRobert Watson.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
26ca0716f5SRobert Watson.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27ca0716f5SRobert Watson.\" POSSIBILITY OF SUCH DAMAGE.
28ca0716f5SRobert Watson.\"
29bc168a6cSRobert Watson.\" $P4: //depot/projects/trustedbsd/openbsm/man/audit_control.5#17 $
30ca0716f5SRobert Watson.\"
3123bf6e20SRobert Watson.Dd January 4, 2006
32ca0716f5SRobert Watson.Dt AUDIT_CONTROL 5
33ca0716f5SRobert Watson.Os
34ca0716f5SRobert Watson.Sh NAME
35ca0716f5SRobert Watson.Nm audit_control
36bc168a6cSRobert Watson.Nd "audit system parameters"
37ca0716f5SRobert Watson.Sh DESCRIPTION
38ca0716f5SRobert WatsonThe
39ca0716f5SRobert Watson.Nm
40ca0716f5SRobert Watsonfile contains several audit system parameters.
41ca0716f5SRobert WatsonEach line of this file is of the form:
4223bf6e20SRobert Watson.Pp
43bc168a6cSRobert Watson.D1 Ar parameter Ns : Ns Ar value
4423bf6e20SRobert Watson.Pp
45ca0716f5SRobert WatsonThe parameters are:
46bc168a6cSRobert Watson.Bl -tag -width indent
47bc168a6cSRobert Watson.It Va dir
48ca0716f5SRobert WatsonThe directory where audit log files are stored.
49ca0716f5SRobert WatsonThere may be more than one of these entries.
50ca0716f5SRobert WatsonChanges to this entry can only be enacted by restarting the
51ca0716f5SRobert Watsonaudit system.
52ca0716f5SRobert WatsonSee
53bc168a6cSRobert Watson.Xr audit 8
54ca0716f5SRobert Watsonfor a description of how to restart the audit system.
55ca0716f5SRobert Watson.It Va flags
56ca0716f5SRobert WatsonSpecifies which audit event classes are audited for all users.
57ca0716f5SRobert Watson.Xr audit_user 5
58ca0716f5SRobert Watsondescribes how to audit events for individual users.
59ca0716f5SRobert WatsonSee the information below for the format of the audit flags.
60ca0716f5SRobert Watson.It Va naflags
61ca0716f5SRobert WatsonContains the audit flags that define what classes of events are audited when
62ca0716f5SRobert Watsonan action cannot be attributed to a specific user.
63ca0716f5SRobert Watson.It Va minfree
64ca0716f5SRobert WatsonThe minimum free space required on the file system audit logs are being written to.
65ca0716f5SRobert WatsonWhen the free space falls below this limit a warning will be issued.
66ca0716f5SRobert WatsonNot currently used as the value of 20 percent is chosen by the kernel.
67bb97b418SRobert Watson.It Va policy
68bb97b418SRobert WatsonA list of global audit policy flags specifying various behaviors, such as
69bb97b418SRobert Watsonfail stop, auditing of paths and arguments, etc.
704bd0c025SRobert Watson.It Va filesz
714bd0c025SRobert WatsonMaximum trail size in bytes; if set to a non-0 value, the audit daemon will
724bd0c025SRobert Watsonrotate the audit trail file at around this size.
734bd0c025SRobert WatsonSizes less than the minimum trail size (default of 512K) will be rejected as
744bd0c025SRobert Watsoninvalid.
754bd0c025SRobert WatsonIf 0, trail files will not be automatically rotated based on file size.
76ca0716f5SRobert Watson.El
77ca0716f5SRobert Watson.Sh AUDIT FLAGS
7823bf6e20SRobert WatsonAudit flags are a comma-delimited list of audit classes as defined in the
79ca0716f5SRobert Watson.Xr audit_class 5
80bc168a6cSRobert Watsonfile.
81ca0716f5SRobert WatsonEvent classes may be preceded by a prefix which changes their interpretation.
82ca0716f5SRobert WatsonThe following prefixes may be used for each class:
8323bf6e20SRobert Watson.Pp
84bc168a6cSRobert Watson.Bl -tag -width indent -compact -offset indent
854bd0c025SRobert Watson.It (none)
86bc168a6cSRobert WatsonRecord both successful and failed events.
87bc168a6cSRobert Watson.It Li +
88bc168a6cSRobert WatsonRecord successful events.
89bc168a6cSRobert Watson.It Li -
90bc168a6cSRobert WatsonRecord failed events.
91bc168a6cSRobert Watson.It Li ^
92bc168a6cSRobert WatsonRecord neither successful nor failed events.
93bc168a6cSRobert Watson.It Li ^+
94bc168a6cSRobert WatsonDo not record successful events.
95bc168a6cSRobert Watson.It Li ^-
96bc168a6cSRobert WatsonDo not record failed events.
97ca0716f5SRobert Watson.El
98bb97b418SRobert Watson.Sh AUDIT POLICY FLAGS
99bb97b418SRobert WatsonThe policy flags field is a comma-delimited list of policy flags from the
100bb97b418SRobert Watsonfollowing list:
101bb97b418SRobert Watson.Pp
102bc168a6cSRobert Watson.Bl -tag -width ".Cm zonename" -compact -offset indent
103bc168a6cSRobert Watson.It Cm cnt
104bb97b418SRobert WatsonAllow processes to continue running even though events are not being audited.
105bb97b418SRobert WatsonIf not set, processes will be suspended when the audit store space is
106bb97b418SRobert Watsonexhausted.
107bb97b418SRobert WatsonCurrently, this is not a recoverable state.
108bc168a6cSRobert Watson.It Cm ahlt
109bc168a6cSRobert WatsonFail stop the system if unable to audit an event\[em]this consists of first
110bb97b418SRobert Watsondraining pending records to disk, and then halting the operating system.
111bc168a6cSRobert Watson.It Cm argv
112bb97b418SRobert WatsonAudit command line arguments to
113bb97b418SRobert Watson.Xr execve 2 .
114bc168a6cSRobert Watson.It Cm arge
115bb97b418SRobert WatsonAudit environmental variable arguments to
116bb97b418SRobert Watson.Xr execve 2 .
117bc168a6cSRobert Watson.It Cm seq
118bb97b418SRobert WatsonInclude a unique audit sequence number token in generated audit records (not
119bc168a6cSRobert Watsonimplemented on
120bc168a6cSRobert Watson.Fx
121bc168a6cSRobert Watsonor Darwin).
122bc168a6cSRobert Watson.It Cm group
123bb97b418SRobert WatsonInclude supplementary groups list in generated audit records (not implemented
124bc168a6cSRobert Watsonon
125bc168a6cSRobert Watson.Fx
126bc168a6cSRobert Watsonor Darwin; supplementary groups are never included in records on
127bb97b418SRobert Watsonthese systems).
128bc168a6cSRobert Watson.It Cm trail
129bc168a6cSRobert WatsonAppend a trailer token to each audit record (not implemented on
130bc168a6cSRobert Watson.Fx
131bc168a6cSRobert Watsonor
132bb97b418SRobert WatsonDarwin; trailers are always included in records on these systems).
133bc168a6cSRobert Watson.It Cm path
134bc168a6cSRobert WatsonInclude secondary file paths in audit records (not implemented on
135bc168a6cSRobert Watson.Fx
136bc168a6cSRobert Watsonor
137bb97b418SRobert WatsonDarwin; secondary paths are never included in records on these systems).
138bc168a6cSRobert Watson.It Cm zonename
139bc168a6cSRobert WatsonInclude a zone ID token with each audit record (not implemented on
140bc168a6cSRobert Watson.Fx
141bc168a6cSRobert Watsonor
142bc168a6cSRobert WatsonDarwin;
143bc168a6cSRobert Watson.Fx
144bc168a6cSRobert Watsonaudit records do not currently include the jail ID or name).
145bc168a6cSRobert Watson.It Cm perzone
146bc168a6cSRobert WatsonEnable auditing for each local zone (not implemented on
147bc168a6cSRobert Watson.Fx
148bc168a6cSRobert Watsonor Darwin; on
149bc168a6cSRobert Watson.Fx ,
150bc168a6cSRobert Watsonaudit records are collected from all jails and placed in a single
151bc168a6cSRobert Watsonglobal trail, and only limited audit controls are permitted within a jail).
152bb97b418SRobert Watson.El
153bb97b418SRobert Watson.Pp
154bb97b418SRobert WatsonIt is recommended that installations set the
155bc168a6cSRobert Watson.Cm cnt
156bb97b418SRobert Watsonflag but not
157bc168a6cSRobert Watson.Cm ahlt
158bb97b418SRobert Watsonflag unless it is intended that audit logs exceeding available disk space
159bb97b418SRobert Watsonhalt the system.
160ca0716f5SRobert Watson.Sh DEFAULT
161ca0716f5SRobert WatsonThe following settings appear in the default
162ca0716f5SRobert Watson.Nm
163ca0716f5SRobert Watsonfile:
164ca0716f5SRobert Watson.Bd -literal -offset indent
165ca0716f5SRobert Watsondir:/var/audit
16623bf6e20SRobert Watsonflags:lo
167ca0716f5SRobert Watsonminfree:20
168ca0716f5SRobert Watsonnaflags:lo
169bb97b418SRobert Watsonpolicy:cnt
1704bd0c025SRobert Watsonfilesz:0
171ca0716f5SRobert Watson.Ed
172ca0716f5SRobert Watson.Pp
173ca0716f5SRobert WatsonThe
174ca0716f5SRobert Watson.Va flags
175ca0716f5SRobert Watsonparameter above specifies the system-wide mask corresponding to login/logout
17623bf6e20SRobert Watsonevents.
177bb97b418SRobert WatsonThe
178bb97b418SRobert Watson.Va policy
179bb97b418SRobert Watsonparameter specifies that the system should neither fail stop nor suspend
180bb97b418SRobert Watsonprocesses when the audit store fills.
1814bd0c025SRobert WatsonThe trail file will not be automatically rotated by the audit daemon based on
1824bd0c025SRobert Watsonfile size.
183ca0716f5SRobert Watson.Sh FILES
184bc168a6cSRobert Watson.Bl -tag -width ".Pa /etc/security/audit_control" -compact
185ca0716f5SRobert Watson.It Pa /etc/security/audit_control
186ca0716f5SRobert Watson.El
187ca0716f5SRobert Watson.Sh SEE ALSO
188bc168a6cSRobert Watson.Xr audit 4 ,
189ca0716f5SRobert Watson.Xr audit_class 5 ,
190bc168a6cSRobert Watson.Xr audit_event 5 ,
19123bf6e20SRobert Watson.Xr audit_user 5 ,
19223bf6e20SRobert Watson.Xr audit 8 ,
19323bf6e20SRobert Watson.Xr auditd 8
194bc168a6cSRobert Watson.Sh HISTORY
195bc168a6cSRobert WatsonThe OpenBSM implementation was created by McAfee Research, the security
196bc168a6cSRobert Watsondivision of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
197bc168a6cSRobert WatsonIt was subsequently adopted by the TrustedBSD Project as the foundation for
198bc168a6cSRobert Watsonthe OpenBSM distribution.
199ca0716f5SRobert Watson.Sh AUTHORS
200bc168a6cSRobert Watson.An -nosplit
201ca0716f5SRobert WatsonThis software was created by McAfee Research, the security research division
202ca0716f5SRobert Watsonof McAfee, Inc., under contract to Apple Computer Inc.
203bc168a6cSRobert WatsonAdditional authors include
204bc168a6cSRobert Watson.An Wayne Salamon ,
205bc168a6cSRobert Watson.An Robert Watson ,
206bc168a6cSRobert Watsonand SPARTA Inc.
207ca0716f5SRobert Watson.Pp
208ca0716f5SRobert WatsonThe Basic Security Module (BSM) interface to audit records and audit event
209ca0716f5SRobert Watsonstream format were defined by Sun Microsystems.
210