A Audit Vault Configuration Assistant (AVCA) Reference

Audit Vault Configuration Assistant (AVCA) is a command-line utility that provides the Audit Vault administrator with the ability to manage various Audit Vault components.

The user running the AVCA commands must be granted the AV_ADMIN role.

Table A-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 A-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	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 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 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 star schema

Note:

In an Oracle RAC environment, AVCA commands must be issued 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.

---

add_agent

Adds or registers a collection agent to Audit Vault. This command is run on the Audit Vault Server.

Syntax

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

Arguments

Argument	Description
-agentname <agent name>	Specify the collection agent (by collection agent name) to be added.
[-agentdesc <desc>]	Optionally, specify a description of the collection agent.
-agenthost <host>	Specify 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.

• For information on how to install an Audit Vault Collection Agent, see Oracle Audit Vault Collection Agent Installation Guide.

Example

The following example shows how to add a collection agent to Audit Vault:

avca add_agent -agentname TTAgent2 -agenthost stapj40 
AVCA started
Adding agent...
Enter agent user name: <agentusername>
Enter agent user password: <agent user pwd>
Re-enter agent user password: <agent user pwd>
Agent added successfully.

---

create_credential

Creates or updates a credential to be stored in the wallet. This command is run on both the Audit Vault Server and Audit Vault Collection Agent as a script during collector development.

Syntax

avca create_credential -wrl <wallet location> -dbalias <db alias> 

Arguments

Argument	Description
-wrl <wallet location>	The location of the Audit Vault wallet; it is always $ORACLE_HOME/network/admin/avwallet on Linux and UNIX-based systems and ORACLE_HOME\network\ADMIN\avwallet on Windows systems.
-dbalias <db alias>	The database alias. In the Audit Vault Server home the database alias is the SID or Oracle instance identifier. In the Audit Vault Collection Agent home, the database alias is always av.

Usage Notes

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

Example

The following example shows how to create a credential for the source user named srcuser1 in the Collection Agent home.

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.

---

create_wallet

Creates a wallet to hold credentials. This command is run on the Audit Vault Collection Agent.

Syntax

avca create_wallet -wrl <wallet_location> 

Arguments

Argument	Description
-wrl	The wallet location

Usage Notes

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

---

deploy_av

Deploys the av.ear file to another node in an Oracle Real Application Clusters (Oracle RAC) environment. This command is run on the Audit Vault Server.

Syntax

deploy_av -sid <sid> -dbalias <db_alias> 
          -avconsoleport <av_console_port>

Arguments

Argument	Description
-sid <sid>	The Oracle system identifier (SID) for the instance
-dbalias <db_alias>	The database alias
-avconsoleport <av_console_port>	The port number for the Audit Vault Console

Options

None

Usage Notes

In an Oracle RAC environment, AVCA commands must be issued 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.

Note that when the AVCA deploy_av command is issued, a wallet containing the default avadmin entries is also 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 AV 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

The following example shows how to deploy the av.ear file to another node in an Oracle RAC environment. In this example, the AVCA_AVADM environment variable is set to usr/pwd and the -avadm argument is omitted.

avca deploy_av -sid av -dbalias av -avconsoleport 5700

---

drop_agent

Drops a collection agent from Audit Vault. This command is run on the Audit Vault Server.

Syntax

avca drop_agent -agentname <agent name> 

Arguments

Argument	Description
-agentname <agent name>	Specify the collection agent (by collection agent name) to be dropped from Audit Vault.

Usage Notes

• The drop_agent command does not delete the collection agent from Audit Vault; it disables the collection agent. The user can neither add the same collection agent name again nor enable the dropped collection agent.

• An error will be raised if active collectors are still running in the collection agent.

Example

The following example shows how to drop a collection agent named 'OC4JAgent1' from Audit Vault:

avca drop_agent -agentname OC4JAgent1 
AVCA started
Dropping agent...
Agent dropped successfully.

---

generate_csr

Generates certificate requests. This command is run on the Audit Vault Server.

Syntax

generate_csr -certdn <Audit Vault Server host DN> -[keysize 512|1024|2048]
             -out <certificate request output file>

Arguments

Argument	Description
-certdn <Audit Vault Server host DN>	Distinguished name (DN) of the Audit Vault Server host
-[keysize 512|1024|2048]	The key size (in bits). The default key size is 1024 bits.
-out <certificate request output file>	The path and name of the certificate request output file

Options

None

Usage Notes

This command must be used to generate certificate requests. After generating the certificate request, send it to your CA and get it signed and then returned as a signed certificate.

The DN of the Audit Vault Server is provided by the Audit Vault Administrator and 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 generate a certificate request.

avca generate_csr -certdn CN=<valid-AV-hostname>,OU=DBSEC,O=Oracle,ST=CA,C=US -out cert_request.txt

---

help

Displays Help for the AVCA commands. This command is run on both the Audit Vault Server and Audit Vault Collection Agent.

Syntax

avca -help

avca <command> -help

Arguments

Argument	Description
<command>	The name of an AVCA command for which you want Help to appear

Options

None

Usage Notes

None

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>
  ------------------------------------------------

The following 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

---

import_cert

Imports the specified User or Trusted certificate into the wallet. This command is run on the Audit Vault Server.

Syntax

import_cert -cert <User/Trusted certificate> -[trusted]

Arguments

Argument	Description
-cert <User/Trusted certificate>	The path and file name of the certificate to be imported into the wallet
-[trusted]	Optional. A key word to indicate whether the certificate is a Trusted or CA certificate

Options

None

Usage Notes

This certificate must match a pending certificate request in the wallet. The Trusted or CA certificate for this certificate must be imported first.

Example

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

avca import_cert -cert user_certificate.cer

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

avca import_cert -cert ca_certitificate.cer -trusted

---

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

Options

None

Usage Notes

None

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

---

remove_cert

Removes the specified certificate from the wallet. This command is run on the Audit Vault Server.

Syntax

remove_cert -cert <Audit Vault Server host DN> 

Arguments

Argument	Description
-cert <Audit Vault Server host DN>	Distinguished name (DN) of the Audit Vault Server host

Options

None

Usage Notes

The Certificate or Key pair for the DN matching the given DN will be removed from the wallet.

You can use this command, for example, to remove a certificate that expires or is revoked by the CA, and replace it with a renewed certificate.

The DN of the Audit Vault Server is provided by the Audit Vault Administrator and 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 -certdn CN=<valid-AV-hostname>,OU=DBSEC,O=Oracle,ST=CA,C=US

---

secure_agent

Secures the Audit Vault Collection Agent by enabling mutual authentication with the Audit Vault Server. This command is run on the Audit Vault Collection Agent. This command also removes mutual authentication with Audit Vault Server.

Syntax

avca secure_agent -agentkeystore <keystore location>
 -avdn <DN of Audit Vault Server> 
 -agentdn <DN of agent> [-agentkeystorepwd <ketstore pwd>]

avca secure_agent -remove

Arguments

Argument	Description
-agentkeystore <keystore location>	Specify the key store location for this collection agent.
[-agentkeystorepwd <ketstore pwd>]	Specify the key store password for Audit Vault Server. The -agentkeystorepwd argument can be omitted if the corresponding environment variable, AVCA_AGENTKEYSTOREPWD is set to keystore password. If the command-line argument -agentkeystorepwd is specified, then the command-line argument overrides the environment variable. This argument is provided for backward compatibility. For password handling security, do not specify this argument on the command-line nor use the environment variable. Instead, let the command prompt you for the key store password. See the example.
-avdn <DN of Audit Vault Server>	Distinguished name (DN) of the Audit Vault Server
-agentdn <DN of agent>	DN of this Audit Vault collection agent
-remove	Keyword to indicate removing mutual authentication with Audit Vault Server

Usage Notes

• The key store and certificate must be in place at the collection agent side before you execute this command.

• Use the following command to generate a key store:

  $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 collection agent OC4J shuts down and starts up again. The specified collection agent and its collectors must all be manually started again.

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 Audit Vault Collection Agent by disabling mutual authentication with the Audit Vault Server.

avca secure_agent -remove
AVCA started
Restarting agent OC4J...
OC4J restarted successfully.

---

secure_av

Secures Audit Vault Server by enabling mutual authentication with the Audit Vault Collection Agent. This command is run on the Audit Vault Server. This command also removes mutual authentication with Audit Vault Collection Agent.

Syntax

avca secure_av -avkeystore <keystore location> -avtruststore <truststore location>
               [-avkeystorepwd <ketstore pwd>]

avca secure_av -remove

Arguments

Argument	Description
-avkeystore <keystore location>	Specify the key store location for Audit Vault Server.
[-avkeystorepwd <ketstore pwd>]	Specify the key store password for Audit Vault Server. The -avkeystorepwd argument can be omitted if the corresponding environment variable, AVCA_AVKEYSTOREPWD is set to keystore password. If the command-line argument -avkeystorepwd is specified, then the command-line argument overrides the environment variable. This argument is provided for backward compatibility. For password handling security, do not specify this argument on the command-line nor use the environment variable. Instead, let the command prompt you for the key store password. See the example.
-avtruststore <truststore location>	Specify the trust store location for Audit Vault Server.
-remove	Keyword to indicate removing mutual authentication with the Audit Vault Collection Agent.

Usage Notes

• The key store and certificate must be in place at Audit Vault Server before you execute this command.

• Use the following command to generate a key store:

  $ORACLE_HOME/jdk/bin/keytool
  

• When you issue the secure_av command, the Audit Vault Console OC4J will shut down and start up again, requiring you to log in to Audit Vault Console again.

Example

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

avca secure_av -avkeystore /tmp/avkeystore 
-avtruststore /tmp/avkeystore 
Enter keystore 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.0.0  Copyright (c) 1996,2008 Oracle Corporation.  All rights reserved.
http://stacd05.us.oracle.com:5700/av
Oracle Audit Vault 10g is running.
------------------------------------
 
Logs are generated in directory /scratch/10.2.2/av_1/av/log

---

set_warehouse_retention

Controls the amount of data kept online in the data warehouse fact table. This command is run on the Audit Vault Server.

Syntax

avca set_warehouse_retention -intrv <year-month interval>  

Arguments

Argument	Description
-intrv <year-month interval>	Specify the year month interval in the form [+]YY-MM.

Usage Notes

• The interval must be positive.

• The data loaded using the AVCTL refresh_warehouse command is removed automatically based on the warehouse retention specified using the AVCA set_warehouse_retention command.

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 one year is specified.

avca set_warehouse_retention -intrv +01-00 
AVCA started
Setting warehouse retention period...
done.

---

set_warehouse_schedule

Sets the schedule for refreshing data from the raw audit data store to the star schema. This command is run 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>	Specify the schedule name created using the DBMS_SCHEDULER.create_schedule procedure.
-startdate <start date>	Specify 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>	Specify the repeat interval for the schedule using the syntax used in the DBMS_SCHEDULER.create_schedule procedure.
[-dateformat <date format>]	Optionally, specify the date format for the -startdate argument.

Usage Notes

• The schedule can be set using a named schedule created using the DBMS_SCHEDULER.create_schedule procedure, or the schedule can be set 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.

Example

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

The following 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.

The following 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.