Installing HVR Agent on Unix

This section describes the requirements, step-by-step instructions on how to install the HVR Agent on Unix (Solaris, AIX) and the initial system configuration.

For installing the HVR Agent on Linux, see Installing HVR Agent on Linux.

Requirements

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

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 Unix (e.g. fivetran-6.1.0_21-agent_only-solaris_10-sparcv9-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 inetd or SMF 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 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 Unix 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-solaris_10-sparcv9-64bit_ga_patch.tar.gz) into the hvr_home directory:
```
cd $HVR_HOME
```
```
gzip -dc /tmp/fivetran-6.1.0_21-agent_only-solaris_10-sparcv9-64bit_ga_patch.tar.gz | tar xf -
```
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:
- Unix inetd
  Standard on older Unix distributions. Requires root privilege.
  inetd configuration steps
  The following steps should be performed as user root to configure the inetd service:
  1. In the /etc/services file, add the following line specifying the name (e.g. myhvr) and the TCP/IP port number of the HVR Agent:
    myhvr 4343/tcp #Port for HVR Agent Listener
  2. Add the following line to /etc/inetd.conf file:
    myhvr stream tcp nowait fivetran /home/fivetran/hvr_home/bin/hvragent hvragent -EHVR_HOME=/home/fivetran/hvr_home -EHVR_CONFIG=/home/fivetran/hvr_config -EHVR_TMP=/home/fivetran/hvr_tmp
    The user must be set to the user (e.g. fivetran) under which the HVR Agent is installed/running.
    The service name (e.g. myhvr) specified in this inetd.conf file must match with the name specified (step #1) in the /etc/services file.
    The above configuration should be defined in a single line (without manual line break).
    Option -E defines the environment variables.
  3. Reload or restart the inetd service to apply the changes. For information about restarting the inetd service, refer to the operating system documentation.
- Solaris Service Management Facility (SMF)
  Used on Solaris (versions 10 and higher) distributions. Requires root privilege.
  SMF configuration steps
  In Solaris 10 and higher, the /etc/inetd.conf file has been replaced by SMF manifests. All inetd services are now configured/controlled under the SMF. The following steps should be performed as user root to configure the SMF service:
  1. In the /etc/services file, add the following line specifying the name (e.g. myhvr) and the TCP/IP port number of the HVR Agent:
    myhvr 4343/tcp #Port for HVR Agent Listener
  2. Create a temporary file (e.g. /tmp/inet.hvr) containing the following inetd.conf-style entry for HVR Agent:
    myhvr stream tcp nowait fivetran /home/fivetran/hvr_home/bin/hvragent hvragent -EHVR_HOME=/home/fivetran/hvr_home -EHVR_CONFIG=/home/fivetran/hvr_config -EHVR_TMP=/home/fivetran/hvr_tmp
    The user must be set to the user (e.g. fivetran) under which HVR Agent is installed/running.
    The service name (e.g. myhvr) specified in this temporary file must match with the name specified (step #1) in the /etc/services file.
    The above configuration should be defined in a single line (without manual line break).
    Option -E defines the environment variables.
  3. Import the temporary file (e.g. /tmp/inet.hvr) into System Management Facility (SMF) using the command inetconv.
    For example:
    inetconv -i /tmp/inet.hvr
  4. Enable the service using the command inetadm.
    For example:
    inetadm -e svc:/network/hvr/tcp:default
  5. Refresh the service using the command svcadm:
    svcadm refresh inetd
- 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 is normally done from a browser while creating a location (provided the agent is in 'setup mode'). Alternatively, you can also perform this agent configuration from the command-line.
- 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 Unix

Requirements

Install Steps

Example 1: Check connection to a HVR Agent

Example 2: Check whether hvragentlistener is running