7 Audit Vault Control (AVCTL) Reference

Use the Audit Vault Control (AVCTL) command-line utility to manage various Oracle Audit Vault components (for example, checking the status of collector agents or managing the Audit Vault Data Warehouse). 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 AVCTL command activity. See Section A.1 and Section A.2 for more information.

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

Table 7-1 Audit Vault Control Commands

Command	Where Used	Description
-help	Both	Displays help information for the AVCTL commands
load_warehouse	Server	Loads older data from the raw audit data store into the data warehouse tables for analysis
purge_warehouse	Server	Purges audit data that was reloaded into the warehouse
refresh_warehouse	Server	Refreshes the data warehouse with the data in the raw audit data store since the last refresh operation
show_agent_status	Server	Shows the status (metric) of a collection agent
show_av_status	Server	Shows the status (metric) of the Audit Vault Console
show_collector_status	Server	Shows the status (metric) of a collector
show_oc4j_status	Collection agent	Shows the status (metric) of OC4J
start_agent	Server	Starts the collection agent
start_av	Server	Starts the Audit Vault Console
start_collector	Server	Starts the collector
start_oc4j	Collection agent	Starts the agent OC4J
stop_agent	Server	Stops the collection agent
stop_av	Server	Stops the Audit Vault Console
stop_collector	Server	Stops the collector
stop_oc4j	Collection Agent	Stops the agent OC4J

Note:

In an Oracle RAC environment, you must issue the AVCTL commands from the node on which Oracle Enterprise Manager resides. This is the same node on which the av.ear file is deployed.

If the node on which the av.ear file is deployed is down, deploy the av.ear file to another node using the AVCA deploy_av command.

7.1 -help

Displays help information for the AVCTL commands. You can run this command on both the Audit Vault Server and the Audit Vault collection agent.

Syntax

avctl -help

avctl command -help

Arguments

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

Usage Notes

If you installed the collection agent on a Microsoft Windows computer and want to run the avctl help 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.

Example

The following example shows how to display general AVCTL utility help in the Audit Vault Server home.

$ avctl -help

  --------------------------------------------
  AVCTL Usage
  --------------------------------------------
  Oracle Audit Vault Control commands - AV Server:
      avctl start_av [-loglevel error|warning|info|debug]
      avctl stop_av
      avctl show_av_status
 
  Oracle Audit Vault Control commands - Agent:
      avctl start_agent -agentname <agent name>
      avctl stop_agent -agentname <agent name>
      avctl show_agent_status -agentname <agent name>
 
  Oracle Audit Vault Control commands - Collector:
      avctl start_collector -collname <collector name> -srcname <source name>
      avctl stop_collector -collname <collector name> -srcname <source name>
      avctl show_collector_status -collname <collector name> -srcname <source name>
 
  Oracle Audit Vault Control commands - Warehouse:
      avctl refresh_warehouse [-wait]
      avctl load_warehouse -startdate <start date> -numofdays <num of days> [-dateformat <date format>] [-wait]
      avctl purge_warehouse -startdate <start date> -numofdays <num of days> [-dateformat <date format>] [-wait]
 
  avctl -help

The following example shows how to display specific AVCTL Help for the start_agent command in Oracle Audit Vault.

$ avctl start_agent -help
  avctl start_agent -agentname <agent name>
  ------------------------------------------------
  -agentname <agent name>
  ------------------------------------------------

7.2 load_warehouse

Loads audit trail data from the raw audit data store after it has been removed from the warehouse repository due to the retention period that was set. Run this command on the Audit Vault Server.

Syntax

avctl load_warehouse -startdate start_date-numofdays num_of_days 
                    [-dateformat date_format] [-wait]

Arguments

Argument	Description
-startdate start_date	Enter the start date for the audit trail data to be loaded into the data warehouse repository using the default format DD-MON-YY. To use a different format, specify the -dateformat argument. Use any supported Oracle Database date format. See Oracle Database Globalization Support Guide for more information about date formats.
-numofdays num_of_days	Enter the number of days' worth of audit trail data to be loaded.
-dateformat date_format	Enter the date format for the -startdate argument. Optional. Ensure that the date argument used for startdate matches the date format you choose. For Oracle Database supported date formats, see Oracle Database Globalization Support Guide.
-wait	Enter the command wait for the load job to complete. If you do not specify this argument, a DBMS job is started, and the command returns immediately. Optional.

Usage Notes

• The audit records received from the value of the -startdate argument for the given number of days specified by the -numofdays argument will be loaded into the data warehouse.

• See Section 3.4 for more information about managing the Oracle Audit Vault data warehouse.

Example

The following example shows how to load the data warehouse with 10 days' worth of audit data beginning with January 1, 2004:

$ avctl load_warehouse -startdate 01-JAN-04 -numofdays 10

AVCTL started
Loading older audit records into warehouse...
done.

The following example shows how to load the data warehouse with 10 days' worth of audit data beginning with January 1, 2004 using the DD/MM/YYYY date format, and to specify that the operation wait until the previous load job completes.

$ avctl load_warehouse -startdate 01/01/2004 -numofdays 10 -dateformat DD/MM/YYYY -wait

AVCTL started
Loading older audit records into warehouse...
done. 

7.3 purge_warehouse

Purges audit trail data from the warehouse repository that was previously loaded into the warehouse using the avctl load_warehouse command. Run this command on the Audit Vault Server.

Syntax

avctl purge_warehouse -startdate start_date -numofdays num_of_days 
                     [-dateformat date_format] [-wait]

Arguments

Argument	Description
-startdate start_date	Enter the start date for the events to be removed from the data warehouse tables using the default format DD-MON-YY. To use a different format, specify the -dateformat argument. Use any supported Oracle Database date format. See Oracle Database Globalization Support Guide for more information about date formats.
-numofdays num_of_days	Enter the number of days' worth of data to be removed.
-dateformat date_format	Specify the date format for the -startdate argument. Optional.
-wait	Optionally, enter this keyword to have the command wait for the purge job to complete. If you omit this argument, then Oracle Audit Vault starts the job and then returns to the command prompt immediately. Optional.

Usage Notes

• The audit records received from the -startdate argument for the given number of days specified by the -numofdays argument will be removed from the data warehouse tables.

• Only data loaded using the avctl load_warehouse command can be purged using the avctl purge_warehouse command. The data loaded using the avctl refresh_warehouse command is removed automatically based on the warehouse duration specified using the avca set_warehouse_retention command.

• See Section 3.4 for more information about managing the Oracle Audit Vault data warehouse.

Example

The following example shows how to purge 10 days' worth of data from the data warehouse beginning with January 1, 2004:

$ avctl purge_warehouse -startdate 01-JAN-04 -numofdays 10 

AVCTL started
Purging older audit records from warehouse...
done.

The following example shows how to purge 10 days' worth of data from the data warehouse beginning with January 1, 2004 and to specify that the operation wait until the previous purge job completes:

$ avctl purge_warehouse -startdate 01-JAN-04 -numofdays 10 -wait 

AVCTL started
Purging older audit records from warehouse...
Waiting for purge to complete...
done.

The following example shows how to purge 10 days' worth of data from the data warehouse beginning with January 1, 2004 using the date format of DD/MM/YYYY.

$ avctl purge_warehouse -startdate 01/01/2004 -numofdays 10 -dateformat DD/MM/YYYY

AVCTL started
Purging older audit records from warehouse...
done.

7.4 refresh_warehouse

Refreshes the data warehouse repository with the data from the raw audit data store since the last refresh operation. Run this command on the Audit Vault Server.

Syntax

avctl refresh_warehouse [-wait]

Arguments

Argument	Description
-wait	Enter this keyword to specify that the command wait for the refresh job to complete. If you omit this argument, Oracle Audit Vault starts the job and then returns to the command prompt immediately. Optional.

Usage Notes

• The last refresh operation could have been an explicit refresh using this command or a scheduled refresh based on the schedule set using the avca set_warehouse_schedule command.

• See Section 3.4 for more information about managing the Oracle Audit Vault data warehouse.

Example

The following example shows how to refresh the data warehouse:

$ avctl refresh_warehouse 

AVCTL started
Refreshing warehouse...
done.

This example shows how to specify that the refresh operation wait until the previous refresh job completes before refreshing the data warehouse:

$ avctl refresh_warehouse -wait 

AVCTL started
Refreshing warehouse...
Waiting for refresh to complete...
done. 

7.5 show_agent_status

Shows the status (metric) of a collection agent. Run this command on the Audit Vault Server.

Syntax

avctl show_agent_status -agentname agent_name

Arguments

Argument	Description
-agentname agent_name	Enter the collection agent (by collection agent name).

Usage Notes

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

Example

The following example shows the collection agent status for the sales_agt agent:

$ avctl show_agent_status -agentname SALES_AGT

AVCTL started
Getting agent metrics...
--------------------------------
Agent is running
--------------------------------
Metrics retrieved successfully.

7.6 show_av_status

Shows the Audit Vault Console status or the metric of the Audit Vault Server. Run this command on the Audit Vault Server.

Syntax

avctl show_av_status 

Arguments

None

Usage Notes

When the Audit Vault Console becomes inaccessible, issue this command to determine its status.

Example

The following example shows the Audit Vault Console status:

$ avctl show_av_status 

AVCTL started
Oracle Audit Vault 10g Database Control Release 10.2.3.1.0  Copyright (c) 1996,
 2008 Oracle Corporation.  All rights reserved.
http://hrdb.us.example.com:5570/av
Oracle Audit Vault 10g is running. 
------------------------------------
Logs are generated in directory /oracle/product/10.2.3/av_1/av/log

7.7 show_collector_status

Shows the status (metric) of a collector. Run this command on the Audit Vault Server.

Syntax

avctl show_collector_status -collname collector_name -srcname source_name

Arguments

Argument	Description
-collname collector_name	Enter the target collector (by collector name).
-srcname source_name	Enter the name of the source database to which this collector belongs.

Usage Notes

None

Example

The following example shows the collector status for the DBAUD_Collector collector:

$ avctl show_collector_status -collname DBAUD_Collector 
                              -srcname RODSRC1.US.EXAMPLE.COM

AVCTL started
Getting collector metrics...
--------------------------------
Collector is running
Records per second  =  0.00
Bytes per second  =  0.00
--------------------------------

7.8 show_oc4j_status

Shows the OC4J status (metric). Run this command on the Audit Vault collection agent.

Syntax

avctl show_oc4j_status

Arguments

None

Usage Notes

If you installed the collection agent on a Microsoft Windows computer, run the avctl show_oc4j_status 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.

Example

The following example shows the OC4J status for when it is running and when it is not running:

$ avctl show_oc4j_status 

AVCTL started
------------------------------------
OC4J is running
------------------------------------

This example shows the OC4J status for when it is not running:

$ avctl stop_oc4j

AVCTL startedStopping OC4J...OC4J stopped successfully.

$ avctl show_oc4j_status
AVCTL started
------------------------------------
OC4J is not running
------------------------------------

7.9 start_agent

Starts the specified collection agent. Run this command on the Audit Vault Server.

Syntax

avctl start_agent -agentname agent_name

Arguments

Argument	Description
-agentname agent_name	Enter the collection agent (by collection agent name) to be started.

Usage Notes

• On successful completion of this command, the collection agent is moved to a RUNNING state. If an error is encountered, the collection agent is moved to an ERROR state.

• Oracle Audit Vault accepts audit records only from collection agents in the RUNNING state.

• If you set the NLS_LANG environment value before running the avctl start_oc4j command in the Audit Vault Agent shell and running the avctl start_agent command or avctl start_collector command in the Audit Vault Server shell, the avctl start_collector command can accept a multibyte source name or collector name.

Example

The following example shows how to start the collection agent in Oracle Audit Vault:

$ avctl start_agent -agentname sales_agt 

AVCTL started
Starting Agent...
Agent started successfully. 

7.10 start_av

Starts the Audit Vault Console. Run this command on the Audit Vault Server.

Syntax

avctl start_av [-loglevel level]

Arguments

Argument	Description
-loglevel level	Optionally, enter the desired level of logging from the following options. error: Logs only error messages warning: Logs both warning and error messages info: Logs informational and error messages (default) debug: Logs debug, error, warning, and informational messages

Usage Notes

This command executes the emctl start dbconsole command.

Example

The following example shows how to start the Audit Vault Console:

$ avctl start_av

AVCTL started
Starting OC4J...
OC4J started successfully.
Oracle Audit Vault 10g Database Control Release 10.2.3.1.0  Copyright (c) 1996,2008 Oracle Corporation.  All rights reserved.
http://shobeen.us.example.com:5700/av
Oracle Audit Vault 10g is running.
------------------------------------
Logs are generated in directory /oracle/product/10.2.3/av_1/av/log 

7.11 start_collector

Starts the collector. Run this command on the Audit Vault Server.

Syntax

avctl start_collector -collname collector_name -srcname source_name

Arguments

Argument	Description
-collname collector_name	Enter the name of the collector to be started.
-srcname source_name	Enter the name of the source database to which the collector (specified in the -collname argument) belongs.

Usage Notes

• On successful completion of this command, Oracle Audit Vault sets the collector to a RUNNING state. If an error is encountered, the collector is set to an ERROR state. If you receive a message saying that the collector is not in a RUNNING state, ensure that the agent has been started. Use the avctl start_agent command to start the agent, as described in Section 7.9.

• Oracle Audit Vault accepts audit records only from collectors in the RUNNING state.

• If you set the NLS_LANG environment value before running the avctl start_oc4j command in the Audit Vault Agent shell and running the avctl start_agent command or avctl start_collector command in the Audit Vault Server shell, the avctl start_collector command can accept a multibyte source name or collector name.

Example

The following example shows how to start the collector in Oracle Audit Vault:

$ avctl start_collector -collname REDO_Collector -srcname ORCLSRC1.EXAMPLE.COM 

AVCTL started
Starting Collector...
Collector started successfully.

7.12 start_oc4j

Starts the agent OC4J. Run this command on the Audit Vault collection agent.

Syntax

avctl start_oc4j [-loglevel level] [-maxheapsize maximum_heap_memory]

Arguments

Argument	Description
-loglevel level	Optionally, enter the desired level of logging from the following options: error: Logs only error messages warning: Logs both warning and error messages info: Logs informational and error messages (default) debug: Logs debug, error, warning, and informational messages
-maxheapsize maximum_heap_memory	Enter the maximum amount of heap memory allocated for the Java OC4J process. The default value is 1000 MB. Optional. This setting enables you to fine-tune the OC4J performance based on the size of your Oracle Audit Vault installation. Check the size of the physical memory of the computer on which the Audit Vault collection agents are installed before setting this value.

Usage Notes

• If you installed the collection agent on a Microsoft Windows computer, run the avctl start_oc4j 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.

• If you set the NLS_LANG environment value before running the avctl start_oc4j command in the Audit Vault Agent shell and running avctl start_agent command or avctl start_collector command in the Audit Vault Server shell, it will ensure that the avctl start_collector command can accept with a multibyte source name or collector name.

Example

The following example shows how to start OC4J. For the -maxheapsize setting, include M (for megabytes) as shown below. You can set it for other sizes, such as G for gigabyte, but in most cases, you should set it in megabytes.

$ avctl start_oc4j -maxheapsize 500M

AVCTL started
Starting OC4J...
OC4J started successfully. 

7.13 stop_agent

Stops the collection agent. Run this command on the Audit Vault Server.

Syntax

avctl stop_agent -agentname agent_name 

Arguments

Argument	Description
-agentname agent_name	Enter the collection agent (by collection agent name) to be stopped.

Usage Notes

• This command will first stop all collectors running at this collection agent, and then stop the collection agent itself.

• On successful completion of this command, the collection agent and its collectors are moved to a STOPPED state.

• f an error is encountered, Oracle Audit Vault sets the collection agent to an ERROR state. Oracle Audit Vault accepts audit records only from collection agents in the RUNNING state.

Example

The following example shows how to stop the collection agent in Oracle Audit Vault:

$ avctl stop_agent -agentname sales_agt

AVCTL started
Stopping Agent...
Agent stopped successfully.

7.14 stop_av

Stops the Audit Vault Console. Run this command on the Audit Vault Server.

Syntax

avctl stop_av 

Arguments

None

Usage Notes

Oracle Audit Vault includes Enterprise Management Database Control as part of the user interfaces. When you issue the stop_av commend, it not only shuts down the Audit Vault Console, but it also stops Enterprise Management Database Control by executing the emctl stop dbconsole command. You do not need to issue the emctl command separately.

Example

The following example shows how to stop the Audit Vault Console:

$ avctl stop_av

AVCTL started
Stopping OC4J...
OC4J stopped successfully.

7.15 stop_collector

Stops the collector. Run this command on the Audit Vault Server.

Syntax

avctl stop_collector -collname collector_name -srcname source_name

Arguments

Argument	Description
-collname collector_name	Enter the name of the collector to be stopped.
-srcname source_name	Enter the name of the source database to which the collector (specified in the -collname argument) belongs.

Usage Notes

• On successful completion of this command, Oracle Audit Vault moves the collector a STOPPED state.

• If an error is encountered, Oracle Audit Vault sets collector to an ERROR state.

• Oracle Audit Vault accepts audit records only from collectors in the RUNNING state.

Example

The following example shows how to stop the collector in Oracle Audit Vault:

$ avctl stop_collector -collname STREAMSCOLLECTOR 

-srcname ORCL.REGRESS.RDBMS.DEV.US.ORACLE.COM 
AVCTL started
Stopping Collector...
Collector stopped successfully. 

7.16 stop_oc4j

Stops the agent OC4J. Run this command on the Audit Vault collection agent.

Syntax

avctl stop_oc4j 

Arguments

None

Usage Notes

If you installed the collection agent on a Microsoft Windows computer, run the avctl stop_oc4j 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.

Example

The following example shows how to stop OC4J:

$ avctl stop_oc4j

AVCTL started
Stopping agent OC4J...
OC4J stopped successfully.