8 Audit Vault Oracle Database (AVORCLDB) Utility Commands

Use the Audit Vault Oracle Database (AVORCLDB) command-line utility to manage the relationship between Oracle Audit Vault and an Oracle source database and collector. When you run these commands, remember the following:

• Enter the command in lowercase letters. The commands are case-sensitive.

• When you open a new shell to run the command, first set the appropriate environment variables. See Section 2.2 for more information.

• Oracle Audit Vault creates a log file of AVORCLDB command activity. See Section A.1 and Section A.2 for more information.

Table 8-1 describes the AVORCLDB commands and where each is used, whether on the Audit Vault Server, on the Audit Vault collection agent, or in both places.

Table 8-1 AVORCLDB Commands

Command	Where Used?	Description
add_collector	Server	Adds a collector to Oracle Audit Vault
add_source	Server	Registers an audit source with Oracle Audit Vault
alter_collector	Server	Alters the attributes of a collector
alter_source	Server	Alters the attributes of a source
drop_collector	Server	Drops a collector from Oracle Audit Vault
drop_source	Server	Drops a source database from Oracle Audit Vault
-help	Both	Displays help information for the AVORCLDB commands
setup	Collection agent	Adds the source user credentials to the wallet, creates a database alias in the wallet for the source user, verifies the connection to the source using the wallet, and updates the tnsnames.ora file
verify	Both	Verifies that the source is compatible with the collectors that are specified for setup

8.1 avorcldb

The AVORCLDB command-line utility, which you use to configure an Oracle database with Oracle Audit Vault.

Syntax

avorcldb command -help

avorcldb command [options] arguments

Arguments

Argument	Description
command	Enter one of the commands listed in Table 8-1.
arguments	Enter one or more of the AVORCLDB command arguments.
-help	Displays help information for the AVORCLDB commands.

Usage Notes

Issuing an AVORCLDB command generates the following log file: $ORACLE_HOME/av/log/avorcldb.log.

8.2 add_collector

Adds a collector for the given Oracle source database to Audit Vault. Oracle Audit Vault verifies the source database for the collector requirements. Run this command on the Audit Vault Server.

Syntax

avorcldb add_collector -srcname srcname
-agentname agentname -colltype [OSAUD,DBAUD,REDO] 
[-collname collname] [-desc desc] 
[-av host:port:service] [-instname instname] [-orclhome orclhome] 

Arguments

Argument	Description
-srcname srcname	Enter the source database name for which the collector is to be added. Remember that the source database name is case-sensitive.
-agentname agentname	Enter the name of the collection agent that was created when you ran the avca add_agent command.
-colltype colltype	Enter the collector type to be added. DBAUD OSAUD REDO See Table 1-4 for more information about the collector types.
-collname collname	Create a name for the collector. Optional. If you do not create a name, Oracle Audit Vault names the collector colltype_Collector (for example, OSAUD_Collector for the OSAUD collector type).
-desc desc	Enter a brief description of the collector. Optional.
-av host:port:service	Enter the connection information for Oracle Audit Vault used for the database link from the source database to Oracle Audit Vault. You must include this argument if the -colltype argument is REDO; otherwise, this argument is optional.
-instname instname	Enter the instance name of Audit Vault Oracle RAC installation. You must include this argument if you are adding multiple OSAUD collectors, that is, one collector for each database instance.
-orclhome orclhome	Enter the Oracle home of the source database.You must include this argument if the -colltype argument is OSAUD; otherwise, this argument is optional. See the usage notes.

Usage Notes

• Run any collector-specific preparation scripts before you execute the avca add_collector command.

• On Microsoft Windows systems, specifying the OSAUD collector type automatically includes the event log and XML audit trails.

• When specifying the value for the -orclhome argument, enter the value as either a quoted string using a backslash. For example:

  -orclhome "c:\app\oracle\product\10.2.3\av_1"
  

  Alternatively, enter it as a nonquoted string using a slash. For example:

  -orclhome c:/app/oracle/product/10.2.3/av_1
  

• There is a 2 GB audit file size limit for the OSAUD collector to be able to collect audit records from audit trails stored in files, which includes the SYSLOG, .AUD, and .XML files. If the file size is greater than 2 GB, then the OSAUD collector ignores all audit records beyond 2 GB. To control the size of the operating system audit trail and select the audit trail type to set, set the DBMS_AUDIT_MGMT.OS_FILE_MAX_SIZE property and the DBMS_AUDIT_MGMT.AUDIT_TRAIL_TYPE type by using the DBMS_AUDIT_MGMT.SET_AUDIT_TRAIL_PROPERTY PL/SQL procedure. See Section 14.4.11 for more information.

Example

The following example shows how to add an OSAUD collector to Oracle Audit Vault on Linux and UNIX platforms in an Oracle Real Application Clusters (Oracle RAC) installation using the -instname argument.

$ avorcldb add_collector -srcname source1db.example.com 
-agentname Agent1 -colltype OSAUD -instname av01 
-orclhome /u01/app/oracle/product/10.2.0/db_1

source SOURCE1DB.EXAMPLE.COM verified for OS File Audit Collector collector
Adding collector...
Collector added successfully.
collector successfully added to Audit Vault

remember the following information for use in avctl
Collector name (collname): OSAUD_Collector

This example shows how to add a DBAUD collector to Oracle Audit Vault:

$ avorcldb add_collector -srcname source1db.example.com 

-agentname Agent1 -colltype DBAUD 
source SOURCE1DB.DOMAIN.COM verified for Aud$/FGA_LOG$ Audit Collector collector

Adding collector...
Collector added successfully.
collector successfully added to Audit Vault

remember the following information for use in avctl
Collector name (collname): DBAUD_Collector

The next example shows how to add a REDO collector to Oracle Audit Vault.

$ avorcldb add_collector -srcname source1db.example.com 
-agentname Agent1 -colltype REDO 
-av system1.example.com:1521:av 

source SOURCE1DB.EXAMPLE.COM verified for REDO Log Audit Collector collector
Adding collector...
Collector added successfully.
collector successfully added to Audit Vault

remember the following information for use in avctl
Collector name (collname): REDO_Collector
initializing REDO Collector
setting up APPLY process on Audit Vault server
setting up CAPTURE process on source database

8.3 add_source

Registers an Oracle source database with Oracle Audit Vault for audit data consolidation. Run this command on the Audit Vault Server.

Syntax

avorcldb add_source -src host:port:service 
      [-srcname srcname] [-desc desc] [-agentname agentname]

Arguments

Argument	Description
-src host:port:service	Enter the source database connection information: host name, port number, and service ID (SID), separated by a colon. If you are unsure of this connection information, run the lsnrctl status command on the computer where you installed the source database.
-srcname srcname	Enter the name of the source database. Remember that the source database name is case-sensitive. Optional. If you do not specify this argument, Oracle Audit Vault uses the global database name.You can check this name by selecting from the GLOBAL_NAME data dictionary view in SQL*Plus. For example: SQL> SELECT * FROM GLOBAL_NAME;
-desc desc	Enter a brief description of the source database. Optional.
-agentname agentname	Create a name for a collection agent. Optional. However, you must specify an agent name if auditors plan to configure policy management using the Audit Vault Console.

Usage Notes

• The global database name of the source database is used as the source name in Oracle Audit Vault.

• The avorcldb add_source command prompts for the source user name and password. This user account must exist on the source database.

  To find this user, query the SESSION_PRIVS and SESSION_ROLES data dictionary views. The source user should have the privileges and roles that are listed in the zarsspriv.sql file, such as the CREATE DATABASE LINK privilege and DBA role.

  If the AVORCLDB_SRCUSR environment variable is set to this user account and password, then you can bypass the Enter Source user name and Enter Source password prompts. If you do specify these values, they override the environment variable.

• You must specify the -agentname agentname parameter so that auditors can configure policy management using the Audit Vault Console.

Example

The following example shows how to register a source with Oracle Audit Vault.

$ avorcldb add_source -src hrdb.example.com:1521:orcl -agentname agent1
Enter Source user name: username
Enter Source password: password

Adding source...
Source added successfully.
source successfully added to Audit Vault

remember the following information for use in avctl
Source name (srcname): RDBMSRC1.US.EXAMPLE.COM
Storing user credentials in wallet... 
Create credential oracle.security.client.connect_string3
done.
Mapping Source to Agent...

8.4 alter_collector

Modifies the attributes of an Oracle Database collector. Run this command on the Audit Vault Server.

Syntax

avorcldb alter_collector -srcname srcname -collname collname 
      [attrname=attrvalue...attrname=attrvalue]

Arguments

Argument	Description
-srcname srcname	Enter the name of the source database to which this collector belongs. Remember that the source database name is case-sensitive.
-collname collname	Enter the name of the collector to be modified.
attrname=attrvalue	Enter the attribute pair (attribute name, new attribute value) for mutable collector attributes for this collector type. This argument is optional. Separate multiple pairs by a space on the command line.

Usage Notes

You can modify one or more collector attributes at a time. The following tables list the collector attributes (parameters) by collector type, whether the parameter is mutable, and its default value. See Section 3.3 for a description of these attributes.

Table 8-2 describes the DBAUD collector attributes.

Table 8-2 DBAUD Collector Attributes

Parameter	Description	Mutable	Default Value
AUDAUDIT_ACTIVE_SLEEP_TIME	The amount of active sleep time (in milliseconds) for the DBAUD process when the last retrieval actually did retrieve records.	Yes	1000 milliseconds
AUDAUDIT_AUDIT_VAULT_ALIAS	The alias name for the Audit Vault Server.	No	NULL
AUDAUDIT_DELAY_TIME	The amount of delay time (in seconds) for the DBAUD process.	Yes	20 seconds
AUDAUDIT_MAX_PROCESS_RECORDS	The maximum number of records after which the collector commits records to the raw audit data store and generates minor recovery context. In fine-grained auditing (FGA_LOG$) and 9.x sources, the collector might need to delay this until the record with the higher timestamp is retrieved. A valid value is an integer value from 10 to 10000.	Yes	1000 records
AUDAUDIT_SLEEP_TIME	The amount of sleep time (in milliseconds) for the DBAUD process. For example, if it is now 10:00:00 AM, the collector will retrieve the records with the timestamps that are less than 9:59:40. However, the next time the collector will only retrieve records with the timestamps of 9:59:40 or higher. The assumption is that within 20 seconds after the timestamp is assigned to the record, the record would be visible (retrievable). This attribute is used only for time-based retrieval in fine-grained auditing (FGA_LOG$) on 9.x source databases. In Oracle Audit Vault, time-based retrieval is used for all retrievals.	Yes	5000 milliseconds
AUDAUDIT_SORT_POLICY	The audit data sort policy. This attribute is not implemented. It was deprecated for Oracle Audit Vault Release 10.2.3.	Yes	NULL
AUDAUDIT_SOURCE_ALIAS	The alias name for the audit data source	No	NULL

Table 8-3 describes the OSAUD collector attributes.

Table 8-3 OSAUD Collector Attributes

Parameter	Description	Mutable	Default Value
OSAUDIT_AUDIT_VALUE_ALIAS	The alias name for the Audit Vault Server	No	NULL
OSAUDIT_CHANNEL_TYPE	The channel type being used by the collector This attribute is not implemented. It was deprecated in Oracle Audit Vault Release 10.2.3.	No	NULL
OSAUDIT_DEFAULT_FILE_DESTFoot 1	The default directory for Oracle Database operating system audit files. This directory contains mandatory audit record files.	Yes	$ORACLE_HOME/rdbms/audit
OSAUDIT_FILE_DEST	The directory for the Oracle Database operating system audit files. This directory contains SYS and regular audit record files.	Yes	$ORACLE_HOME/admin/DB_UNIQUE_NAME/adump
OSAUDIT_MAX_PROCESS_RECORDS	The maximum number of records to be processed during each call to process the collector. A valid value is an integer value from 10 to 10000.	Yes	10000
OSAUDIT_MAX_PROCESS_TIME	The maximum processing time for each call to process the collector (in centiseconds). A valid value is an integer value from 10 to 10000.	Yes	600 centiseconds
OSAUDIT_NLS_CHARSET	The NLS character set of the data source	Yes	WE8ISO8859P1
OSAUDIT_NLS_LANGUAGE	The NLS language of the data source	Yes	AMERICAN
OSAUDIT_NLS_TERRITORY	The NLS territory of the data source	Yes	AMERICA
OSAUDIT_NT_ORACLE_SID	The Oracle SID name on Microsoft Windows systems	Yes	NULL
OSAUDIT_RAC_INSTANCE_ID	The instance ID in an Oracle RAC environment	Yes	1.0
OSAUDIT_SOURCE_ALIAS	The alias or connection string to the source database	Yes	NULL
OSAUDIT_SYSLOG_FILE	The syslog file name and location, if other than the default as indicated in the etc/syslog.conf file. Setting this parameter to a valid syslog file name overrides the default setting.	Yes	NULL

^Footnote 1 To avoid collecting duplicate operating system audit trail records, do not set the attribute value for the OSAUDIT_DEFAULT_FILE_DEST attribute and the OSAUDIT_FILE_DEST attribute such that the values, although different, resolves to the same directory.

Table 8-4 describes the REDO collector attributes.

Table 8-4 REDO Collector Attributes

Parameter	Description	Mutable	Default Value
AV.DATABASE.NAME	The Oracle Audit Vault database name	No	NULL
STRCOLL_DBPORT	The port number of the audit data Oracle source database	Yes	NULL
STRCOLL_DBSERVICE	The service name of the audit data Oracle source database	No	NULL
STRCOLL_HEARTBEAT_TIME	The time, in seconds, between events for monitoring the status of the Audit Vault REDO collection system	Yes	60 seconds
STRCOLL_SRCADM_ALIAS	The alias name for the audit data source	No	NULL
STRCOLL_SRCADM_NAME	The name of the audit data source database	No	NULL

On Microsoft Windows systems, if the path value for the OSAUDIT_DEFAULT_FILE_DEST attribute is set incorrectly using backslashes, use the Audit Vault Console to log in as the Audit Vault administrator and connect as AV_ADMIN, click Configuration, click Collector, select the OSAUD_Collector name, then click Edit and edit the value for this attribute using slashes instead of backslashes. When finished, click OK to save your changes.

Example

The following example shows how to alter the AUDAUDIT_DELAY_TIME attribute for the DBAUD_Collector collector in Oracle Audit Vault:

$ avorcldb alter_collector -srcname hrdb.example.com -collname DBAUD_Collector  AUDAUDIT_DELAY_TIME=60 

Altering collector...
Collector altered successfully.

8.5 alter_source

Modifies the attributes of an Oracle source database. Run this command on the Audit Vault Server.

Syntax

avorcldb alter_source -srcname srcname
      [attrname=attrvalue...attrname=attrvalue]

Arguments

Argument	Description
-srcname srcname	Enter the name of the source database to be modified. Remember that the source database name is case-sensitive.
attrname=attrvalue	Enter the pair (attribute name, new attribute value) for the mutable source attributes of this source to be modified. Optional. Separate multiple pairs by a space on the command line.

Usage Notes

Table 8-5 lists source attributes that you can specify for the attrname=attrvalue argument.

Table 8-5 Source Attributes

Parameter	Description	Mutable	Default Value
HOSTIP	The Internet protocol address of the host system on which the source database resides	Yes	NULL
VERSION	The source database version	Yes	NULL
DESCRIPTION	The description for this source database	Yes	NULL
DB_SERVICE	A new audit data source database service name	Yes	NULL
PORT	A new port number for this system where the source database audit data resides	Yes	NULL
GLOBAL_DATABASE_NAME	The new global database name	Yes	NULL

Example

The following example shows how to alter the PORT attribute for the source database named hrdb.example.com in Oracle Audit Vault:

$ avorcldb alter_source -srcname hrdb.example.com PORT=1522
Altering source...
Source altered successfully.

8.6 drop_collector

Disables (but does not remove) a collector from Oracle Audit Vault. Run this command from the Audit Vault Server.

Syntax

avorcldb drop_collector -srcname srcname -collname collname

Arguments

Argument	Description
-srcname srcname	Enter the name of the source database to which the collector (specified in the -collname argument) belongs. Remember that the source database name is case-sensitive.
-collname collname	Enter the name of the collector to be dropped from Oracle Audit Vault.

Usage Notes

The drop_collector command does not delete the collector from Oracle Audit Vault. It only disables the collector. The collector metadata is still in the database after you run the drop_collector command. If you want to recreate the collector, create it with a different name.

Example

$ avorcldb drop_collector -srcname hrdb.example.com -collname DBAud_Collector

Dropping collector...
Collector dropped successfully.

8.7 drop_source

Disables (but does not remove) a source database from Oracle Audit Vault. Run this command on the Audit Vault Server.

Syntax

avorcldb drop_source -srcname srcname

Arguments

Argument	Description
-srcname srcname	Enter the name of the source database to be dropped from Oracle Audit Vault. Remember that the source database name is case-sensitive.

Usage Notes

• The drop_source command does not delete the source database from Oracle Audit Vault. It only disables the source database definition in Oracle Audit Vault. The source database metadata is still in the database after you run the drop_source command. If you want to re-create the source database definition, create it with a different name.

• You cannot drop a source database if there are any active collectors for this source. You must drop all collectors associated with the source database before you can run the drop_source command on it.

Example

The following example shows how to drop the source named hrdb.example.com from Oracle Audit Vault:

$ avorcldb drop_source -srcname hrdb.example.com 

Dropping source...
Source dropped successfully.

8.8 -help

Displays help information for the AVORCLDB commands. Run this command on either the Audit Vault Server and the Audit Vault collection agent.

Syntax

avorcldb -help

avorcldb command -help

Arguments

Argument	Description
command	Enter the name of an AVORCLDB command for which you want help to appear

Usage Notes

None

Example

The following example shows how to display general AVORCLDB utility help in Oracle Audit Vault:

$ avorcldb -help

The following example shows how to display specific AVORCLDB help for the add_source command in the Audit Vault Server home shell.

$ avorcldb add_source -help

  avorcldb add_source command
 
    add_source
          -src <host:port:service> [-srcusr <usr>/<pwd>]
         [-srcname <srcname>] [-desc <desc>] [-agentname <agentname>]
 
  Purpose: The source is added to Audit Vault. The global DB Name
       of the source database is used as the Source Name in Audit Vault.
 
  Arguments:
       -src        : Source DB connection information
       -srcusr     : Optional source user name and password. Will be prompted.
       -srcname    : Optional name of source, default : <global_dbname>
       -desc       : Optional description of the source
       -agentname  : Optional agent name to configure policy management
 
  Examples:
     avorcldb add_source -src lnxserver:4523:hrdb.domain.com
       -desc 'HR Database'

8.9 setup

Adds the source user credentials to the wallet, creates a database alias in the wallet for the source user, verifies the connection to the source using the wallet, and updates the tnsnames.ora file. You also can use this command to change the source user credentials in the wallet after these credentials have been changed in the source database. Run this command on the Audit Vault collection agent.

Syntax

avorcldb setup -srcname srcname 

Arguments

Argument	Description
-srcname srcname	Enter the name of the source database. Remember that the source database name is case-sensitive.

Usage Notes

• If you installed the collection agent on a Microsoft Windows computer, run the avorcldb setup command from the ORACLE_HOME\agent_directory\bin directory. For UNIX or Linux installations, set the appropriate environment variables before running this command. See Section 2.2 for more information.

• The avorcldb setup command prompts for the source user name and password. This user account must exist on the source database.

  To find the privileges and roles granted to this user, query the SESSION_PRIVS and SESSION_ROLES data dictionary views. The source user should have the privileges and roles that are listed in the zarsspriv.sql file, such as the CREATE DATABASE LINK privilege and DBA role.

  If the AVORCLDB_SRCUSR environment variable is set to this user account and password, then you can bypass the Enter Source user name and Enter Source password prompts. If you do specify these values, they override the environment variable.

Example

The following example configures the REDO and OSAUD collectors.

$ avorcldb setup -srcname hrdb.example.com
Enter Source user name: username
Enter Source password: password

adding credentials for user srcuser_ora for connection [SRCDB1]
Storing user credentials in wallet...
Create credential oracle.security.client.connect_string3
done.
updated tnsnames.ora with alias [SRCDB1] to source database
verifying SRCDB1 connection using wallet

To change the source user name password in the wallet in the Audit Vault collection agent home, use the following setup command, where the source name is orcl1 and the source user name is srcuser_ora.

$ avorcldb setup -srcname orcl1
Enter Source user name: srcuser_ora
Enter Source password: password

adding credentials for user srcuser_ora for connection [SRCDB1]
Storing user credentials in wallet...
Create credential oracle.security.client.connect_string3
done.
updated tnsnames.ora with alias [SRCDB1] to source database
verifying SRCDB1 connection using wallet

8.10 verify

Verifies that the source is compatible for setting up the specified collectors. Run this command on either the Audit Vault Server or the Audit Vault collection agent.

Syntax

avorcldb verify -src host:port:service 
                -colltype [OSAUD,DBAUD,REDO,ALL] 

Arguments

Argument	Description
-src host:port:service	Enter the source database connection information: host name, port number, and service name, separated by a colon. Typically, the host is the fully qualified domain name or IP address of the server on which the source database is running, and the port number is 1521. If you are unsure of the host and port number, run the lsnrctl status command on the computer where you installed the source database.
-colltype colltype	Enter one of the following collector types: ALL DBAUD OSAUD REDO See Table 1-4 for more information about the collector types.

Usage Notes

• If you installed the collection agent on a Microsoft Windows computer and want to run the avorcldb verify command from there, run it from the ORACLE_HOME\agent_directory\bin directory. For UNIX or Linux installations, set the appropriate environment variables before running this command. See Section 2.2 for more information.

• The avorcldb verify command prompts for the source user name and password. This user account must exist on the source database. To find this user, query the SESSION_PRIVS and SESSION_ROLES data dictionary views. The source user should have the privileges and roles that are listed in the zarsspriv.sql file, such as the CREATE DATABASE LINK privilege and DBA role.

• If the AVORCLDB_SRCUSR environment variable is set to this user account, then you can bypass the Enter Source user name and Enter Source password prompts. If you do specify these values, they override the environment variable.

Example

The following example verifies that the source is compatible with the OSAUD, DBAUD, and REDO collectors on a Linux or UNIX system.

$ avorcldb verify -src hrdb.example.com:1521:orcl -colltype ALL
Enter Source user name: username
Enter Source password: password

source HRDB.EXAMPLE.COM verified for OS File Audit Collector collector
source HRDB.EXAMPLE.COM verified for Aud$/FGA_LOG$ Audit Collector collector
source HRDB.EXAMPLE.COM verified for REDO Log Audit Collector collector