Configuring Audit Logs (Tasks)

Two audit plugins, audit_binfile and audit_syslog, can create local audit logs. 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. Configuring logs for the audit_binfile plugin is optional. The logs for other plugins must be configured by an administrator.

Task	Description	For Instructions
Add local storage for the `audit_binfile` plugin.	Creates additional 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 streaming audit records to a remote system.	Enables you to send audit records to a remote repository through a protected mechanism.	How to Send Audit Files to a Remote Repository
Configure remote storage for audit files.	Enables you to receive audit records on a remote system.	How to Configure a Remote Repository for Audit Files
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 become an administrator who is assigned the ZFS File System Management and ZFS Storage Management rights profiles. The latter profile enables you to create storage pools. For more information, see How to Use Your Assigned 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 11.1 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 11.1 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 8. 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 11.1 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

The file system is unreachable without the passphrase, so the administrator saves it in a secure location.

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 become an administrator who is assigned the Audit Configuration rights profile. For more information, see How to Use Your Assigned 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 that an audit
     file can become before it is automatically closed and a new 
     audit file is opened. ... The format of the p_fsize value can 
     be specified as an exact value in bytes or in a human-readable
     form with a suffix of  B,  K, M, G, T, P, E, Z (for bytes, 
     kilobytes, megabytes, gigabytes, terabytes,  petabytes, exabytes,
     or zettabytes, respectively). Suffixes of KB, MB, GB, TB, PB, EB,
     and ZB are also accepted.

To add directories to the audit trail, specify the p_dir attribute.
The default file system is /var/audit.
```
# auditconfig -setplugin audit_binfile 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 p_fsize=4M
# auditconfig -getplugin audit_binfile
Plugin: audit_binfile
    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 4 GB, 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
    Attributes: p_dir=/var/audit;p_fsize=2G;p_minfree=1;
# auditconfig -setplugin audit_binfile "p_minfree=2;p_fsize=4G" 200
# auditconfig -getplugin audit_binfile
Plugin: audit_binfile
    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
    Attributes: p_dir=/var/audit;p_fsize=4G;p_minfree=2;
    Queue size: 200
# auditconfig -setplugin audit_binfile "" 0
# auditconfig -getplugin audit_binfile
 Plugin: audit_binfile
    Attributes: p_dir=/var/audit;p_fsize=4G;p_minfree=2;

The empty quotation marks ("") retain the current attribute values. The final 0 sets 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 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 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 of the audit_remote plugin to send the audit trail to a remote audit repository. To configure a remote repository on an Oracle Solaris system, see How to Configure a Remote Repository for Audit Files.

Before You Begin

You must have a receiver of audit files at your remote repository. You must become an administrator who is assigned the Audit Configuration rights profile. For more information, see How to Use Your Assigned Administrative Rights.

Determine the attributes of 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 receiving system, use the p_hosts attribute.
In this example, the receiving system uses a different port.
```
# auditconfig -setplugin audit_remote p_hosts=ars.example.com:16088:kerberos_v5
```
To change other attributes of the plugin, specify them.
For example, the following command specifies values for all optional attributes:
```
# auditconfig -setplugin audit_remote "p_retries=;p_timeout=3" 300
```

Verify the values, then activate the plugin.

For example, the following commands specify and verify the values of the plugin:

# auditconfig -getplugin audit_remote
Plugin: audit_remote (inactive)
    Attributes: p_hosts=ars.example.com:16088:kerberos_v5;p_retries=5;p_timeout=3;
    Queue size: 300
# auditconfig -setplugin audit_remote active

Refresh the audit service.
The audit service reads the audit plugin change upon refresh.
```
# audit -s
```

Example 28-18 Tuning the Audit Queue Buffer Size

In this example, the audit queue is full behind the audit_remote plugin. This audited system is configured to audit many classes and is transmitting across a high-traffic, slow network. The administrator enlarges the plugin's buffer size to enable the audit queue to grow and not exceed the buffer's limit before records are removed from the queue.

audsys1 # auditconfig -setplugin audit_remote "" 1000
audsys1 # audit -s

How to Configure a Remote Repository for Audit Files

In this procedure, you configure a remote system, the Audit Remote Server (ARS), to receive and store audit records from one or more audited systems. Then, you activate the audit daemon on the remote server.

The configuration is twofold. First, you configure the underlying security mechanisms to securely transport the audit data, that is, you configure the KDC. Second, you configure the audit service on both the audited system and the ARS. This procedure illustrates a scenario with one audited client and one ARS, where the ARS and the KDC are on the same server. More complex scenarios can be configured similarly.

Before You Begin

You must assume the root role. You have installed the Kerberos packages, as described in How to Prepare to Stream Audit Records to Remote Storage. You are working with an administrator who has configured the audited system, as described in How to Send Audit Files to a Remote Repository.

Configure the underlying security transport mechanism.

You need a KDC on a system that both the audited system and the ARS can use, a host principal for each system, and an audit service principal.

Configure the KDC.
If your site has configured a KDC, use it and continue with Step c. The following series of commands illustrate a KDC configuration strategy:
```
arstore # kdcmgr -a audr/admin -r EXAMPLE.COM create master
```
This command uses the administrative principal audr/admin to create a master KDC in the EXAMPLE.COM realm, enables the master KDC, and starts the Kerberos service.

Verify that the KDC is available.

For more information, see the kdcmgr(1M) man page.

# kdcmgr status
KDC Status Information
--------------------------------------------
svc:/network/security/krb5kdc:default (Kerberos key distribution center)
 State: online since Wed Feb 29 01:59:27 2012
   See: man -M /usr/share/man -s 1M krb5kdc
   See: /var/svc/log/network-security-krb5kdc:default.log
Impact: None.

KDC Master Status Information
--------------------------------------------
svc:/network/security/kadmin:default (Kerberos administration daemon)
 State: online since Wed Feb 29 01:59:28 2012
   See: man -M /usr/share/man -s 1M kadmind
   See: /var/svc/log/network-security-kadmin:default.log
Impact: None.

Transaction Log Information
--------------------------------------------

Kerberos update log (/var/krb5/principal.ulog)
Update log dump :
        Log version # : 1
        Log state : Stable
        Entry block size : 2048
        Number of entries : 13
        First serial # : 1
        Last serial # : 13
        First time stamp : Wed Feb 29 01:59:27 2012
        Last time stamp : Mon Mar 5 19:29:28 2012


Kerberos Related File Information
--------------------------------------------
(Displays any missing files)

Add the audit service principal to the KDC keytab file.
You can add the principal by typing the kadmin.local command on the KDC system. Or, you can remotely add the principal by using the kadmin command and providing a password. In this example, the arstore system is running the KDC.
```
# kadmin -p audr/admin
kadmin: addprinc -randkey audit/arstore.example.com@EXAMPLE.COM
kadmin: ktadd audit/arstore.example.com@EXAMPLE.COM
```

On each audited system, add keys.

The receiver and the sender must have keys.

enigma # kclient
        .. Enter the Kerberos realm: EXAMPLE.COM
        .. KDC hostname for the above realm: arstore.example.com
        .. Will this client need service keys ? [y/n]: y

Configure the audit service on the ARS.
- To create a group that accepts audit records from any audited system in the Kerberos realm, name a connection group.
```
# auditconfig -setremote group create Bank_A
```
  Bank_A is a connection group. Because the hosts attribute is not defined, this group accepts all connections, which means that it is a wildcard group. Any audited system in this Kerberos realm whose audit_remote plugin is correctly configured can reach this ARS.
- To limit connections to this group, specify the audited systems that can use this repository.
```
# auditconfig -setremote group Bank_A "hosts=enigma.example.com"
```
  Connection group Bank_A now accepts only connections from the enigma system. A connection from any other host is refused.
- To prevent an audit file in this group from growing too large, set a maximum size.
```
# auditconfig -setremote group Bank_A "binfile_size=4GB"
# auditconfig -getremote
Audit Remote Server
  Attributes: listen_address=;login_grace_time=30;max_startups=10;listen_port=0;
Connection group: Bank_A (inactive)
  Attributes: binfile_dir=/var/audit;binfile_fsize=4GB;binfile_minfree=1;
  hosts=enigma.example.com;
```

Configure the audit service on the audited system.

To specify the ARS, use the p_hosts attribute.

enigma # auditconfig -setplugin audit_remote active p_hosts=arstore.example.com
enigma # auditconfig -getplugin audit_remote
Plugin: audit_remote
      Attributes: p_retries=3;p_timeout=5;p_hosts=arstore.example.com;

Refresh the audit service.
The audit service reads the audit plugin change upon refresh.
```
# audit -s
```
The KDC now manages the connection between the audited system enigma and the ARS.

Example 28-19 Streaming Audit Records to Different File Locations on the Same ARS

This example extends the example in the procedure. The administrator separates audit records by host on the ARS by creating two connection groups.

Audit files from audsys1 stream to the Bank_A connection group on this ARS.

arstore # auditconfig  -setremote group create Bank_A
arstore # auditconfig -setremote group active Bank_A "hosts=audsys1"
     "hosts=audsys1;binfile_dir=/var/audit/audsys1;binfile_fsize=4M;"

Audit files from audsys2 stream to the Bank_B connection group.

arstore # auditconfig -setremote group create Bank_B
arstore # auditconfig -setremote group active Bank_B \
     "hosts=audsys2;binfile_dir=/var/audit/audsys2;binfile_fsize=4M;"

For easier maintenance, the administrator sets other attribute values identically.

arstore # auditconfig -getremote
Audit Remote Server
      Attributes: listen_address=;login_grace_time=30;max_startups=10;listen_port=0;

Connection group: Bank_A
      Attributes: binfile_dir=/var/audit/audsys1;binfile_fsize=4M;binfile_minfree=1;
      hosts=audsys1

Connection group: Bank_B
      Attributes: binfile_dir=/var/audit/audsys2;binfile_fsize=4M;binfile_minfree=1;
      hosts=audsys2

Example 28-20 Placing the ARS on a Different System From the KDC

In this example, the administrator places the ARS on a different system from the KDC. First, the administrator creates and configures the master KDC.

kserv # kdcmgr -a audr/admin -r EXAMPLE.COM create master
kserv # kadmin.local -p audr/admin
kadmin: addprinc -randkey audit/arstore.example.com@EXAMPLE.COM
kadmin: ktadd -t /tmp/krb5.keytab.audit audit/arstore.example.com@EXAMPLE.COM

After securely transmitting the /tmp/krb5.keytab.audit file to the ARS, arstore, the administrator moves the file to the correct location.

arstore # chown root:root krb5.keytab.audit
arstore # chmod 600 krb5.keytab.audit
arstore # mv krb5.keytab.audit /etc/krb5/krb5.keytab

Rather than rewrite the file, the administrator also has the option to use the ktutil command on the ARS to merge the KDC krb5.keytab.audit file with existing keys in the arstore's /etc/krb5/krb5.keytab file.

Finally, the administrator generates keys on the audited system.

enigma # kclient
   .. Enter the Kerberos realm: EXAMPLE.COM
   .. KDC hostname for the above realm: kserv.example.com
   .. Will this client need service keys ? [y/n]: y

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 become an administrator who is assigned the Audit Configuration rights profile. To configure the syslog utility and create the auditlog file, you must assume 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
```

Determine which system-log service instance is online.

# svcs system-log
STATE          STIME    FMRI
disabled       13:11:55 svc:/system/system-log:rsyslog
online         13:13:27 svc:/system/system-log:default

Note - If the rsyslog service instance is online, modify the rsyslog.conf file.

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 system-log service.
```
# svcadm refresh system-log:default
```
  Note - Refresh the system-log:rsyslog service instance if the rsyslog service is online.
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-21 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 utility collects successful and failed calls to the pfexec command. The syslog utility collects successful calls to the pfexec command.

Example 28-22 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 11.1 Administration: Security Services Oracle Solaris 11.1 Information Library