6 Audit Vault Configuration Assistant (AVCA) Reference

Audit Vault Configuration Assistant (AVCA) is a command-line utility you use to manage various Audit Vault components (for example, adding or dropping collection agents). 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 AVCA command activity. See Section A.1 and Section A.2 for more information.

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

Table 6-1 Audit Vault Configuration Assistant Commands

Command	Used Where?	Description
add_agent	Server	Adds a collection agent to Oracle Audit Vault
create_credential	Both	Creates or updates a credential to be stored in the wallet
create_wallet	Collection agent	Creates a wallet to hold credentials
deploy_av	Server	Deploys the av.ear file to another node in an Oracle RAC environment
drop_agent	Server	Drops a collection agent from Oracle Audit Vault
generate_csr	Server	Generates a certificate request
-help	Both	Displays help information for the AVCA commands
import_cert	Server	Imports the specified certificate into the wallet
redeploy	Both	Redeploys the av.ear file on the Audit Vault Server system or the AVAgent.ear file on the Audit Vault collection agent system
remove_cert	Server	Removes the specified certificate from the wallet
secure_agent	Collection agent	Secures the Audit Vault collection agent by enabling mutual authentication with Oracle Audit Vault
secure_av	Server	Secures Audit Vault Server by enabling mutual authentication with the Audit Vault collection agent
set_warehouse_retention	Server	Controls the amount of data kept online in the data warehouse fact table
set_warehouse_schedule	Server	Sets the schedule for refreshing data from the raw audit data store to the audit data warehouse

Note:

In an Oracle RAC environment, you must run AVCA 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.

6.1 add_agent

Adds or registers a collection agent to Oracle Audit Vault. Run this command on the Audit Vault Server.

Syntax

avca add_agent -agentname agent_name [-agentdesc desc] -agenthost host

Arguments

Argument	Description
-agentname agent_name	Enter the name of the collection agent (by collection agent name) to be added.
-agentdesc desc	Enter a description of the collection agent. Optional.
-agenthost host	Enter the name of an agent host name where this collection agent is to be installed.

Usage Notes

You will be prompted for the agent user name and agent user name password. See the example.

Example

$ avca add_agent -agentname TTAgent2 -agenthost stapj40 

AVCA started
Adding agent...
Enter agent user name: agent_user_name
Enter agent user password: agent_user_pwd
Re-enter agent user password: agent_user_pwd
Agent added successfully.

6.2 create_credential

Creates or updates a credential to be stored in an Oracle wallet. Run this command on both the Audit Vault Server and Audit Vault collection agent during collector development.

Syntax

avca create_credential -wrl wallet_location -dbalias db_alias 

Arguments

Argument	Description
-wrl wallet_location	Enter the location of the Oracle Audit Vault wallet. Locations are as follows: UNIX and Linux-based systems: $ORACLE_HOME/network/admin/avwallet Microsoft Windows systems: ORACLE_HOME\network\ADMIN\avwallet
-dbalias db_alias	Enter the database alias. In the Audit Vault Server home, the database alias is the SID or Oracle instance identifier. You can find this SID by running the lsnrctl status command on the computer where you installed the source database.

Usage Notes

• Use this command to create a new certificate if another user changes the source user password on the source database, thus eventually breaking the connection between the collector and the source.

• If you installed the collection agent on a Microsoft Windows computer and want to run the avca create_credential 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

$ avca create_credential -wrl $ORACLE_HOME/network/admin/avwallet -dbalias av

AVCA started
Storing user credentials in wallet... 
Enter source user username: srcuser1
Enter source user password: password
Re-enter source user password: password
Create credential oracle.security.client.connect_string4
done.

6.3 create_wallet

Creates a wallet to hold credentials. Run this command on the Audit Vault collection agent.

Syntax

avca create_wallet -wrl wallet_location

Arguments

Argument	Description
-wrl wallet_location	Enter the directory location for the wallet. Ensure that this directory already exists. Locations are as follows: Linux and UNIX-based systems: $ORACLE_HOME/network/admin/avwallet Microsoft Windows systems: ORACLE_HOME\network\ADMIN\avwallet

Usage Notes

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

• After you execute this command, .sso and .p12 files are generated in the wallet location.

Example

The following example shows how to create a wallet in the location specified as $T_WORK/tt_1:

$ avca create_wallet -wrl $T_WORK/tt_1 
Enter wallet password: password

6.4 deploy_av

Deploys the av.ear file to another node in an Oracle Real Application Clusters (Oracle RAC) environment. This command also modifies the server.xml file and other related files to enable Oracle Audit Vault management through the Oracle Enterprise Manager Database Control console. Run this command on the Audit Vault Server.

Syntax

deploy_av -sid sid -dbalias db_alias -avconsoleport av_console_port

Arguments

Argument	Description
-sid sid	Enter the Oracle Database system identifier (SID) for the instance. You can verify the SID by running the lsnrctl status command on the computer where you installed the source database.
-dbalias db_alias	Enter the database alias
-avconsoleport av_console_port	Enter the port number for the Audit Vault Console. You can find this number by entering the following command in the Audit Vault Server shell: avctl show_av_status

Usage Notes

In an Oracle RAC environment, you must run the AVCA 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.

When you run the avca deploy_av command on Oracle RAC database, a wallet containing the default avadmin entries is created on the other node. However, other entries, such as the source user credentials must be added to the wallet using the avca create_credential command) being used that matches the collectors that are in use.

To use the Audit Vault Console from this other node, enter its host name or IP address (host) and port number (port) as you did previously in the Address field of the browser window (http://host:port/av), but replace the original host name or IP address with that for the other node.

Example

$ avca deploy_av -sid av -dbalias av -avconsoleport 5700

6.5 drop_agent

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

Syntax

avca drop_agent -agentname agent_name 

Arguments

Argument	Description
-agentname agent_name	Enter the name of the collection agent to be dropped from Oracle Audit Vault.

Usage Notes

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

• Oracle Audit Vault displays an error if active collectors are still running in the collection agent.

Example

The following example shows how to drop a collection agent named sales_agt from Oracle Audit Vault:

$ avca drop_agent -agentname sales_agt 

AVCA started
Dropping agent...
Agent dropped successfully.

6.6 generate_csr

Generates a certificate request in the format of a text file. Run this command on the Audit Vault Server.

Syntax

generate_csr -certdn Audit_Vault_Server_host_DN [-keysize size]
             -out certificate_request_output_file

Arguments

Argument	Description
-certdn Audit_Vault_Server_host_DN	Enter the distinguished name (DN) of the Audit Vault Server host
keysize size	Enter the certificate key size (in bits). Optional. Possible values are: 512 1024 (default) 2048
-out certificate_request_output_file	Enter the path and name of the certificate request output file. Ensure that you have write permissions for this directory.

Usage Notes

• You must use this command to generate a certificate request. After generating the certificate request, send it to your certificate authority (CA) and get it signed and then returned as a signed certificate.

  The DN of the Audit Vault Server is typically of the following form:

  CN=fully_qualified_hostname,OU=Org_Unit,O=Organization,ST=State,C=Country
  

• For detailed information about generating certificate requests when setting up the HTTPS protocol for Oracle Audit Vault, see Section 5.5.

Example

The following example shows how to generate a certificate request.

$ avca generate_csr -certdn CN=sales_srv.us.example.com,OU=SalesReps,O=RisingDoughCo,ST=CA,C=US -out user_certificate.cer

6.7 -help

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

Syntax

avca -help

avca command -help

Arguments

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

Usage Notes

If you installed the collection agent on a Microsoft Windows computer and want to run the avca help command from there, run it 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 how to display general AVCA utility Help in the Audit Vault Server home.

$ avca -help

  --------------------------------------------
  AVCA Usage
  --------------------------------------------
  Oracle Audit Vault Server Installation commands
      avca deploy_av -sid <sid> -dbalias <db alias> -avconsoleport <av console port>
      avca generate_csr -certdn <Audit Vault Server host DN> [-keysize 512|1024|2048] 
                        -out <certificate request output file> 
      avca import_cert -cert <User/Trusted certificate> [-trusted] 
      avca remove_cert -certdn <Audit Vault Server host DN> 
      avca secure_av -avkeystore <keystore location> -avtruststore <truststore location>
      avca secure_av -remove
 
  Oracle Audit Vault Configuration commands - Agent:
      avca add_agent -agentname <agent name> [-agentdesc <desc>] -agenthost <host> 
      avca drop_agent -agentname <agent name>
 
  Oracle Audit Vault Configuration commands - Warehouse:
      avca set_warehouse_schedule -schedulename <schedule name>
      avca set_warehouse_schedule -startdate <start date> -rptintrv <repeat interval> 
                                 [-dateformat <date format>]
      avca set_warehouse_retention -intrv <year-month interval>
 
  Oracle Audit Vault Agent Installation commands
      avca secure_agent -agentkeystore <keystore location> -avdn <DN of Audit Vault> 
                        -agentdn <DN of agent>
      avca secure_agent -remove
  
  Oracle Audit Vault Configuration commands - Authentication:
      avca create_wallet -wrl <wallet_location> 
      avca create_credential -wrl <wallet_location> -wpwd <wallet_pwd> -dbalias <db alias> 
                             -usr <usr>/<pwd> 

  avca -help

The following example shows how to display specific AVCA help for the add_agent command in Audit Vault.

$ avca add_agent -help

  avca add_agent -agentname <agent name> [-agentdesc <desc>] -agenthost <host>
  ------------------------------------------------
  -agentname <agent name>
  [-agentdesc <agent description>]
  -agenthost <agent host>
  ------------------------------------------------

This example shows how to display general AVCA utility help in the Audit Vault collection agent home.

$ avca -help
  --------------------------------------------
  AVCA Usage
  --------------------------------------------
  Oracle Audit Vault Agent Installation commands
      avca secure_agent -agentkeystore <keystore location> 
                        -avdn <DN of Audit Vault> -agentdn <DN of agent>
      avca secure_agent -remove

  Oracle Audit Vault Configuration commands - Authentication:
      avca create_wallet -wrl <wallet_location> 
      avca create_credential -wrl <wallet_location> -wpwd <wallet_pwd> 
                             -dbalias <db alias> -usr <usr>/<pwd> 

  avca -help

6.8 import_cert

Imports the specified user or trusted certificate into the wallet. Run this command on the Audit Vault Server.

Syntax

import_cert -cert User/Trusted_certificate [-trusted]

Arguments

Argument	Description
-cert User/Trusted_certificate	Enter the path and file name of the certificate to be imported into the wallet. See the usage notes.
-trusted	Include this argument if you want to indicate that the certificate is trusted. If it is a user certificate, then omit the trusted argument. Optional.

Usage Notes

• To obtain the certificate, contact the certificate authority. Place the certificate in a directory that you can easily access, for the -cert argument. Ensure that the certificate matches a pending certificate request in the wallet. You must import the trusted certificate for this certificate first.

• For detailed information about configuring wallets when setting up the HTTPS protocol for Oracle Audit Vault, see Section 5.5.

Example

The following example shows how to import a certificate into the wallet.

$ avca import_cert -cert user_certificate.cer

This example shows how to import a trusted certificate into the wallet.

$ avca import_cert -cert ca_certificate.cer -trusted

6.9 redeploy

Redeploys the av.ear file on the Audit Vault Server system or the AVAgent.ear file on the Audit Vault collection agent system.

Syntax

avca redeploy

Arguments

None

Usage Notes

If you installed the collection agent on a Microsoft Windows computer and want to run the avca redeploy command from there, run it 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 how to redeploy either the av.ear file on the Audit Vault Server system or the AVAgent.ear file on the Audit Vault collection agent system.

$ avca redeploy

6.10 remove_cert

Removes the specified certificate from the wallet. Run this command on the Audit Vault Server.

Syntax

remove_cert -cert Audit_Vault_Server_host_DN 

Arguments

Argument	Description
-cert Audit_Vault_Server_host_DN	Enter the distinguished name (DN) of the Audit Vault Server host that was used for the avca generate_csr command.

Usage Notes

Oracle Audit Vault removes the certificate or key pair for the DN matching the given DN from the wallet. For example, you can use this command to remove a certificate that expires or is revoked by the CA, and replace it with a renewed certificate.

You, the Oracle Audit Vault administrator, provide the DN of the Audit Vault Server is typically of the form:

CN=hostname_fully_qualified,OU=Org_Unit,O=Organization,ST=State,C=Country

Example

The following example shows how to remove a certificate from the wallet.

$ avca remove_cert -hrdb.example.com CN=AV_Server_host_DN,OU=DBSEC,O=Oracle,ST=CA,C=US

6.11 secure_agent

Secures the Audit Vault collection agent by enabling mutual authentication with the Audit Vault Server. Run this command on the Audit Vault collection agent. If you specify the remove argument, this command removes mutual authentication with the Audit Vault Server.

Syntax

avca secure_agent -agentkeystore keystore_location
 -avdn Audit_Vault_Server_host_DN 
 -agentdn agent_DN [-agentkeystore_pwd keystore_pwd]

avca secure_agent -remove

Arguments

Argument	Description
-agentkeystore keystore_location	Enter the keystore file location for this collection agent. See Section 5.5.3 for more information about the keystore file.
-avdn Audit_Vault_Server_host_DN	Enter the distinguished name (DN) of the Audit Vault Server.
-agentdn agent_DN	Enter the DN of this Audit Vault collection agent.
-remove	Include this keyword to remove mutual authentication with the Audit Vault Server.

Usage Notes

• If you installed the collection agent on a Microsoft Windows computer, run the avca secure_agent 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 avca secure_agent command prompts for the agent key password. You can bypass this prompt if the corresponding environment variable, AVCA_AGENTKEYSTOREPWD is set. If you enter the password, then it overrides the environment variable. This argument is provided for backward compatibility

• The keystore and certificate must be in place at the collection agent site before you execute this command.

• Use the following command to generate a keystore:

  $ORACLE_HOME/jdk/bin/keytool
  

• When you issue the secure_agent command for the specified collection agent with both the collection agent and its collectors in a running state, the collection agent and all its collectors will shut down when the agent OC4J shuts down and then restarts. You must manually restart the collection agent and its collectors.

• For detailed information about configuring mutual authentication when setting up the HTTPS protocol for Oracle Audit Vault, see Section 5.5.

Example

The following example shows how to secure the Audit Vault collection agent by enabling mutual authentication with the Audit Vault Server.

$ avca secure_agent -agentkeystore /tmp/agentkeystore
  -agentdn "CN=agent1, OU=development, O=oracle, L=redwoodshores, ST=ca, C=us" 
  -avdn "CN=av1, OU=development, O=oracle, L=redwoodshores, ST=ca, C=us" 
Enter keystore password: *******

The following example shows how to unsecure the Oracle Audit Vault collection agent by disabling mutual authentication with the Audit Vault Server.

$ avca secure_agent -remove

AVCA started
Restarting OC4J...
OC4J restarted successfully.

6.12 secure_av

Secures the Audit Vault Server by enabling mutual authentication with the Audit Vault collection agent. Run this command on the Audit Vault Server. If you specify the remove argument, this command removes mutual authentication with Audit Vault collection agent.

Syntax

avca secure_av -avkeystore keystore_location -avtruststore truststore_location
               [-avkeystorepwd keystore_pwd>]

avca secure_av -remove

Arguments

Argument	Description
-avkeystore keystore_location	Enter the keystore file location for the Audit Vault Server. By default, this file is located in the Audit Vault Server home directory. It has the file extension of .keystore. See Section 5.5.3 for more information about the keystore file.
-avtruststore truststore_location	Enter the trust store location for the Audit Vault Server. This file can be the same file as the avkesytore file. Ensure that this file has the CA certificates imported into it.
-remove	Include this keyword to remove mutual authentication with the Audit Vault collection agent

Usage Notes

• The keystore and certificate files must be in place at the Audit Vault Server before you run this command.

• Use the following command to generate a keystore:

  $ORACLE_HOME/jdk/bin/keytool
  

• When you issue the avca secure_av command, the Audit Vault Console agent OC4J restarts, which requires you to log in to Audit Vault Console again.

• The avca secure_av command prompts for the keystore password for the Audit Vault Server. If the corresponding environment variable, AVCA_AVKEYSTOREPWD, is set, then you can bypass this prompt. If you enter the password anyway, it overrides the environment variable. This argument is provided for backward compatibility.

• For detailed information about configuring mutual authentication when setting up the HTTPS protocol for Oracle Audit Vault, see Section 5.5.

Example

The following example shows how to secure the Audit Vault Server by enabling mutual authentication with the Oracle Audit Vault collection agent.

$ avca secure_av -avkeystore /tmp/avkeystore -avtruststore /tmp/avkeystore 
Enter keystore password: password

The following example shows how to unsecure Audit Vault Server by disabling mutual authentication with the Audit Vault collection agent.

$ avca secure_av -remove

AVCA started
Stopping OC4J...
OC4J stopped successfully.
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://av_srv.us.example.com:5700/av
Oracle Audit Vault 10g is running.
------------------------------------
 
Logs are generated in directory $ORACLE_HOME/10.2.3/av_1/av/log

6.13 set_warehouse_retention

Controls the amount of data kept online in the data warehouse fact table. Run this command on the Audit Vault Server.

Syntax

avca set_warehouse_retention -intrv year_month_interval  

Arguments

Argument	Description
-intrv year_month_interval	Enter the year-month interval in the following format: +YY-MM

Usage Notes

• The interval setting must be a positive value.

• Oracle Audit Vault removes the data loaded using the avctl refresh_warehouse command based on the warehouse retention that was using the AVCA set_warehouse_retention command.

• See Section 3.4 for detailed information about creating a retention period.

Example

The following example shows how to control the amount of data kept online in the data warehouse table. In this case, a time interval of 1 year is specified.

$ avca set_warehouse_retention -intrv +01-00 

AVCA started
Setting warehouse retention period...
done.

6.14 set_warehouse_schedule

Sets the schedule for refreshing data from the raw audit data store to the audit data warehouse tables. Run this command on the Audit Vault Server.

Syntax

avca set_warehouse_schedule -schedulename schedule_name 

avca set_warehouse_schedule -startdate start_date 
     -rptintrv repeat_interval [-dateformat date_format] 

Arguments

Argument	Description
-schedulename schedule_name	Enter the schedule name created using the DBMS_SCHEDULER.create_schedule procedure. To find the names of existing schedules created with the DBMS_SCHEDULE package, query the ALL_SCHEDULER_JOBS data dictionary view. See Oracle Database Reference for more information.
-startdate start_date	Enter the start date for a warehouse refresh job using the default format DD-MON-YY. To use a different format, specify the -dateformat argument.
-rptintrv repeat_interval	Enter the repeat interval for the schedule using the syntax used in the DBMS_SCHEDULER.create_schedule procedure.
-dateformat date_format	Enter the date format for the -startdate argument. Optional.

Usage Notes

• You can select an existing schdule that was created with the DBMS_SCHEDULER.CREATE_SCHEDULE PL/SQL procedure, or you can set the schedule by providing the start date and repeat interval.

• The following are error conditions:

  • The schedule name argument must be a valid schedule created using the DBMS_SCHEDULER.CREATE_SCHEDULE procedure.

  • The repeat interval argument must be a valid interval specification consistent with the DBMS_SCHEDULER package.

• See Section 3.4 for detailed information about creating a refresh schedule.

Example

The following examples show how to set the schedule for refreshing data from the raw audit data store to the audit data warehouse tables by schedule name and by start date using the avca set_warehouse_schedule command.

The first example uses a schedule name argument based on a valid schedule created using the DBMS_SCHEDULER.create_schedule procedure.

avca set_warehouse_schedule -schedulename daily_refresh 

$ AVCA started
Set warehouse schedule...
done.

This example uses a start date and repeat interval argument.

$ avca set_warehouse_schedule -startdate 01-JUL-06 -rptintrv 'FREQ=DAILY;BYHOUR=0'

AVCA started
Set warehouse schedule...
done.

The following example uses a start date with a specified date format and a repeat interval argument.

$ avca set_warehouse_schedule -startdate 01-07-2006 -dateformat 'DD-MM-YYYY'

-rptintrv 'FREQ=DAILY;BYHOUR=0'
AVCA started
Set warehouse schedule...
done.