NAME

audit − controls auditing facilities

SYNOPSIS

audit  [-B] [-T] [-S] [-I] [-Q] [-D]
[-s {on|off}]
[-f {on|off}]
[-o {on|off}]
[-w {on|off}]
[-m {on|off}]
[-p {on|off}]
[-t {pct_total%t | pct_free%f | rem_blocks},block_increment]
[-a file[:size[:date/time]][,file[:size[:date/time]] ...]
[-r file[,file] ...]
[-u user[,user] ...]
[-d user[,user] ...]

DESCRIPTION

audit enables root to monitor and control the functions of the audit system.  Commands are passed to the audit daemon (audit_d(1M)) to change the state of the system and to query its current state.  The audit command options provide the following capabilities:

Starts and stops system auditing. 

Specifies a list of audit files, the maximum size for each file, and a "use before" date and time, Also, automatically switches through the list of files, and overwrites the existing audit file. 

Causes the audit trail recording to seamlessly switch to the next file in the audit file list. 

Sets the configuration options for the logging of additional associated audit event information. 

Specifies that a warning notice be sent to a list of users by either displaying it on their terminals or mailing it to them. 

Sets the file system fullness threshold at which an initial warning message is issued and the increment at which additional warning messages are issued. 

Specifies whether the system should be shutdown when auditing can no longer be performed. 

Initializes the audit daemon to its default startup state. 

Queries the audit daemon to determine the state of the audit system. 

The options supplied to the audit command are executed in the order in which they are presented on the command line.  The valid options are:

-B Begins auditing if the audit system is not already active.  An audit file must already be selected. 

-T Terminates auditing if the audit system is active.  The currently selected audit file remains selected. 

-S Switches the current audit file to the next file in the audit file list.  This will fail if (1) file switching is not enabled, (2) there is no audit file to switch to (i.e., the audit file list has only one file in it), or (3) auditing is not active. 

-I Causes the audit daemon to reinitialize itself to its default startup state.  Auditing will be terminated if active, the audit file list will be emptied, and the user list will be emptied.  The user is prompted to ensure that this is a desired action. 

-Q Requests that the audit daemon display the complete state of the audit system, including the value of all options and lists.  A shorter state display can be requested by simply issuing audit with no options. 

-D Generates a listing showing the contents of the daemon last-state file (/usr/spool/audit/last_state).  Note that this is not the same as the -Q option, which shows the complete status, including how full the audit files and file systems are.  The daemon need not be running to use this option. 

-s Determines whether the system is to be shutdown if auditing can no longer be performed.  The parameter on causes immediate shutdown if auditing cannot be performed; the parameter off turns off auditing and allows the system to continue operation.  The default value is on. 

-f Allows the audit daemon to switch active (selected) audit files taken from the audit file list whenever the currently selected audit file reaches its size limit or its date/time limit.  When a file switch occurs, the previously active audit file is removed from the list.  If the -f option is not set, the actions defined by -o and/or -s will occur when auditing cannot proceed with the current audit file.  The parameter on enables file switching, and the parameter off disables file switching. 

-o Controls whether the last file specified in the audit file list will be overwritten when it fills.  If overwrite is enabled by the on option, when the file system fills up so that audit records can no longer be recorded, auditing will continue at the start of the currently selected file, causing the loss of all auditing data previously recorded in that file.  An overwrite record will be inserted at the beginning of the file to show that overwriting took place.  If overwrite is disabled by the off parameter, auditing will stop (and the system will take the action specified by the -s option) when the last file is filled. 

-w Causes the audit daemon to send a message to the screen of all the users who are in the user list and currently logged in whenever the audit daemon initiates a serious warning message.  The parameter on enables this option; off disables it.  Warnings are always displayed on the system console.  If the same user is logged in on several terminals, the warning will be displayed on all of those terminals.  All warnings, regardless of severity, are also recorded in the audit history log /usr/spool/audit/audit_log. 

-m Causes the audit daemon to send a mail message (using mail(1)) to all the users in the user list who do not receive warning messages (either because they are not logged in or because their terminals cannot be written to), whenever the audit daemon initiates a warning message.  The parameter on enables this option; off disables it.  If the -w option is set off and the -m option is set on, all users in the user list will receive mail. 

-p Causes all audit events associated with failed password entries to log the bad password into the audit trail.  The parameter on enables this option; off disables it.  If this option is disabled, audit events regarding bad passwords will be generated without including the passwords. 

-t Controls the point at which file system full warnings will begin.  This is known as the warning threshold.  This option also determines the setting of the action threshold, the point at which the audit daemon will attempt to switch to a new file if file switching is enabled, overwrite the current file if overwriting is enabled, or stop auditing and potentially shut down the system.  The action threshold is a minimum of 100 blocks free in the file system and may be greater, as described below. 

Throughout the following discussion, file system refers to the file system containing the currently active audit file.  Block refers to a 512-byte block, regardless of the underlying file system block size. 

The audit daemon generates warnings when it determines that the file system is nearly full.  The warning threshold can be set in one of three ways:

1.  As an absolute number of free blocks in the file system

2.  As a percentage of the total file system size

3.  As a percentage of the free space in the file system when the audit file is started

  The warning threshold value is followed by the increment value.  The increment value provides an absolute number of blocks at which additional warnings are generated. 

To use an absolute number of free blocks as the warning threshold, the first value following the -t option is the free block count.  The threshold can be any positive value greater than the action threshold.  If this type of warning threshold is used, then the action threshold will be 100 free blocks.  For example, to generate the first warning when the file system drops to 2,000 free blocks, with subsequent warnings every 20 blocks, the option -t 2000,20 would be specified.  When the file system reaches 100 free blocks, the daemon will take the actions prescribed by the -s and -o options. 

To use a percentage of the total file system size as the warning threshold, the first value following the -t option is the percentage, followed by the characters %t (for percent total).  If this type of warning threshold is used, then the action threshold will be set to 98% of the total file system size.  The warning threshold percentage can be any positive value less than the action threshold.  For example, to generate the first warning when 90% of the total space in the file system is used, with subsequent warnings every 40 blocks, the option -t 90%t,40 would be specified.  When the file system reaches 98% full, the daemon will take the actions prescribed by the -s and -o options. 

To use a percentage of file system free space as the warning threshold, the first value following the -t option is the percentage, followed by the characters %f (for percent free).  If this type of warning threshold is used, then the action threshold will be set to 98% of the file system free space whenever the warning threshold is calculated (see below).  The warning threshold percentage can be any positive value less than the action threshold.  The warning threshold is calculated as a percentage of the free space in the file system at the time when the audit file is started, or when the -t option is used to change the warning threshold while auditing is enabled.  Thus, reexecuting the audit command with the same -t parameters can cause the block count at which warnings will begin to change as the file system fills up. 

An example of setting the warning threshold to a percentage of the file system free space is as follows.  If auditing is running and the option -t 93%f,60 is specified, then the warning threshold will be set to 93% of file system free space.  If the file system has 10,000 free blocks at that time, warnings will begin when 700 free blocks (7% of 10,000 blocks) remain in the file system.  Normally, decreasing the threshold increases the absolute number of blocks used as the warning level.  However, if some time later the file system free space drops to 5,000 free blocks and audit is executed with the option -t 90%f,80, then the warning threshold will decrease to 500 free blocks (10% of 5,000 blocks), even though the warning threshold percentage decreased from 93% to 90%. 

The default values are equivalent to specifying -t 95%t,5.  This will produce an initial warning when 95% of the total file system space has been used and subsequent warnings every five blocks thereafter. 

For further information on how the audit daemon decides when to switch to a new file or how to terminate auditing, see the audit_d(1M) manual page. 

-a Adds a file to the end of the audit file list or modify the expiration date and size limit associated with the file.  The first optional parameter specifies the maximum size (in 512-byte blocks) that the file is allowed to grow to.  The second optional parameter specifies a date and time at which this file is to be closed.  If either of these limits is reached, then the action taken will be dependent upon the other options currently set.  The format for the date/time is either hhmm or mmddhhmm[yy].  The year, month, and day default to the current date.  If the file does not exist when selected, it is created.  If the file already exists in the audit file list, the parameters are replaced if specified.  At most, 40 files may be in the audit file list. 

If the file is already on the list, the expiration date and file size will be updated if they are specified.  To remove the expiration date, use a 0 (zero) as the expiration date value.  To remove the file size limit, use a 0 for that value. 

If the file does not exist, it will be created when it reaches the head of the list. 

-r Removes a file from the audit file list.  If auditing is active and the file to be removed is the currently selected audit file, it will not be removed.  To remove the currently selected file, use the -S option; this will remove the current file and cause a switch to the next available file. 

-u Adds a username to the user list.  If the username is already in the user list, it will be ignored.  If the username is not in the /etc/shadow file, the request will be rejected.  At most, 40 user names may be in the user list. 

-d Deletes a username from the user list. 

If no options are specified, a short display of the current state of the audit system will be presented.  This display will include whether the audit system is active, the current audit file selected, its optional parameters, its current size, the state of file switching, end-of-auditing action (shutdown or not), message notification, and mail notification. 

Option processing is performed in two passes.  The first pass verifies that the options are syntactically correct; the second pass verifies the semantic correctness and executes the operations.  In the first pass, all options are processed, even if an error is detected during option processing.  Errors detected in this phase include invalid options, missing or incorrect spellings of parameters, and some invalid parameter values (including range checking and use of non-numeric characters where numeric values are expected).  Note that invalid user names or filenames are considered semantic errors and are not detected until the second pass.  If no syntactic errors are found, the second pass is performed. 

In the second (semantic) pass, options are executed in the exact order in which they appear on the command line.  Thus, a fatal error prevents the execution of any option following the failed option.  Also, the success of a particular option depends upon the current state of the audit system.  For example, if the overwrite option is enabled, file switching is disabled and the currently selected audit file will be overwritten when it fills even though there may be additional files in the audit file list.  The file will also continue to be used even though the expiration date/time has been exceeded. 

There is one exception to the above rules: the -D option is processed locally by the audit command as it is encountered in the first pass.  Thus, the -D option displays the state when the audit command starts, not the state as modified by prior options. 

The currently selected file is defined to be the file at the head of the audit file list. 

Only one audit command may be running at any given time.  The lock file /usr/spool/audit/ALOCK is used to prevent more than one copy of the command from running.  This file is removed automatically by the audit daemon as part of its startup procedure and upon completion of an audit command. 

FILES

/usr/spool/audit/CFIFO FIFO to send commands to the audit daemon

/usr/spool/audit/RFIFO FIFO to get responses from the audit daemon

/usr/spool/audit/ALOCK Lock file for the audit command

/usr/spool/audit/DLOCK Lock file for the audit daemon

/usr/spool/audit/last_state Last state of the audit daemon

SEE ALSO

audit_d(1M), au_ctl(3A), audit_sys(5)

NOTES

Setting the -o (overwrite) option to on is strongly discouraged, as it may lead to loss of auditing data. 

Setting the -s (shutdown) option to off is strongly discouraged, as it may lead to unaudited events if auditing files fill up. 

Auditing files should be on a separate file system to reduce the likelihood of the file system being filled (hence, a potential system shutdown) due to user actions. 

DIAGNOSTICS

Following are the exit codes possible from audit:

0 OK. 

1 User is not root. 

2 Could not create lock file. 

3 Fatal syntax error in command processing. 

4 Could not create link to audit daemon. 

5 Could not send command to audit daemon. 

6 Could not get response from audit daemon. 

7 Could not remove lock file. 

8 Format error in response. 

9 Command processing aborted by audit_d. 

10 Unexpected signal received. 

Diagnostics messages are intended to be self-explanatory. 

(Security Enhancement)