6 Registering Hosts and Deploying the Agent

Learn about registering hosts and deploying the agents.

6.1 Registering Hosts on Oracle Audit Vault Server

Learn about registering hosts on Oracle Audit Vault Server.

6.1.1 About Registering Hosts

Learn how to register hosts.

Register a host computer from where audit data is collected. After registering the host, you can deploy and activate the Audit Vault Agent on that host. Audit Vault Agent is a component of Oracle AVDF. It collects audit data from the targets and sends audit data to the Audit Vault Server. A target is a system that you want to monitor and protect. This chapter contains necessary information for registering hosts using the Audit Vault Server console.

After registering the hosts on the Audit Vault Server perform the following steps to be able to collect audit records:

  1. Download the Audit Vault Agent software from the Audit Vault Server console
  2. Deploy the Audit Vault Agent
  3. Activate the Audit Vault Agent
  4. Register one or more targets from which the audit data needs to be collected
  5. Start audit trails using the Audit Vault Server console

6.1.2 Registering Hosts in the Audit Vault Server

Learn about registering hosts in the Audit Vault Server.

To register a host computer in the Audit Vault Server:

  1. Log in to the Audit Vault Server console as an administrator.
  2. Click the Agents tab.
  3. In the left navigation menu, click Agents tab.

    A list of registered Agents is displayed on the page.

  4. Click Register.
  5. In Name field, enter the name of the Audit Vault Agent. This field is mandatory and must not contain special characters. The system connects to the host using the IP address. The name defined here is a logical name of the Agent and is used for descriptive identification. You may use the host name as the Agent name for easy identification.
  6. The IP Address field is mandatory.

    Enter the IP address of the host computer where the Audit Vault Agent is expected to run.

    If the Audit Vault Agent is expected to run on a host with multiple IP addresses (or network interfaces), then follow these steps:

    1. Enter one of the IP addresses or a unique logical IP address.
    2. After setting the IP address, set all the physical IP addresses using which the Audit Vault Agent is expected to connect to the Audit Vault Server as host attributes. Click Add button in the Attributes section.
    3. Enter AGENT_PHYSICAL_ADDRESS_XX in the Name field where XX can be any value between 01 and 99.
    4. Enter a valid IP address in the corresponding Value field.
  7. Click Save.

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

Agent Deployment in a High Availability System

Audit Vault Agent may be associated with multiple IP addresses in the following cases:

  1. Agent installed on a host with multiple network interface cards

  2. Agent installed on a node of high availability cluster

    1. Only one Audit Vault Agent installation is necessary for high availability cluster deployment. The Agent installation is needed only on active node of the cluster. Ensure the Audit Vault Agent installation directory is accessible to all nodes of the cluster.
    2. Cluster management software must be configured to start, stop, and monitor the Agent by providing the necessary input. The Agent must be started automatically by the cluster management software on the active node and stopped automatically on passive nodes.

See Also:

6.1.3 Changing Host Names

Learn about changing host name.

To change the name of a registered host:

  1. If the Audit Vault Agent is already deployed on that host and the Agent is running, then stop the Agent by executing the command below.

    For Linux platform:

    Agent_Home/bin/agentctl stop

    For Windows platform, if Agent is running as a process:

    Agent_Home/bin/agentctl stop

    For Windows platform, if Agent is running as a service:

    Agent_Home/bin/agentctl stopsvc
  2. Log in to the Audit Vault Server console as an administrator. See Using Audit Vault Server Console for more information.
  3. Click the Agents tab.
  4. In the left navigation menu, click Agents.

    A list of registered Agents is displayed on the page.

  5. Click the name of the Agent that you want to change.
  6. In the dialog, change the Name or the IP Address field, and then click Save.
  7. If you have changed either the Agent name or the IP address, and if the Agent has already been deployed on that host, then start the Agent by executing the below command. Enter the new activation key when prompted.

    For Linux platform:

    Agent_Home /bin/agentctl start -k

    For Windows platform, if Agent is running as a process:

    Agent_Home /bin/agentctl start -k

    For Windows platform, if Agent is running as a service:

    Agent_Home /bin/agentctl startsvc -k

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

6.2.1 About Deploying the Audit Vault Agent

Learn about deploying Oracle Audit Vault Agent.

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

For audit trail collection perform the following:

  1. Register the host
  2. Deploy the Audit Vault Agent
  3. Register the target
  4. Add audit trails for the targets

To decide on the specific host to deploy the Agent, follow these guidelines.

Trail Type Guideline

TABLE

To configure TABLE trail, the Audit Vault Agent can be deployed either on a remote host or on the host machine where the database is running.

DIRECTORY

To configure DIRECTORY trail, the Audit Vault Agent can be deployed either on the host machine where DIRECTORY path exists, or on a machine from where the DIRECTORY path can be accessed.

TRANSACTION LOG

To configure TRANSACTION LOG trail, the Audit Vault Agent can be deployed either on the host machine where the GoldenGate Integrated Extract path exists, or on a machine from where it can be accessed.

Table 6-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, 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:

6.2.2 Audit Vault Agent Requirements

Learn about the Audit Vault Agent requirements.

Recommended prerequisites for installing Audit Vault Agent:

  1. Ensure to meet the system requirements. See Product Compatibility Matrix.
  2. Ensure to meet the following Java requirements:

  3. The host machine on which the Audit Vault Agent is deployed must have at least 512 MB RAM.
  4. Apply the latest security patches of OpenSSL libraries available from the OS vendor for the specific OS version on the host machine.
  5. The host machine on which the Audit Vault Agent is deployed must have connectivity to the Audit Vault Server. In case of high availability set up, it must have connectivity to both the primary and standby Audit Vault Servers.
  6. The Audit Vault Server uses 2 ports (1521 and 1522 by default) for Agent communication. Ensure to configure the ports appropriately for this communication.
  7. If NAT (Network Address Translation) is used in the network between Audit Vault Server and the host machine where agent is deployed, then ensure the IP address of the host machine is resolvable from Audit Vault Server.
  8. The user must have the required OS permissions to install the Agent. The user must be able to access the audit trail location in case of directory audit trails. See About Deploying the Audit Vault Agent for the OS permissions required for installing the Agent.

6.2.3 Steps Required to Deploy and Activate the Audit Vault Agent

Learn about the procedures to deploy and activate Oracle 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.
  3. Activating and Starting the Audit Vault Agent.

6.2.4 Registering the Host

Learn about the procedure for registering the host.

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

6.2.5 Deploying the Audit Vault Agent

Learn about deploying the Audit Vault Agent.

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 all security patches from the OS vendor is applied on the host machine.

See Also:

The Audit Vault Agent is supported on Unix and Microsoft Windows platforms. It requires Java version 1.8 to be installed on the host machine. See Product Compatibility Matrix for Agent platform support details for the current release and for the supported Java versions.

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

  1. Log in to the Audit Vault Server console as an administrator.
  2. Click the Agents tab.
  3. In the left navigation menu:

    A list of downloadable agent software files are displayed on the page.

  4. Click the Download button against the platform type, 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.

  5. Using an OS user account, copy the agent.jar file to the target's host machine.

    Best Practice:

    Do not install the Audit Vault Agent as root user.

  6. 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 target, ensure the Audit Vault Agent is installed on a computer in which SQL*Net can communicate with the Sybase ASE database.
  7. On a Microsoft Windows system, start a command prompt with Run as Administrator.
  8. 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 Microsoft Windows system, this command automatically registers a Microsoft 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, then do not delete the existing Agent_Home directory.

6.2.6 Activating and Starting the Audit Vault Agent

Learn how to activate and start Oracle Audit Vault Agent.

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

Prerequisites

To activate and start the agent:

  1. Click the Hosts tab.
  2. Click the Agents tab.
  3. In the left navigation menu, click Agents.

    A list of registered hosts are displayed on the page.

  4. On this page, make a note of the Agent Activation Key for this host.
  5. On the host machine, change directory as follows:

    cd Agent_Home/bin

    Agent_Home is the directory created in the step 8 above.

  6. Run one of the following commands 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:

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

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

6.2.7.2 Registering the Audit Vault Agent as a Windows Service

You can register the Oracle Audit Vault agent as a Windows service.

Note: 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.

To register the Audit Vault Agent as a Windows Service:

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

agentctl registersvc

This adds the Oracle 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.

Note that 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.

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

6.3 Stopping, Starting, and Other Agent Operations

Learn about starting and stopping the agent and other operations.

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

6.3.1.1 Stopping and Starting the Agent on Unix Hosts

Learn about stopping and starting the Agent on Unix hosts.

To start the Audit Vault Agent after initial activation, run the following command from the Agent_Home/bin directory on the host machine:

agentctl start

To stop the Audit Vault Agent run the following command from the Agent_Home/bin directory on the host machine:

agentctl stop

Note:

After the agentctl stop command, execute agentctl status command to ensure the Agent is in STOPPED state before executing the agentctl start command again.
6.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.

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.

6.3.1.3 Autostarting the Agent on Windows Hosts

Learn about autostarting the agent on Microsoft 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 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.

6.3.2 Changing the Logging Level for the Audit Vault Agent

Learn how to change the logging level for Oracle Audit Vault Agent.

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

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

The following logging levels are listed in the order of the amount of information written to log files, where debug provides 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 "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.

6.3.3 Viewing the Status and Details of Audit Vault Agent

Learn about viewing the status and details of 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 Using Audit Vault Server Console for more information.

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

  1. Click the Agents tab.
  2. In the left navigation menu, click Agents.

    A list of registered Agents is displayed on the page.

  3. In this list of registered Agents, check the Agent Status, Host Monitor Status, Agent Activation Key, Agent Details, and Host Monitor Details columns for the Agent that you are interested in.
  4. To see the audit trails for a specific Agent host, click View Audit Trails in the Agent Details column.

6.3.4 Deactivating and Removing Audit Vault Agent

Learn about deactivating and removing Audit Vault Agent.

Use this procedure to deactivate and remove 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 Home tab, then click Audit Trails.

    2. In the left navigation menu, click Audit Trails to display a page of the available audit trails.

    3. Select the check boxes for each audit trail that you want to stop, 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 Agents tab, and then in the left navigation menu, select Agents.

    2. Select the check box for each host name that you want to deactivate, and then click Deactivate.

    3. Optionally, drop the host by selecting the check box for 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 targets. It sends this data to the specific Audit Vault Server. To configure the audit trail collection from the existing 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.

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

6.5 Deploying Plug-ins and Registering Plug-in Hosts

Learn about deploying plug-ins and registering plug-in hosts.

6.5.1 About Plug-ins

Learn about plug-ins for Oracle Audit Vault Server.

Each type of 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 target types. New plug-ins are available from Oracle Technology Network or third parties.

A plug-in supports only one target type. However, you may deploy more than one plug-in for the same 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 target type. You can select the specific plug-in to use when you configure audit trail collections.

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

Deploying a plug-in consists of three steps:

  1. Ensuring that Auditing is Enabled in A Target

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

  3. Deploying and Activating the Plug-in

6.5.2 Ensuring that Auditing is Enabled in A Target

Learn how to ensure that auditing is enabled in a target.

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

See Also:

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

6.5.3 Registering the Plug-in Host in Audit Vault Server

Learn about registering a plug-in host in Oracle Audit Vault Server.

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

6.5.4 Deploying and Activating the Plug-in

Learn about deploying and activating a plug-in in Oracle Audit Vault Server.

To deploy and activate a plug-in:

  1. Log in to the Audit Vault Server console as an administrator.
  2. Click the Settings tab.
  3. In the left navigation menu, select System.
    A status page appears, with pane for Configuration and Monitoring.
  4. In the Monitoring pane, click Plug-ins.

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

  5. 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 file.
  6. Click Deploy Plug-in, then click Deploy.

    The new plug-in is listed in the Plug-ins page. The updated agent.jar file has a new Deployed Time shown in this page.

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

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

    Register the host machine in case it is not registered.

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

6.5.5 Un-Deploying Plug-ins

Learn about 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.
  3. In the left navigation menu, select System.
    A status page appears, with pane for Configuration and Monitoring.
  4. In the Monitoring pane, click Plug-ins.
  5. Select the plug-in that you want, and then click Un-deploy.

6.6 Deleting Hosts from Audit Vault Server

Learn how to delete hosts from Audit Vault Server.

When you delete a host, if you want to register it again to collect audit data, then 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 Agents tab.
  3. In the left navigation menu, click Agents.

    A list of registered Agents is displayed on the page.

  4. Select the check boxes for the hosts that you want to delete, and then click Delete.

    See Also: