Deploying the Audit Vault Agent on Host Computers

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

Note: When you register a host on the Audit Vault Server, an activation key is generated. When you deploy the Audit Vault Agent on the host computer, you need to provide the corresponding activation key, as discussed in the following procedures.

Audit Vault Agent Requirements

Learn about the Audit Vault Agent requirements.

Note: You can use agentless collection instead of the Audit Vault Agent for Oracle Database table audit trails and Microsoft SQL Server directory audit trails for .sqlaudit and .xel (Extended Events) files. The total number of audit trails configured for agentless collection must not exceed 20. See Adding Audit Trails with Agentless Collection.

Recommended Prerequisites for Installing Audit Vault Agent

1. Ensure that you meet the system requirements. See Product Compatibility Matrix.

2. Ensure that you meet the following Java requirements:

   • Install the supported Java version on the Audit Vault Agent. See Audit Vault Agent: Supported and Tested Java Runtime Environment.

   • Apply the latest Java patches.

   • Point the JAVA_HOME to the JRE/JDK directory and set the path before installing the Audit Vault Agent.

3. Ensure that the host machine on which the Audit Vault Agent is deployed has at least 512 MB RAM.

4. Ensure that the host machine on which the Audit Vault Agent is deployed has connectivity to the Audit Vault Server.

   In a high availability environment, it must have connectivity to both primary and standby Audit Vault Servers.

5. Ensure that you configure two Audit Vault Server ports (1521 and 7447 by default) for communication with the Audit Vault Agent.

6. If you use Network Address Translation (NAT) in the network between the Audit Vault Server and the host machine where the agent is deployed, then ensure that the IP address of the host machine is resolvable from the Audit Vault Server.

7. Ensure that the user has the required OS permissions to install the agent.

   For directory audit trails, the user must be able to access the audit trail location. See About Deploying the Audit Vault Agent for the OS permissions that are required for installing the agent.

8. Ensure that the Audit Vault Agent home directory is access protected.

   Only the Agent user should have write or execute permissions on the agent home directory.

9. Ensure that the Audit Vault Agent host machine system settings are access protected to prevent malicious users from making modification.

10. Ensure that the system time of the Audit Vault Agent and the target are synchronized.

    They can be in different time zones. The time difference between these two systems (considering time zone conversion) should not exceed two seconds.

Additional Requirements for Starting the Audit Vault Agent as a Service on Windows

You can comply with one of the following prerequisites:

• Install the Visual C++ Redistributable for Visual Studio 2017 package from Microsoft on the Windows host machine.

  Ensure that the vcruntime140.dll file is available in the C:\Windows\System32 directory.

• If the vcruntime140.dll file is not present, then add it to the <Agent Home>/bin and <Agent Home>/bin/mswin-x86-64 directories.

Audit Vault Agent Machine Java Best Practices

Learn some best practices regarding Java on the Audit Vault Agent machine.

1. Ensure installation of Java and the Java home directory is managed by a trusted user.

2. If Java is upgraded to a major version or if it is patched with security updates, then restart the Audit Vault Agent. This ensures the Audit Vault Agent runs with the updated Java.

Validation During Audit Vault Agent Deployment

Learn about validations performed by Oracle Oracle Database Security Central when deploying the Audit Vault Agent.

Some validations are performed when deploying Audit Vault Agent.

The following validations are performed when running the agentctl start command. These requirements are mandatory and have to be complied, without which the Audit Vault Agent installation cannot be completed.

• Minimum java version is installed on the host machine as per Audit Vault Agent: Supported and Tested Java Runtime Environment.

• Audit Vault Agent is being installed on the supported operating system version as per Product Compatibility Matrix.

• The Agent machine on which the Audit Vault Agent is being deployed can connect to the Audit Vault Server.

Ensure to comply with the requirements on the Agent machine:

• The Agent machine has a minimum of 512MB available space.

• The Agent machine must be able to connect to the Audit Vault Server.

• Sufficient permissions required to install the Audit Vault Agent are available.

About Deploying the Audit Vault Agent

Audit Vault Agent collects audit trail data from targets. The host computer where you deploy the Audit Vault Agent depends on the type of audit trail that you want to collect. The Audit Vault Agent includes plug-ins for each target type.

Use the following guidelines to choose the host computer where you need to deploy the Audit Vault Agent:

Trail Type	Guideline for Host Computer
TABLE	Deploy the Audit Vault Agent on a remote host or on the host machine where the database is running.
DIRECTORY	Deploy the Audit Vault Agent on the host machine where the DIRECTORY path exists or on a machine from which the DIRECTORY path can be accessed.
TRANSACTION LOG	Deploy the Audit Vault Agent on the host machine where the GoldenGate Integrated Extract path exists or on a machine from which it can be accessed.
NETWORK	Deploy the Audit Vault Agent on the host machine where the database is running.

OS Permissions for Installing the Agent

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

Note:

• Host Monitor Agent 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 Agent on Windows platform, must be installed as admin user.

Deploying Audit Vault Agent Remotely or Locally

Table 1 Remote Agent or Local Agent

Trail Type	Audit Vault Server Location	Agent Type	Detailed Information
Directory	On-premises	Remote Agent Not installed on the target machine	Audit data is written to the local disk. The local disk is mounted on the remote Agent machine as NFS (Network File System). Remote Agent is not installed on the target machine. Remote Agent should have access to the mounted NFS. Audit data read time includes the network latency involved in accessing NFS. This deployment can be used when the operating system of the target machine is not supported for Audit Vault Agent installation. This deployment can be used when the target machine does not have sufficient memory or CPU resources for the Audit Vault Agent processes. For Oracle Linux operating system, it is recommended to use Kerberos to secure NFS. For non Oracle Linux operating systems, follow the respective OS recommendations to secure NFS.
Directory	On-premises	Local Agent Installed on the target machine	Audit data is written to the local disk. The local Audit Vault Agent is installed on the target machine. The local Audit Vault Agent should have access to the local disk. Audit data read time has no network latency. This deployment can be used when the operating system of the target machine is supported for Audit Vault Agent installation. This deployment can be used when the target machine has sufficient memory and CPU resources for the Audit Vault Agent processes.
Directory	OCI (Oracle Cloud Infrastructure)	Remote Agent Not installed on the target machine	Audit data is written to the local disk. The local disk is mounted on the remote Agent machine as NFS. Remote Agent should have access to the mounted NFS. Remote Agent is not installed on the target machine. If the target is on-premises, then the remote Agent must also be installed on-premises. If the target is on OCI, then the remote Agent must be installed on OCI. OCI virtual firewall for VCN must be configured to allow ingress traffic on ports 1522 and 7447 for Audit Vault Server. This deployment can be used when the operating system of the target machine is not supported for Audit Vault Agent installation. This deployment can be used when the target machine does not have sufficient memory or CPU resources for the Audit Vault Agent processes. For Oracle Linux operating system, it is recommended to use Kerberos to secure NFS. For non Oracle Linux operating systems, follow the respective OS recommendations to secure NFS.
Directory	OCI (Oracle Cloud Infrastructure)	Local Agent Installed on the target machine	Audit data is written to the local disk. The local Audit Vault Agent is installed on the target machine. The local Audit Vault Agent should have access to the local disk. Audit data read time has no network latency. This deployment can be used when the operating system of the target machine is supported for Audit Vault Agent installation. This deployment can be used when the target machine has sufficient memory and CPU resources for the Audit Vault Agent processes.
Table	On-premises	Remote Agent Not installed on the target machine	Audit data is written to the table. Remote Agent is not installed on the target machine. Remote Agent uses connection string to connect to the target. Audit data read time includes the network latency involved in accessing the audit table. This deployment can be used when the operating system of the target machine is not supported for Audit Vault Agent installation. This deployment can be used when the target machine does not have sufficient memory or CPU resources for the Audit Vault Agent processes.
Table	On-premises	Local Agent Installed on the target machine	Audit data is written to the table. The local Audit Vault Agent is installed on the target machine. The local Audit Vault Agent uses connection string to connect to the target. Audit data read time has no network latency. This deployment can be used when the operating system of the target machine is supported for Audit Vault Agent installation. This deployment can be used when the target machine has sufficient memory and CPU resources for the Audit Vault Agent processes.
Table	OCI (Oracle Cloud Infrastructure)	Remote Agent Not installed on the target machine	Audit data is written to the table. Remote Agent is not installed on the target machine. Remote Agent uses connection string to connect to the target. If the target is on-premises, then the remote Agent must also be installed on-premises. If the target is on OCI, then the remote Agent must also be installed on OCI. Audit data read time includes the network latency involved in accessing the audit table. OCI virtual firewall for VCN must be configured to allow ingress traffic on ports 1522 and 7447 for Audit Vault Server. This deployment can be used when the operating system of the target machine is not supported for Audit Vault Agent installation. This deployment can be used when the target machine does not have sufficient memory or CPU resources for the Audit Vault Agent processes.
Table	OCI (Oracle Cloud Infrastructure)	Local Agent Installed on the target machine	Audit data is written to the table. The local Audit Vault Agent is installed on the target machine. The local Audit Vault Agent uses connection string to connect to the target. Audit data read time has no network latency. OCI virtual firewall for VCN must be configured to allow ingress traffic on ports 1521 and 1522 for Audit Vault Server. This deployment can be used when the operating system of the target machine is supported for Audit Vault Agent installation. This deployment can be used when the target machine has sufficient memory and CPU resources for the Audit Vault Agent processes.

Related Topics

• Behavior Changes, Deprecated, and Desupported Platforms and Features

• Registering Hosts on the Audit Vault Server

• Discovering and Registering Targets and Creating Groups

• Configuring and Managing Audit Trail Collection

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.

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 the Audit Vault Server.

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 Oracle Database Security Central console as an administrator.

2. Select Agents.

3. In the left navigation menu, Select Downloads.

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

4. Select 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 host machine where you’re deploying the Audit Vault Agent.

   Tip: Do not install the Audit Vault Agent as root user.

6. On a Microsoft Windows system, 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 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.

Note:

If you run into any issues, see the following topics for more information:

• Troubleshooting Oracle Database Security Central

• Known Issues

Activating and Starting the Audit Vault Agent

Learn how to activate and start 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 on the Audit Vault Server.

• Log in to the Oracle Database Security Central console as an administrator. See Using Oracle Database Security Central Console for more information.

To activate and start the agent:

1. Select Agents.

2. In the left navigation menu, select Agents.

   A list of registered hosts are displayed on the page.

3. Copy or make a note of the agent activation key for this host.

4. On the host machine, change directory as follows:

   cd Agent_Home/bin

   Agent_Home is the directory created in the step 7 above.

5. Run the following command:

   agentctl start -k

6. The system prompts as follows:

   Enter Activation Key:

7. Paste or enter the agent activation key in the following format:

   <Agent Name>:: XXXX-XXXX-XXXX-XXXX-XXXX

   The activation key is not 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.

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 Oracle Database Security Central console as an administrator. See Using Oracle Database Security Central Console for more information.

3. Select Agents.

4. In the left navigation menu, select Agents.

   A list of registered Agents is displayed on the page.

5. Select name of the Agent that you want to change.

6. In the dialog, change the Name or the IP Address field, and then select 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

Configuring Agent Auto Restart Functionality

Learn how to configure the Audit Vault Agent auto restart functionality.

Audit Vault Agent collects audit data from the target and sends it to the Audit Vault Server. The Agent must continuously run to carry out this task seamlessly. In some cases where the host machine (Agent machine) is restarted or the Agent goes down, then the Agent may stop running. It needs to be manually restarted so that it can continue to collect audit data.

The Audit Vault Agent can be configured to restart automatically. This functionality can be configured by the agent user. It periodically monitors the status of the Agent and restarts whenever required.

Run the following commands in the Agent_Home/bin directory to enable or disable the Agent auto restart functionality:

Task	Command
To enable Agent auto restart functionality and to start the Agent	agentctl startsvc
To enable Agent auto restart functionality, if the Agent is not activated	agentctl startsvc -k
To disable Agent auto restart functionality and to stop the Agent	agentctl stopsvc
To enable Agent auto restart functionality when the Agent is already in RUNNING status	agentctl registersvc
To disable Agent auto restart functionality without stopping the Agent	agentctl unregistersvc

Note:

• Use the commands wisely as it involves two tasks (enabling or disabling the Agent auto restart functionality and starting or stopping the Agent). In case the Agent is manually stopped and the auto start service is still in effect, then the Agent is automatically started again. If the Audit Vault Agent service is started, do not stop the Agent alone without stopping the service.

• The Agent auto restart functionality must be enabled again, after updating the Java version on the Audit Vault Agent.

• The Agent auto restart functionality may not work, if the Audit Vault Agent is not properly installed or if it is not registered in the Oracle Database Security Central console.

• In case the Audit Vault Agent is being managed by another application such as cluster manager, then do not use the Agent auto restart functionality.

Configuring Agent Auto Restart Functionality Remotely

Learn how to configure Agent auto restart functionality remotely.

Agent auto restart functionality can be configured remotely. The administrator can enable this functionality through Audit Vault Server for multiple Audit Vault Agents at a time.

Note: This functionality is applicable for Audit Vault Agents deployed on Linux/Unix/AIX/Solaris platforms only. It is not applicable for Audit Vault Agents deployed on Windows platform.

Prerequisite

The Audit Vault Agent must be in RUNNING state.

Follow these steps to enable or disable this functionality:

1. Log in to the AVCLI as an administrator.

2. Run the following commands:

   Task	Command
   To configure the Agent auto restart service remotely.	ALTER HOST SET AUTO_RESTART=Y
   To disable the Agent auto restart service configuration remotely.	ALTER HOST SET AUTO_RESTART=N

   See Also: Viewing the Status and Details of Audit Vault Agent

Check if Audit Vault Agent Has Auto Restart Functionality Enabled

Learn how to check if the Audit Vault Agent is configured for auto restart functionality.

Follow these steps:

1. Log in to the Oracle Database Security Central console as an administrator.

2. Select Agents tab.

3. The Agents sub tab in the left navigation menu is selected by default. A list of registered Audit Vault Agents is displayed on the page.

4. In the list of registered Agents, identify the specific Agent.

5. Check the Agent Details column. The Agent Auto Restart Status field confirms if the Audit Vault Agent has auto restart functionality enabled.

   Note:

   Alternately, the auto restart status can be checked by running the following command from <agent_home>/bin directory:

   agentctl svcstatus

Registering and Unregistering the Audit Vault Agent as a Windows Service

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

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

Registering the Audit Vault Agent as a Windows Service

You can register 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 2017 package from Microsoft on the Windows target machine. Ensure vcruntime140.dll file is available in C:\Windows\System32 directory.

• If the vcruntime140.dll file is not present, then add it to the <Agent Home>/bin and <Agent Home>/bin/mswin-x86-64 directories.

Registering 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 dialog box.

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

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