The onaudit utility: Configure auditing

Use the onaudit utility to start, stop, and configure auditing.

Syntax


1  onaudit?   -l audit_mode?   -e error_mode?   -p auditdir?   -R row_mode?   -s maxsize?   -c?   -n
Element Purpose Key Considerations
-c Shows the current audit configuration as the values of the auditing configuration parameter in the ADTCFG file. None.
-e error_mode Specifies the error-handling method for auditing when a record cannot be written to the audit file or event log:
  • 0 = Continue processing the thread and record the error in the message log. Errors for subsequent attempts to write to the audit file are also sent to the message log.
  • 1 = Suspend processing a thread when the database server cannot write a record to the current audit file. The database server attempts to write the record until it succeeds.
  • 3 = Shut down the server.
This option sets the ADTERR configuration parameter in the ADTCFG file.

You can use this option only when auditing is enabled.

-l audit_mode Specifies the audit mode:
  • 0 = Disable auditing
  • 1 = Audit all sessions
  • 3 = Audit DBSSO actions
  • 5 = Audit database server administrator actions
  • 7 = Audit DBSSO and database server administrator actions
This option sets the ADTMODE configuration parameter in the ADTCFG file.
-n Starts a new audit file. You can use this option only when auditing is enabled.
-p auditdir Specifies a new directory in which the database server creates audit files. The change occurs with the next write attempt. The database server creates a new audit file in the new directory, beginning with the first available number that is equal to or greater than 0. This option sets the ADTPATH configuration parameter in the ADTCFG file.

You can use this option only when auditing is enabled.

-R row_ mode Controls selective row-level auditing:
  • 0 = Selective row-level auditing is disabled.
  • 1 = Selective row-level auditing is enabled for tables that are set with the AUDIT flag.
  • 2 = Selective row-level auditing is enabled for tables that are set with the AUDIT flag. The primary key, if it is an integer data type, is included in the audit records.
This option sets the ADTROWS configuration parameter in the ADTCFG file.
-s maxsize Specifies the maximum size (in bytes) of an audit file. Can be any value between 10,240 bytes and approximately 2 gigabytes (the maximum value of a 32-bit integer). If you specify a size that is less than the minimum, the size is set automatically to the minimum value. When an audit file reaches or exceeds the maximum size, the database server closes the current file and starts a new audit file. This option sets the ADTSIZE configuration parameter in the ADTCFG file.

You can use this option only when auditing is enabled.

Usage

Before you try to run the onaudit utility, ensure that the server is running, that an audit mask with defined audit events has been added, and that you hold the AAO role.

All the options of this utility must be entered as shown because they are case-sensitive.

The onaudit command takes effect immediately for all new and existing user sessions.

To enable auditing for a high-availability cluster, you must enable auditing on the primary server and on every secondary server in the cluster. The audit mask must be created on the primary server. All of the servers in the cluster use the audit mask set on the primary server. Audit records for insert, update, and delete operations are created only on the primary server.

You can start auditing by using the onaudit command with the -l option set to a positive value. You can specify whether to limit auditing to certain tables by using the -R option. A new audit file is created when you enable auditing. When you start auditing with the onaudit command, the audit file size, the error mode, and the audit file directory information in the ADTCFG file is used.

You can stop auditing by using the onaudit -l 0 command. The database server stops auditing all existing sessions, and does not audit new sessions.

You can view the current audit configuration by using the onaudit -c command. That command displays the contents of the ADTCFG file.

You can dynamically change the behavior of auditing by using the onaudit command with any of its options.

You can use the -n option to create a new audit file:

  • For database server-managed auditing, the onaudit utility closes the current database server audit file, stores it in the specified directory, and creates a new audit file named servername.integer. The servername value is the name of the database server being audited, and integer is the next available integer. For example, if the last audit file saved for the maple database server was maple.123, the next audit file is maple.124.
  • For operating-system-managed files, the onaudit utility closes the current operating-system audit file, stores it as part of the operating-system audit trail, and creates a new audit file. For the naming conventions for files in the audit trail, see your operating-system documentation.

Example 1: Start auditing

The following command starts auditing all sessions:

onaudit -l 1

Example 2: Stop auditing

The following command stops auditing all current sessions. Also, sessions started after the command is run are not audited:

onaudit -1 0

Example 3: Change the audit configuration

The following command changes the error mode to 3 (shut down the server), the auditing mode to 3 (Audit DBSSO actions), and starts a new audit file:

onaudit -e 3 -l 3 -n

Example 4: Audit selected tables

The following command continues auditing all tables that have the AUDIT flag and stops auditing all other tables:

onaudit -R 1