Installing HVR Agent on Linux

This section describes the requirements, step-by-step instructions on how to install the HVR Agent on Linux and the initial system configuration.

For installing the HVR Hub System on Linux, see Installing HVR Hub on Linux.

For installing the HVR Agent on Unix (Solaris, AIX), see Installing HVR Agent on Unix.

Requirements

Following are the prerequisites for installing the HVR Agent on Linux:

Sufficient disk space Ensure sufficient disk space is available on the machine where this installation will be performed. For more information, see Agent Disk Requirements.
Compatibility Check whether the HVR Agent version is compatible with the operating system and DBMS. Refer to the relevant Supported Platforms section or read the COMPATIBILITY section in the release notes (available under the Downloads tab in the Fivetran dashboard).
Installation file HVR Agent installation file for Linux (e.g. fivetran-6.1.0_21-agent_only-linux_glibc2.27-ppc64-64bit_ga_patch.tar.gz). This file can be downloaded from the Downloads tab in the Fivetran dashboard. For more information, see Downloading HVR.
Access to source and target locations For the HVR Agent to access a source or target database directly, the database connectivity (e.g. ODBC drivers) must be installed on the agent machine. For more information, see Source and Target Requirements.
- If HVR Agent must perform log-based capture from an Oracle source database, then the operating system user that HVR Agent uses must be able to read the redo files and archive files that Oracle generates. It can be done by adding the operating system user to the oinstall or dba group in /etc/group. The permission to read these files can also be given by creating special Access Control Lists (ACLs). For more information, see Oracle Requirements.
System root permission This permission is typically needed to configure autostart of the HVR Agent process using systemd or xinetd to listen on a TCP/IP port. Alternatively, you can manually start the HVR Agent as daemon process using hvragentlistener, which does not require root permission.

It is recommended to create a non-root account for installing and operating the HVR Agent. We suggest creating a separate user account (e.g, fivetran) for this purpose.

Install Steps

Perform the following steps as the user that will be used for operating the HVR Agent:

The commands to set the environment variables depend on the shell you use to interface with the operating system. This procedure lists examples that can be used in Bourne Shell (sh) and KornShell (ksh).

Configure the environment variables HVR_HOME, HVR_CONFIG, and HVR_TMP for your operating system. Each of these environment variables should be pointed to the HVR Agent installation directories - hvr_home, hvr_config, and hvr_tmp.
```
export HVR_HOME=/home/fivetran/hvr_home
```
```
export HVR_CONFIG=/home/fivetran/hvr_config
```
```
export HVR_TMP=/home/fivetran/hvr_tmp
```
Also, add the executable directory path to the environment variable PATH.
```
export PATH=$PATH:$HVR_HOME/bin
```

Add the environment variables and the executable directory path into the startup file (e.g. .profile).

export HVR_HOME=/home/fivetran/hvr_home
export HVR_CONFIG=/home/fivetran/hvr_config
export HVR_TMP=/home/fivetran/hvr_tmp
export PATH=$PATH:$HVR_HOME/bin

Create the installation directory - hvr_home:
```
umask 022
```
```
mkdir $HVR_HOME
```
- umask 022 is used so that the files and directories created in the following commands are readable by everyone (other Linux users and groups), but only writable by the owner.
- other directories (hvr_config and hvr_tmp) will be automatically created as needed.
- hvr_home is regarded a read-only directory. The user files saved in this directory will be moved to a backup directory when executing the HVR Agent for the first time or after an upgrade.
Uncompress the installation file (e.g. fivetran-6.1.0_21-agent_only-linux_glibc2.27-ppc64-64bit_ga_patch.tar.gz) into the hvr_home directory:
```
cd $HVR_HOME
```
```
tar xzf /tmp/fivetran-6.1.0_21-agent_only-linux_glibc2.27-ppc64-64bit_ga_patch.tar.gz
```
Configure the system for HVR Agent. After the agent install steps are completed, it is necessary to configure the HVR Agent process.
There are different ways for configuring the HVR Agent to listen on a TCP/IP port:
- Linux systemd
  Standard on some Linux distributions. Requires root privilege.
  Systemd configuration steps
  The following steps should be performed as user root to configure systemd:
  1. Create the systemd unit files hvr.socket and hvr@.service in /etc/systemd/system directory.
    1. hvr.socket should contain the following:
      [Unit] Description=HVR service socket [Socket] ListenStream=4343 Accept=true TriggerLimitIntervalSec=1s TriggerLimitBurst=10000 MaxConnectionsPerSource=100 MaxConnections=500 KeepAlive=true [Install] WantedBy=sockets.target
      TriggerLimitIntervalSec is supported since systemd version 230.
      TriggerLimitBurst is supported since systemd version 230.
      MaxConnectionsPerSource is supported since systemd version 232.
      In a IPv4/IPv6 mixed system, if you want to force systemd to use IPv4, set ListenStream=0.0.0.0:4343.
    2. hvr@.service should contain the following:
      [Unit] Description=HVR service [Service] Environment="HVR_HOME=/home/fivetran/hvr_home" Environment="HVR_CONFIG=/home/fivetran/hvr_config" Environment="HVR_TMP=/home/fivetran/hvr_tmp" User=fivetran ExecStart=/home/fivetran/hvr_home/bin/hvragent StandardInput=socket KillMode=process TimeoutStartSec=infinity [Install] WantedBy=multi-user.target
      User must be set to the user under which the HVR Agent is installed/running.
  2. To enable and start the service, execute the following commands:
    systemctl enable hvr.socket
    systemctl start hvr.socket
    1. To verify whether the service is active, execute the following command:
      systemctl status hvr.socket
      Sample output:
      hvr.socket - HVR service socket Loaded: loaded (/etc/systemd/system/hvr.socket; enabled; vendor preset: enabled) Active: active (listening) since Mon 2020-09-07 17:54:44 CEST; 5s ago Listen: [::]:4343 (Stream) Accepted: 0; Connected: 0
- Linux xinetd
  Used on other Linux distributions. Requires root privilege.
  Xinetd configuration steps
  The following steps should be performed as user root to configure xinetd:
  1. Create an xinetd service file hvr in /etc/xinetd.d/ directory. This service file should contain the following:
    service hvr { socket_type = stream wait = no user = fivetran server = /home/fivetran/hvr_home/bin/hvragent env += HVR_HOME=/home/fivetran/hvr_home env += HVR_CONFIG=/home/fivetran/hvr_config env += HVR_TMP=/home/fivetran/hvr_tmp disable = no cps = 10000 30 per_source = 100 instances = 500 }
    user must be set to the user under which HVR Agent is installed/running.
  2. Added the following to /etc/services - the name of the xinetd service for HVR Agent (created in the previous step) and the TCP/IP port number for HVR Agent Listener.
    hvr 4343/tcp #Port for HVR Agent
  3. Reload or restart the xinetd service to apply the changes. For information about restarting the xinetd service, refer to the operating system documentation.
- HVR Agent Listener
  Our own daemon hvragentlistener. Does not require root privilege.
  Start HVR Agent Listener as daemon process
  The command hvragentlistener should be executed with option -d to start the HVR Agent Listener service as a daemon process on the required port:
```
hvragentlistener -d 4343
```
To test the connection to the HVR Agent, execute the command hvragenttest on the machine from which you are connecting to the agent. You can also check whether hvragentlistener is running by executing the command hvragenttest directly on the HVR Agent machine.
Examples for testing the connection to a HVR Agent
Example 1: Check connection to a HVR Agent
You can check the connection to the HVR Agent installed/running on a remote machine with username and password authentication enabled. Execute the following command on the hub machine or on the machine from which you are connecting to the HVR Agent:
```
hvragenttest -L myuser/mypassword mynode 4343
```
Sample output in Linux with successful authentication and also indicating that the HVR Agent Listener is running:
```
hvragenttest: Fivetran 6.1.0/21 (linux_glibc2.17-x64-64bit)
hvragenttest: Agent version 6.1.0/21.
hvragenttest: Authentication with username and password enabled.
hvragenttest: Authentication successful.
hvragenttest: Finished. (elapsed=0.34s)
```
Example 2: Check whether hvragentlistener is running
After installing and starting the HVR Agent Listener service, you can verify whether the hvragentlistener is running on the agent machine. Execute the following command on the agent machine:
```
hvragenttest mynode 4343
```
Sample output in Windows with successful authentication indicating that the HVR Agent Listener is running:
```
hvragenttest: Fivetran 6.1.0/21 (windows-x64-64bit)
hvragenttest: Agent version 6.1.0/21.
hvragenttest: Authentication with username and password enabled.
hvragenttest: Authentication successful.
hvragenttest: Finished. (elapsed=0.18s)
```
Configure the HVR Agent, which requires setting its network security and authentication properties. This can be done from a web browser (UI) while creating a location (provided the agent is in 'setup mode') or from the command-line (CLI).
- For configuring the HVR Agent from browser, see Configuring HVR Agent from Browser.
- For configuring the HVR Agent from CLI, see Configuring HVR Agent from CLI.
By default, after starting the HVR Agent for the first time, it will be available in 'setup mode' for the next 60 minutes. In 'setup mode', you can configure the HVR Agent remotely from the hub machine using browser or CLI. When the 'setup mode' expires after 60 minutes, the agent can not be configured remotely. If you want to re-initiate the HVR Agent 'setup mode' later, use the command hvragentconfig directly on the agent machine. For example, to enable 'setup mode' for the next 1 hour, execute:
hvragentconfig Setup_Mode_Timed_Until=now+1h

Installing HVR Agent on Linux

Requirements

Install Steps

Example 1: Check connection to a HVR Agent

Example 2: Check whether hvragentlistener is running