5 Registering Hosts and Deploying the Agent

Topics

• Registering Hosts in the Audit Vault Server

• Deploying and Activating the Audit Vault Agent on Host Computers

• Stopping, Starting, and Other Agent Operations

• Updating Oracle Audit Vault Agent

• Deploying Plug-ins and Registering Plug-in Hosts

• Deleting Hosts from the Audit Vault Server

5.1 Registering Hosts in the Audit Vault Server

Topics

• About Registering Hosts

• Registering Hosts in the Audit Vault Server

• Changing Host Names

5.1.1 About Registering Hosts

If you want to collect audit data from a secured target, you must configure a connection between the Audit Vault Server and the host machine where the Audit Vault Agent resides for that secured target (usually the same computer as the secured target).

After registering a host, you must then deploy and activate the Audit Vault Agent on that host.

This chapter assumes the Audit Vault Agent is deployed on the secured target host, and describes the procedures for registering hosts using the Audit Vault Server console UI.

After you register hosts and deploy the Audit Vault Agent on them, in order to start audit trail collections you must also register the secured targets, configure audit trails, and start audit trail collections manually.

See Also:

• Registering Secured Targets

• Configuring and Managing Audit Trail Collection

• Summary of Configuration Steps to understand the high-level workflow for configuring the Oracle Audit Vault and Database Firewall system.

• Using the Audit Vault Command-Line Interface

• Deploying and Activating the Audit Vault Agent on Host Computers

5.1.2 Registering Hosts in the Audit Vault Server

Sections in this chapter give information on configuring hosts that is specific to each secured target type. However, the procedure for registering any host machine in the Audit Vault Server is the same.

To register a host machine in the Audit Vault Server:

1. Log in to the Audit Vault Server console as an administrator.
2. Click the Hosts tab.

   A list of the registered hosts, if present, appears in the Hosts page.

3. Click Register.
4. Enter the Host Name which is mandatory. Entering the Host IP address is optional.

   If you enter a host name only, you must have a DNS server configured.

5. Click Save.

   An Agent Activation Key is automatically generated when you register the host.

See Also:

• REGISTER HOST for the command line syntax to register a host.

• Configuring or Changing the Oracle Audit Vault Server Services to configure DNS server.

• Working with Lists of Objects in the UI to control the view of registered hosts listed in the Hosts page.

• Logging in to the Audit Vault Server Console UI

5.1.3 Changing Host Names

After you change a host name, the change takes place immediately. You do not need to restart the host Audit Vault Server.

Caution:

Do not manually reboot the system after changing a host name as this may put the system in an inconsistent state. Wait up to 10 minutes for the system to automatically reboot.

Prerequisite

Log in to the Audit Vault Server console as an administrator. See Logging in to the Audit Vault Server Console UI for more information.

To change the name of a registered host:

1. Click the Hosts tab.
2. Click the name of the host you want to change.
3. In the Modify Host page, change the Host Name field, and then click Save.
4. Wait for the system to automatically reboot.

   This may take up to 10 minutes. Do not manually reboot the system.

5.2 Deploying and Activating the Audit Vault Agent on Host Computers

Learn about how to deploy and activate the Audit Vault Agent on host computers.

5.2.1 About Deploying the Audit Vault Agent

In order to collect audit trails from secured targets, you must deploy the Audit Vault Agent on a host computer usually the same computer where the secured target resides. The Audit Vault Agent includes plug-ins for each secured target type, as well as host monitoring functionality.

In addition to deploying the Audit Vault Agent, in order to start audit trail collections you must also register each host, register secured targets, configure audit trails, and start audit trail collections manually (thereafter, audit trails start automatically when the Audit Vault Agent is restarted, or updated due to an Audit Vault Server update).

To deploy the Audit Vault Agent in Oracle RAC environment, follow these guidelines.

Trail Type	Guideline
TABLE	To configure TABLE trail, deploy one Audit Vault Agent on a remote host.
DIRECTORY	To configure DIRECTORY trail, deploy one Audit Vault Agent. This is sufficient in case the audit trails are configured as described in section Configuring Audit Trail Collection for Oracle Real Application Clusters.
TRANSACTION LOG (REDO)	To configure TRANSACTION LOG trail, deploy one Audit Vault Agent on a remote host.

Table 5-1 OS Permission Required For Installing The Agent

Operating System	User
Linux/Unix	Any user.
Windows	Any user for running the Agent from the command prompt. admin user for registering as a service.

Note:

• Host Monitor on Linux/Unix/AIX/Solaris platforms must be installed as root user.

• If directory trails are used then Agent installation user should have read permission on the audit files.

• Host Monitor on Windows platform is not certified in release 12.2.0.11.0.

  If your installation is 12.2.0.10.0 and prior, then Host Monitor must be installed as admin user.

• Ensure that the host machine has OpenSSL 1.0.1 (or later) installed for Audit Vault Agent

See Also:

• Registering Hosts in the Audit Vault Server

• Registering Secured Targets and Creating Groups

• Configuring and Managing Audit Trail Collection

• Summary of Configuration Steps to understand the high-level workflow for configuring the Oracle Audit Vault and Database Firewall system.

• Adding an Audit Trail in the Audit Vault Server to configure an audit trail.

5.2.2 Steps Required to Deploy and Activate the Audit Vault Agent

Deploying and activating the Audit Vault Agent on a host machine consists of these steps:

1. Registering the Host
2. Deploying the Audit Vault Agent on the Host Computer.
3. Activating and Starting the Audit Vault Agent.

5.2.3 Registering the Host

To register the host on which you deployed the Audit Vault Agent, follow the procedure in "Registering Hosts in the Audit Vault Server".

5.2.4 Deploying the Audit Vault Agent on the Host Computer

You must use an OS user account to deploy the Audit Vault Agent. In this step, you copy the agent.jar file from the Audit Vault Server and deploy this file on the host machine.

Note:

Ensure that the host machine has OpenSSL 1.0.1 (or later) installed for Audit Vault Agent.

See Also:

The Audit Vault Agent is supported on Unix, Windows, and HP-UX Itanium platforms, and requires Java version 1.8 to be installed on the host computer. See Oracle Audit Vault and Database Firewall Installation Guide for Agent platform support details for the current release and for the supported Java versions. For supported platforms in prior releases, see Article 1536380.1 at the Oracle Support website: https://support.oracle.com

To copy and deploy the Audit Vault Agent to the host machine:

1. Log in to the Audit Vault Server console as an administrator.
2. Click the Hosts tab, and then from the Hosts menu, click Agent.

   The Agent and host monitor files are listed.

3. Click the Download button next to the Agent file, and then save the agent.jar file to a location of your choice.

   The download process copies the agent.jar file from the Audit Vault Server. Ensure that you always use this agent.jar file when you deploy the agent.

4. Using an OS user account, copy the agent.jar file to the secured target's host computer.

   Best Practice:

   Do not install the Audit Vault Agent as root user.

5. On the host machine, set the JAVA_HOME environment variable to the installation directory of the Jdk, and make sure the Java executable corresponds to this JAVA_HOME setting.

   Note: For a Sybase ASE secured target, ensure that the Audit Vault Agent is installed on a computer in which SQL*Net can communicate with the Sybase ASE database.

6. Start a command prompt with Run as Administrator.
7. In the directory where you placed the agent.jar file, extract it by running:

   java -jar agent.jar -d Agent_Home

   This creates a directory by the name you enter for Agent_Home, and installs the Audit Vault Agent in that directory.

   On a Windows system, this command automatically registers a Windows service named OracleAVAgent.

Caution:

After deploying the Audit Vault Agent, do not delete the Agent_Home directory unless directed to do so by Oracle Support. If you are updating an existing Audit Vault Agent, do not delete the existing Agent_Home directory.

5.2.5 Activating and Starting the Audit Vault Agent

In this step, you activate the Audit Vault Agent with the Agent Activation Key and start the Agent.

Prerequisites

• Follow and complete the procedure in Registering Hosts in the Audit Vault Server.

• Log in to the Audit Vault Server console as an administrator. See Logging in to the Audit Vault Server Console UI for more information.

To activate and start the agent:

1. Click on the Hosts tab.
2. On the Hosts tab, make a note of the Agent Activation Key for this host.
3. On the host machine, change directory as follows:

   cd Agent_Home/bin

   Agent_Home is the directory created in the step 7 above.

4. Run one of the following command and provide the Agent Activation Key:

   agentctl start -k 
   Enter Activation Key:
   

   Enter the activation key when prompted. This key will not be displayed as you type it.

   Note: the -k argument is not needed after the initial agentctl start command.

See Also:

• Registering and Unregistering the Audit Vault Agent as a Windows Service to start or stop the agent Windows service through the Windows Services applet in the Windows Control Panel, in case the Agent is deployed on a Microsoft Windows host computer.

• ACTIVATE HOST for the command line syntax to activate the Agent.

5.2.6 Registering and Unregistering the Audit Vault Agent as a Windows Service

Learn about registering and unregistering Oracle Audit Vault Agent as a Windows service.

Note:

The Audit Vault Agent as a Windows Service is not supported in Oracle Audit Vault and Database Firewall release 12.2.0.7.0. Use the console mode to stop or start the Agent.

5.2.6.1 About the Audit Vault Agent Windows Service

Learn about the Audit Vault Agent Windows service.

When you deploy the Audit Vault Agent on a Microsoft Windows host computer, during agent deployment, a Microsoft Windows service named OracleAVAgent is automatically registered. Additionally, you can register and unregister the agent service using the agentctl command.

When the Audit Vault Agent is registered as a Windows service, you can start or stop the service through the Windows Services applet in the Windows Control Panel.

See Also:

Deploying the Audit Vault Agent on the Host Computer

5.2.6.2 Registering the Audit Vault Agent as a Windows Service

Deploying the Audit Vault Agent on a Windows host automatically registers a Windows service named agentctl. Use this procedure to register the Windows service again.

Prerequisite

Ensure to comply with one of the following prerequisites:

• Install Visual C++ Redistributable for Visual Studio 2012 Update 4 package from Microsoft on the Windows target machine. Ensure msvcr110.dll file is available in any of the directories defined in the PATH variable.
• Add the directory path where msvcr110.dll is present to the PATH variable. For example: C:\Windows\System32
• Copy the msvcr110.dll file that is compatible with the Windows target machine to the <Agent Home>/bin and <Agent Home>/bin/mswin-x86-64 folders.

To register the Audit Vault Agent as a Windows Service, run the following command on the host machine from the Agent_Home\bin directory:

agentctl registersvc

This adds the Audit Vault Agent service in the Windows services registry.

Note:

• Be sure to set the Audit Vault Agent service to use the credentials of the Windows OS user account that was used to deploy the Agent using the java -jar command. Do this in the service Properties dialogue.
• In the Service Properties dialogue, local user name entries in the This account field should be formatted as in the following example: user name jdoe should be entered as .\jdoe. Refer to Microsoft Windows documentation for procedures to do so.

5.2.6.3 Unregistering the Audit Vault Agent as a Windows Service

You can use two methods to unregister the Oracle Audit Vault Agent as a Windows service.

To unregister the Oracle Audit Vault Agent as a Windows Service, use one of the following methods:

• Method 1 (Recommended)

  On the host machine, run the following command from the Agent_Home\bin directory:

  agentctl unregistersvc

  This removes the Oracle Audit Vault Agent service from the Windows services registry.

• Method 2

  If Method 1 fails, then execute the following from the Windows command prompt (Run as Administrator):

  cmd> sc delete OracleAVAgent

  You can verify that the Audit Vault Agent has been deleted by executing the following query from the Windows command prompt (Run as Administrator):

  cmd> sc queryex OracleAVAgent

5.3 Stopping, Starting, and Other Agent Operations

Topics

• Stopping and Starting Oracle Audit Vault Agent

• Changing the Logging Level for the Audit Vault Agent

• Viewing the Status and Details of an Audit Vault Agent

• Deactivating and Removing the Audit Vault Agent

5.3.1 Stopping and Starting Oracle Audit Vault Agent

Learn about stopping and starting Oracle Audit Vault Agent.

Topics

Important:

Stop and start the Audit Vault Agent as the same OS user account that you used during installation.

5.3.1.1 Stopping and Starting the Agent on Unix Hosts

To stop or start the Audit Vault Agent after initial activation and start, run one of the following commands from the Agent_Home/bin directory on the host machine:

agentctl stop

agentctl start

5.3.1.2 Stopping and Starting the Agent on Windows Hosts

Learn about stopping and starting the agent on Microsoft Windows hosts.

The Audit Vault Agent is automatically registered as a Windows service when you deploy the Agent on a Windows host. We recommend that you run the Agent as Windows service so that it can keep running after the user logs out.

See Also::

Registering and Unregistering the Audit Vault Agent as a Windows Service

To stop or start the Agent Windows service

Use one of the methods below:

• In the Windows GUI (Control Panel > Administrative Tools > Services), find the Oracle Audit Vault Agent service, and then right-click it to select Start or Stop.

• Run one of these commands from the Agent_Home\bin directory on the host machine:

  agentctl stopsvc

  agentctl startsvc

To check that the Windows service is stopped

Run this command:

cmd> sc queryex OracleAVAgent

You should see the agent Windows service in a STOPPED state.

To stop or start the Agent in console mode

start /b agentctl stop

start /b agentctl start

To forcibly stop the Agent in console mode

agentctl stop -force

Note:

This is not a recommended option to stop the Agent. Use it only in case the Agent goes into an unreachable state for a long time and cannot be restarted or stopped. In such a scenario, use this option to forcibly stop and later restart the agent.

To restart the agent use the agentctl start command.

5.3.1.3 Autostarting the Agent on Windows Hosts

You can configure the agent service to start automatically on a Windows host.

1. Open the Services Management Console.

   From the Start menu, select Run, and in the Run dialog box, enter services.msc to start the Services Management Console.

2. Right-click on Oracle Audit Vault Agent and from the menu, select Properties.
3. In the Properties dialog box, set the Startup type setting to Automatic.
4. Click OK.
5. Close the Services Management Console.

5.3.2 Changing the Logging Level for the Audit Vault Agent

The logging level you set affects the amount of information written to the log files. You may need to take this into account for disc space limitations.

Log files are located in the Agent_Home/av/log directory.

The following logging levels are listed in the order of amount of information written to log files, with debug providing the most information:

• error - Writes only error messages

• warning - (Default) Writes warning and error messages

• info - Writes informational, warning, and error messages

• debug - Writes detailed messages for debugging purposes

Using the Audit Vault Server Console to Change Logging Levels

To change the logging level for the Audit Vault Agent using the Audit Vault Server UI, see "Changing Logging Levels and Clearing Diagnostic Logs".

Using AVCLI to Change the Agent Logging Level

To change the logging level for the Audit Vault Agent using the AVCLI utility:

1. Ensure that you are logged into AVCLI on the Audit Vault Server.

2. Run the ALTER HOST command.

   The syntax is as follows:

   ALTER HOST host_name SET LOGLEVEL=av.agent:log_level

   In this specification:

   • host_name: The name of the host where the Audit Vault Agent is deployed.

   • log_level: Enter a value of info, warn, debug, or error.

5.3.3 Viewing the Status and Details of an Audit Vault Agent

You can view an Audit Vault Agent's status and details such as activation key, platform, version, location, and other details.

Prerequisite

Log in to the Audit Vault Server console as an administrator. See Logging in to the Audit Vault Server Console UI for more information.

To view the status and details of an Audit Vault Agent:

1. Click the Hosts tab.
2. Check the Agent Status, Agent Activation Key, and Agent Details columns for the host that you are interested in.
3. To see the audit trails for a specific agent host, click View Audit Trails in the Agent Details column.

5.3.4 Deactivating and Removing the Audit Vault Agent

Use this procedure to deactivate and remove the Audit Vault Agent.

See Also:

If you have registered the Audit Vault Agent as a Windows service, see Registering and Unregistering the Audit Vault Agent as a Windows Service to unregister the service.

To deactivate and remove the Audit Vault Agent:

1. Stop all audit trails being collected by the Audit Vault Agent.

   1. In the Audit Vault Server console, click the Hosts tab, then click Audit Trails.

   2. Select the audit trails being collected by this Audit Vault Agent, and then click Stop.

2. Stop the Audit Vault Agent by running the following command on the host computer:

   agentctl stop

3. Deactivate the Audit Vault Agent on the host computer:

   1. In the Audit Vault Server console, click the Hosts tab.

   2. Select the host name, and then click Deactivate.

   3. Optionally, drop the host by selecting it, and then clicking Delete.

4. Delete the Audit Vault Agent home directory on the host computer.

Note:

The Audit Vault Agent deployed on a host is associated with the specific Audit Vault Server from where it was downloaded. This Audit Vault Agent collects audit data from the configured secured targets. It sends this data to the specific Audit Vault Server. To configure the audit trail collection from the existing secured targets to a different Audit Vault Server, you should deactivate, remove the existing Agent, download the Audit Vault Agent installation file from the new Audit Vault Server, and install it on the target host. This scenario is different from updating the existing Auditing Vault Agent.

5.4 Updating Oracle Audit Vault Agent

Learn about updating Oracle Audit Vault Agent.

As of Oracle Audit Vault and Database Firewall 12.1.1 BP2, when you update the Audit Vault Server to a future release, the Audit Vault Agent is automatically updated.

If your current release is prior to 12.1.1 BP2, then refer to the README included with upgrade software or patch updates for instructions on how to update the Audit Vault Agent.

As of Oracle Audit Vault and Database Firewall 12.2.0, when you upgrade the Audit Vault Server to a later version, or restart the Audit Vault Agent, you no longer need to restart audit trails manually. The audit trails associated with this Audit Vault Agent automatically restart if you have not explicitly stopped them. If you upgrade the Audit Vault Server to 12.2.0 from a prior release, audit trails associated with the updated Agents will automatically restart if the trails have a single plug-in.

See Also:

Oracle Audit Vault and Database Firewall Installation Guide for information about downloading upgrade software.

5.5 Deploying Plug-ins and Registering Plug-in Hosts

Topics

• About Plug-ins

• Ensuring that Auditing is Enabled in the Secured Target

• Registering the Plug-in Host in Audit Vault Server

• Deploying and Activating the Plug-in

• Un-Deploying Plug-ins

5.5.1 About Plug-ins

Each type of secured target has a corresponding software plug-in in the Audit Vault Server, which enables the Audit Vault Agent to collect audit data. You can deploy more plug-ins, in addition to those shipped with Oracle Audit Vault and Database Firewall, in order to collect audit data from more secured target types. New plug-ins are available from Oracle Technology Network or third parties.

A plug-in supports only one secured target type. However, you may deploy more than one plug-in for the same secured target type if, for example, you acquired each plug-in from a different developer, or each plug-in supports a specific type of audit trail for the same secured target type. You can select the specific plug-in to use when you configure audit trail collections.

To start collecting audit data from the secured target type associated with a plug-in, you must also add the secured target in the Audit Vault Server, then configure and manually start audit trail collection.

See Also:

Configuring Secured Targets, Audit Trails, and Enforcement Points

Deploying a plug-in consists of three steps:

1. Ensuring that Auditing is Enabled in the Secured Target

2. Registering the Plug-in Host in Audit Vault Server

3. Deploying and Activating the Plug-in

5.5.2 Ensuring that Auditing is Enabled in the Secured Target

Ensure that auditing has been enabled in the secured target. See the secured target's product documentation for more information.

See Also:

Ensuring that Auditing is Enabled on the Secured Target for information on plug-ins for Oracle Database.

5.5.3 Registering the Plug-in Host in Audit Vault Server

To register a host in the Audit Vault Server, see "Registering Hosts in the Audit Vault Server".

5.5.4 Deploying and Activating the Plug-in

To deploy and activate a plug-in:

1. Log in to the Audit Vault Server console as an administrator.
2. Click the Settings tab, and from the System menu, click Plug-ins.

   The Plug-ins page lists the currently deployed plug-ins:

   
   

   
   Description of the illustration GUID-31AF499E-5B3E-4785-B65B-989F9C592F53-default.gif

   
   
3. Plug-in archives are available from Oracle Technology Network or a third party. Copy the plug-in archive to the Audit Vault Server, and make a note of the location of the file. Click Deploy, and in the Plug-in Archive field, enter or browse for the name of the plug-in archive.
   
   

   
   Description of the illustration GUID-71DB281F-C019-4D05-B362-DD97121E5022-default.gif

   
   
4. Click Deploy Plug-in.

   The new plug-in is listed in the Hosts tab, Agent page, under Plug-ins. The updated agent.jar file has a new Agent Generation Time shown in the Agent page.

   The Hosts page displays an Agent Generation Time column for each registered host, indicating the version of the agent.jar on that host.

5. Copy the updated agent.jar file to each registered host machine.

   Register the host machine in case it is not registered.

6. On the host machine, extract the agent:

   java -jar agent.jar
   

   Note:

   You cannot download the agent during the same login session in which you deploy a plug-in, since the agent.jar is being updated. However, users in other sessions will be able to download the most current version of agent.jar until the plug-in deployment process is complete and a new version is available.

   See Also:

   • Logging in to the Audit Vault Server Console UI

   • Registering Hosts in the Audit Vault Server

5.5.5 Un-Deploying Plug-ins

To un-deploy a plug-in:

1. Log in to the Audit Vault Server console as an administrator.
2. Click the Settings tab, and from the System menu, click Plug-ins.
3. Select the plug-in you want, and then click Un-deploy.

   See Also:

   Logging in to the Audit Vault Server Console UI

5.6 Deleting Hosts from the Audit Vault Server

When you delete a host, if you want to register it again to collect audit data, you must reinstall the Audit Vault Agent on this host.

To delete hosts:

1. Log in to the Audit Vault Server console as an administrator.
2. Click the Hosts tab.

   A list of the registered hosts, if present, appears in the Hosts page.

3. Select the host(s) you want to delete, and then click Delete.

   See Also:

   • Working with Lists of Objects in the UI to control the view of registered hosts listed.

   • Logging in to the Audit Vault Server Console UI