Configuring Audit Logs (Tasks)

Two audit plugins, audit_binfile and audit_syslog, send audit logs to locations that you can configure. The following tasks help you configure these logs.

Configuring Audit Logs (Task Map)

The following task map points to the procedures for configuring audit logs for the various plugins. All tasks are optional.

Task	Description	For Instructions
Add local storage for the `audit_binfile` plugin.	Creates local disk space for the audit files and protects them with file permissions.	How to Create ZFS File Systems for Audit Files
Assign storage for the `audit_binfile` plugin.	Identifies directories for binary audit records.	How to Assign Audit Space for the Audit Trail
Configure storage for the `audit_remote` plugin.	Enables you to send audit records to a remote repository through a protected mechanism.	How to Send Audit Files to a Remote Repository
Configure storage for the `audit_syslog` plugin.	Enables you to stream audit events in text format to `syslog`.	How to Configure `syslog` Audit Logs

How to Create ZFS File Systems for Audit Files

The following procedure shows how to create a ZFS pool for audit files, as well as the corresponding file systems and mount point. By default, the /var/audit file system holds audit files for the audit_binfile plugin.

Before You Begin

You must be assigned the ZFS File System Management and ZFS Storage Management rights profiles. The latter profile enables you to create storage pools.

Become an administrator with the required security attributes.
For more information, see How to Obtain Administrative Rights.
Determine the amount of disk space that is required.
Assign at least 200 MB of disk space per host. However, how much auditing you require dictates the disk space requirements. So, your disk space requirements might be far greater than this figure.

Note - The default class preselection creates files in /var/audit that grow by about 80 bytes for every recorded instance of an event in the lo class, such as a login, logout, or role assumption.
Create a mirrored ZFS storage pool.
The zpool create command creates a storage pool that is a container for the ZFS file systems. For more information, see Chapter 1, Oracle Solaris ZFS File System (Introduction), in Oracle Solaris Administration: ZFS File Systems.
```
# zpool create audit-pool mirror disk1 disk2
```
For example, create the auditp pool from two disks, c3t1d0 and c3t2d0, and mirror them.
```
# zpool create auditp mirror c3t1d0 c3t2d0
```
Create a ZFS file system and mount point for the audit files.
You create the file system and mount point with one command. At creation, the file system is mounted. For example, the following illustration shows audit trail storage that is stored by host name.

Note - If you plan to encrypt the file system, you must encrypt the file system at creation. For an example, see Example 28-12.
Encryption requires management. For example, a passphrase is required at mount time. For more information, see Encrypting ZFS File Systems in Oracle Solaris Administration: ZFS File Systems.
```
# zfs create -o mountpoint=/mountpoint audit-pool/mountpoint
```
For example, create the /audit mount point for the auditf file system.
```
# zfs create -o mountpoint=/audit auditp/auditf
```
Create a ZFS file system for the audit files.
```
# zfs create -p auditp/auditf/system
```
For example, create an unencrypted ZFS file system for the sys1 system.
```
# zfs create -p auditp/auditf/sys1
```
(Optional) Create additional file systems for audit files.
One reason to create additional file systems is to prevent audit overflow. You can set a ZFS quota per file system, as shown in Step 9. The audit_warn email alias notifies you when each quota is reached. To free space, you can move the closed audit files to a remote server.
```
# zfs create -p auditp/auditf/sys1.1
# zfs create -p auditp/auditf/sys1.2
```
Protect the parent audit file system.
The following ZFS properties are set to off for all file systems in the pool:
```
# zfs set devices=off auditp/auditf
# zfs set exec=off auditp/auditf
# zfs set setuid=off auditp/auditf
```
Compress the audit files in the pool.
Typically, compression is set in ZFS at the file system level. However, because all the file systems in this pool contain audit files, compression is set at the top-level dataset for the pool.
```
# zfs set compression=on auditp
```
See also Interactions Between ZFS Compression, Deduplication, and Encryption Properties in Oracle Solaris Administration: ZFS File Systems.
Set quotas.
You can set quotas at the parent file system, the descendant file systems, or both. If you set a quota on the parent audit file system, quotas on the descendant file systems impose an additional limit.
1. Set a quota on the parent audit file system.
  In the following example, when both disks in the auditp pool reach the quota, the audit_warn script notifies the audit administrator.
```
# zfs set quota=510G auditp/auditf
```
2. Set a quota on the descendant audit file systems.
  In the following example, when the quota for the auditp/auditf/system file system is reached, the audit_warn script notifies the audit administrator.
```
# zfs set quota=170G auditp/auditf/sys1
# zfs set quota=170G auditp/auditf/sys1.1
# zfs set quota=165G auditp/auditf/sys1.2
```
For a large pool, limit the size of the audit files.
By default, an audit file can grow to the size of the pool. For manageability, limit the size of the audit files. See Example 28-14.

Example 28-12 Creating an Encrypted File System for Audit Files

To comply with site security requirements, the administrator creates the audit file system with encryption turned on. Then, the administrator sets the mount point.

# zfs create -o encryption=on auditp/auditf
Enter passphrase for auditp/auditf': /** Type 8-character minimum passphrase**/
Enter again: /** Confirm passphrase **/
# zfs set -o mountpoint=/audit auditp/auditf

When the administrator creates additional file systems under the auditf file system, these descendant file systems are also encrypted.

Example 28-13 Setting a Quota on the /var/audit Directory

In this example, the administrator sets a quota on the default audit file system. When this quota is reached, the audit_warn script warns the audit administrator.

# zfs set quota=252G rpool/var/audit

How to Assign Audit Space for the Audit Trail

In this procedure, you use attributes to the audit_binfile plugin to assign additional disk space to the audit trail.

Before You Begin

You must be assigned the Audit Configuration rights profile.

Become an administrator with the required security attributes.
For more information, see How to Obtain Administrative Rights.

Determine the attributes to the audit_binfile plugin.

Read the OBJECT ATTRIBUTES section of the audit_binfile(5) man page.

# man audit_binfile
...
OBJECT ATTRIBUTES
     The p_dir attribute specifies where the audit files will be
     created. The directories are listed in the order in which
     they are to be used.
     
     The p_minfree attribute defines the percentage of free space
     that the audit system requires before the audit daemon invokes
     the audit_warn script.

     The p_fsize attribute defines the maximum size in bytes that
     an  audit  file can become before it is automatically closed
     and a new audit file  opened.  ...

To add directories to the audit trail, specify the p_dir attribute.
The default file system is /var/audit.
```
# auditconfig -setplugin audit_binfile active p_dir=/audit/sys1.1,/var/audit
```
The preceding command sets the /audit/sys1.1 file system as the primary directory for audit files and the default /var/audit file system as the secondary directory. In this scenario, /var/audit is the directory of last resort. For this configuration to succeed, the /audit/sys1.1 file system must exist.
You created a similar file system in How to Create ZFS File Systems for Audit Files.
Refresh the audit service.
The auditconfig -setplugin command sets the configured value. This value is a property of the audit service, so is restored when the service is refreshed or restarted. The configured value becomes active when the audit service is refreshed or restarted. For information about configured and active values, see the auditconfig(1M) man page.
```
# audit -s
```

Example 28-14 Limiting File Size for the audit_binfile Plugin

In the following example, the size of a binary audit file is set to a specific size. The size is specified in megabytes.

# auditconfig -setplugin audit_binfile active p_fsize=4M
# auditconfig -getplugin audit_binfile
Plugin: audit_binfile (active)
    Attributes: p_dir=/var/audit;p_fsize=4M;p_minfree=1;

By default, an audit file can grow without limit. To create smaller audit files, the administrator specifies a file size limit of 4MB. The audit service creates a new file when the size limit is reached. The file size limit goes into effect after the administrator refreshes the audit service.

# audit -s

Example 28-15 Specifying Several Changes to an Audit Plugin

In the following example, the administrator on a system with high throughput and a large ZFS pool changes the queue size, the binary file size, and the soft limit warning for the audit_binfile plugin. The administrator allows audit files to grow to 4GB, is warned when 2 percent of the ZFS pool remains, and doubles the allowed queue size. The default queue size is the high water mark for the kernel audit queue, 100, as in active audit queue hiwater mark (records) = 100.

# auditconfig -getplugin audit_binfile
Plugin: audit_binfile (active)
    Attributes: p_dir=/var/audit;p_fsize=2G;p_minfree=1;
# auditconfig -setplugin audit_binfile active "p_minfree=2;p_fsize=4G" 200
# auditconfig -getplugin audit_binfile
Plugin: audit_binfile (active)
    Attributes: p_dir=/var/audit;p_fsize=4G;p_minfree=2;
    Queue size: 200

The changed specifications go into effect after the administrator refreshes the audit service.

# audit -s

Example 28-16 Removing Queue Size for an Audit Plugin

In the following example, the queue size for the audit_binfile plugin is removed.

# auditconfig -getplugin audit_binfile
Plugin: audit_binfile (active)
    Attributes: p_dir=/var/audit;p_fsize=4G;p_minfree=2;
    Queue size: 200
# auditconfig -setplugin audit_binfile active "" ""
# auditconfig -getplugin audit_binfile
 Plugin: audit_binfile (active)
    Attributes: p_dir=/var/audit;p_fsize=4G;p_minfree=2;

The final empty quotation marks ("") set the queue size for the plugin to the default.

The change in qsize specification for the plugin goes into effect after the administrator refreshes the audit service.

# audit -s

Example 28-17 Setting a Soft Limit for Warnings

In this example, the minimum free-space level for all audit file systems is set so that a warning is issued when two percent of the file system is still available.

# auditconfig -setplugin audit_binfile active p_minfree=2

The default percentage is one (1). For a large ZFS pool, choose a reasonably low percentage. For example, 10 percent of a 16 TB pool is around 16 GB, which would warn the audit administrator when plenty of disk space remains. A value of 2 sends the audit_warn message when about two GB of disk space remains.

The audit_warn email alias receives the warning. To set up the alias, see How to Configure the audit_warn Email Alias.

For a large pool, the administrator also limits the file size to 3 GB.

# auditconfig -setplugin audit_binfile active p_fsize=3G

The p_minfree and p_fsize specifications for the plugin go into effect after the administrator refreshes the audit service.

# audit -s

How to Send Audit Files to a Remote Repository

In this procedure, you use attributes to the audit_remote plugin to send the audit trail to a remote audit repository.

Before You Begin

You must have a receiver of audit files at your remote repository. You must be assigned the Audit Configuration rights profile.

Become an administrator with the required security attributes.
For more information, see How to Obtain Administrative Rights.

Determine the attributes to the audit_remote plugin.

Read the OBJECT ATTRIBUTES section of the audit_remote(5) man page.

# man audit_remote
...
OBJECT ATTRIBUTES
     The p_hosts attribute specifies the remote servers.
     You can also specify the port number and the GSS-API
     mechanism.
     
     The p_retries attribute specifies the number of retries for
     connecting and sending data. The default is 3.

     The p_timeout attribute specifies the number of seconds
     in which a connection times out.

The default port is the solaris_audit IANA-assigned port, 16162/tcp. The default mechanism is kerberos_v5. The timeout default is 5 seconds. You can also specify a queue size for the plugin.

To specify the remote hosts, use the p_hosts attribute.

# auditconfig -setplugin audit_remote active p_hosts=rhost1:16088:kerberos_v5

To specify the number of retries, use the p_retries attribute.
```
# auditconfig -setplugin audit_remote active p_retries=5
```
To specify the length of a connection timeout, use the p_timeout attribute.
```
# auditconfig -setplugin audit_remote active p_timeout=3
```
Refresh the audit service.
The audit service reads the audit plugin change upon refresh.
```
# audit -s
```

How to Configure `syslog` Audit Logs

You can instruct the audit service to copy some or all of the audit records in the audit queue to the syslog utility. If you record both binary audit data and text summaries, the binary data provide a complete audit record, while the summaries filter the data for real-time review.

Before You Begin

To configure the audit_syslog plugin, you must be assigned the Audit Configuration rights profile. To configure the syslog utility, you must be in the root role.

Select audit classes to be sent to the audit_syslog plugin, and make the plugin active.
Note - p_flags audit classes must be preselected as either system defaults or in a user's or a rights profile's audit flags. Records are not collected for a class that is not preselected.
```
# auditconfig -setplugin audit_syslog active p_flags=lo,+as,-ss
```
Configure the syslog utility.
1. Add an audit.notice entry to the syslog.conf file.
  The entry includes the location of the log file.
```
# cat /etc/syslog.conf
…
audit.notice       /var/adm/auditlog
```
2. Create the log file.
```
# touch /var/adm/auditlog
```
3. Refresh the configuration information for the syslog service.
```
# svcadm refresh system/system-log
```
Refresh the audit service.
The audit service reads the changes to the audit plugin upon refresh.
```
# audit -s
```
Regularly archive the syslog log files.
The audit service can generate extensive output. To manage the logs, see the logadm(1M) man page.

Example 28-18 Specifying Audit Classes for syslog Output

In the following example, the syslog utility collects a subset of the preselected audit classes. The pf class is created in Example 28-10.

# auditconfig -setnaflags lo,na
# auditconfig -setflags lo,ss
# usermod -K audit_flags=pf:no jdoe
# auditconfig -setplugin audit_syslog active p_flags=lo,+na,-ss,+pf

The arguments to the auditconfig command instruct the system to collect all login/logout, non-attributable, and change of system state audit records. The audit_syslog plugin entry instructs the syslog utility to collect all logins, successful non-attributable events, and failed changes of system state.

For the jdoe user, the binary audit record includes all uses of a call to the pfexec command. For these events to be available for post-selection, either the audit_binfile or the audit_remote plugin must be active. The syslog utility collects successful calls to the pfexec command.

Example 28-19 Putting syslog Audit Records on a Remote System

You can change the audit.notice entry in the syslog.conf file to point to a remote system. In this example, the name of the local system is sys1.1. The remote system is remote1.

sys1.1 # cat /etc/syslog.conf
…
audit.notice       @remote1

The audit.notice entry in the syslog.conf file on the remote1 system points to the log file.

remote1 # cat /etc/syslog.conf
…
audit.notice       /var/adm/auditlog

Skip Navigation Links
Exit Print View
	Oracle Solaris Administration: Security Services Oracle Solaris 11 Information Library