2 .\" Copyright (c) 2008-2009 Apple Inc.
3 .\" Copyright (c) 2005 Robert N. M. Watson
4 .\" Copyright (c) 2005 Tom Rhodes
5 .\" Copyright (c) 2005 Wayne J. Salamon
6 .\" All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" $P4: //depot/projects/trustedbsd/openbsm/man/auditon.2#18 $
36 .Nd "configure system audit parameters"
40 .Fn auditon "int cmd" "void *data" "u_int length"
44 system call is used to manipulate various audit control operations.
48 should point to a structure whose type depends on the command.
58 may be any of the following:
59 .Bl -tag -width ".It Dv A_GETPINFO_ADDR"
61 Set audit policy flags.
67 value set to one or more the following audit
68 policy control values bitwise OR'ed together:
75 .Dv AUDIT_CNT is set, the system will continue even if it becomes low
76 on space and discontinue logging events until the low space condition is
78 If it is not set, audited events will block until the low space
79 condition is remedied.
80 Unaudited events, however, are unaffected.
82 .Dv AUDIT_AHLT is set, a
84 if it cannot write an event to the global audit log file.
87 is set, then the argument list passed to the
89 system call will be audited. If
91 is set, then the environment variables passed to the
93 system call will be audited. The default policy is none of the audit policy
96 Set the host information.
102 structure containing the host IP address information.
103 After setting, audit records
104 that are created as a result of kernel events will contain
107 Set the kernel preselection masks (success and failure).
113 structure containing the mask values as defined in
115 These masks are used for non-attributable audit event preselection.
118 specifies which classes of successful audit events are to be logged to the
119 audit trail. The field
121 specifies which classes of failed audit events are to be logged. The value of
122 both fields is the bitwise OR'ing of the audit event classes specified in
124 The various audit classes are described more fully in
127 Set kernel audit queue parameters.
133 structure (defined in
135 containing the kernel audit queue control settings:
144 defines the maximum number of audit record entries in the queue used to store
145 the audit records ready for delivery to disk.
146 New records are inserted at the tail of the queue and removed from the head.
147 For new records which would exceed the
148 high water mark, the calling thread is inserted into the wait queue, waiting
149 for the audit queue to have enough space available as defined with the field
153 defines the maximum length of the audit record that can be supplied with
160 specifies the minimum amount of free blocks on the disk device used to store
162 If the value of free blocks falls below the configured
163 minimum amount, the kernel informs the audit daemon about low disk space.
164 The value is to be specified in percent of free file system blocks.
165 A value of 0 results in a disabling of the check.
166 The default and maximum values (default/maximum) for the
167 audit queue control parameters are:
169 .Bl -column aq_hiwater -offset indent -compact
170 .It aq_hiwater Ta 100/10000 (audit records)
171 .It aq_lowater Ta 10/aq_hiwater (audit records)
172 .It aq_bufsz Ta 32767/1048576 (bytes)
173 .It aq_delay Ta (Not currently used.)
188 Set the current auditing condition.
194 value containing the new
195 audit condition, one of
202 is set, then auditing is temporarily suspended. If
204 is set, auditing is resumed. If
206 is set, the auditing system will
207 shutdown, draining all audit records and closing out the audit trail file.
209 Set the event class preselection mask for an audit event.
215 structure containing the audit event and mask.
218 is the audit event and
220 is the audit class mask. See
222 for more information on audit event to class mapping.
224 Set the preselection masks for a process.
230 structure that contains the given process's audit
231 preselection masks for both success and failure.
234 is the process id of the target process.
239 structure which holds the preselection masks as described in the
243 Set the maximum size of the audit log file.
251 field set to the maximum audit log file size.
253 indicates no limit to the size.
255 Return the event to class mapping for the designated audit event.
263 section above for more information.
265 Get the current host information.
273 Return the audit settings for a process.
279 structure which will be set to contain
283 (the preselection mask),
285 (the terminal ID), and
287 (the audit session ID)
288 of the given target process.
289 The process ID of the target process is passed
290 into the kernel using the
297 for more information.
298 .It Dv A_GETPINFO_ADDR
299 Return the extended audit settings for a process.
304 .Vt auditpinfo_addr_t
305 structure which is similar to the
306 .Vt auditpinfo_addr_t
307 structure described above.
310 (the terminal ID) field which points to a
312 structure can hold much a larger terminal address and an address type.
313 The process ID of the target process is passed into the kernel using the
320 for more information.
321 .It Dv A_GETSINFO_ADDR
322 Return the extended audit settings for a session.
329 The audit session ID of the target session is passed
330 into the kernel using the
334 for more information about the
338 Return the current kernel preselection masks.
344 structure which will be set to
345 the current kernel preselection masks for non-attributable events.
347 Return the current audit policy setting.
353 value which will be set to
354 one of the current audit policy flags.
355 The audit policy flags are
360 Return the current kernel audit queue control parameters.
366 structure which will be set to the current
367 kernel audit queue control parameters.
370 section above for more information.
372 Returns the maximum size of the audit log file.
381 field will be set to the maximum audit log file size.
382 A value of 0 indicates no limit to the size.
386 will be set to the current audit log file size.
388 .\" [COMMENTED OUT]: Valid description, not yet implemented.
389 .\" Return the current working directory as stored in the audit subsystem.
394 .\" [COMMENTED OUT]: Valid description, not yet implemented.
395 .\"Stores and returns the current active root as stored in the audit
401 .\" [COMMENTED OUT]: Valid description, not yet implemented.
402 .\"Return the statistics stored in the audit system.
407 Return the current auditing condition.
413 value which will be set to
414 the current audit condition, one of
421 section above for more information.
423 Send a trigger to the audit daemon.
429 value set to one of the acceptable
431 .Dv AUDIT_TRIGGER_LOW_SPACE
432 (low disk space where the audit log resides),
433 .Dv AUDIT_TRIGGER_OPEN_NEW
434 (open a new audit log file),
435 .Dv AUDIT_TRIGGER_READ_FILE
439 .Dv AUDIT_TRIGGER_CLOSE_AND_DIE
440 (close the current log file and exit),
441 .Dv AUDIT_TRIGGER_NO_SPACE
442 (no disk space left for audit log file).
443 .Dv AUDIT_TRIGGER_ROTATE_USER
444 (request audit log file rotation).
445 .Dv AUDIT_TRIGGER_INITIALIZE
446 (initialize audit subsystem for Mac OS X only).
448 .Dv AUDIT_TRIGGER_EXPIRE_TRAILS
449 (request audit log file expiration).
456 function will fail if:
459 Returned by options not yet implemented.
461 A failure occurred while data transferred to or from
464 Illegal argument was passed by a system call.
466 The process does not have sufficient permission to complete
472 command is specific to the
474 and Mac OS X implementations, and is not present in Solaris.
479 .Xr getaudit_addr 2 ,
482 .Xr setaudit_addr 2 ,
486 The OpenBSM implementation was created by McAfee Research, the security
487 division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004.
488 It was subsequently adopted by the TrustedBSD Project as the foundation for
489 the OpenBSM distribution.
492 This software was created by McAfee Research, the security research division
493 of McAfee, Inc., under contract to Apple Computer Inc.
494 Additional authors include
499 The Basic Security Module (BSM) interface to audit records and audit event
500 stream format were defined by Sun Microsystems.
502 This manual page was written by
503 .An Tom Rhodes Aq trhodes@FreeBSD.org ,
504 .An Robert Watson Aq rwatson@FreeBSD.org ,
506 .An Wayne Salamon Aq wsalamon@FreeBSD.org .