Installing HVR Hub on Linux

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

For installing the HVR Agent on Linux, see Installing HVR Agent 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 Hub System on Linux:

Sufficient disk space
Ensure sufficient disk space is available on the machine where this installation will be performed. For more information, see Hub Disk Requirements.
Compatibility
Check whether the HVR 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 Hub System installation file for Linux (e.g. fivetran-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz). This file can be downloaded from the Downloads tab in the Fivetran dashboard. For more information, see Downloading HVR.
Database for HVR repository
HVR uses its repository database to store the replication definitions (which tables must be replicated between which 'locations') as well as run-time status (which jobs are currently running). For databases supported as a repository, see section Repository Database.
Access to source and target locations
For the HVR Hub System to access a source or target database directly, the database connectivity (e.g. ODBC drivers) must be installed on the hub machine. For more information, see Source and Target Requirements.
- If HVR Hub System must perform log-based capture from an Oracle source database, then the operating system user that HVR Hub System 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.
Perl module IO::Socket::SSL version 2.007.
This module is required for sending hvralert notification email using the STARTTLS option.
System root permission
This permission is typically needed to configure autostart of the HVR Hub Server process after rebooting the operating system. The same permission may be needed to schedule hvralertmanager inside crontab.

It is recommended to create a non-root account for installing and operating the HVR Hub System. 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 Hub System:

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 Hub System 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 starting the HVR Hub System for the first time or after an upgrade.
Uncompress the installation file (e.g. fivetran-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz) into the hvr_home directory.
```
cd $HVR_HOME
```
```
tar xzf /tmp/fivetran-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz
```
Configure the TCP listening port, on which the HVR Hub Server will listen for connection request.
The secure HTTP protocol (HTTPS) is preferred, but this requires a private-key and public-certificate. This pair of files must have been generated for the hub machine's DNS host name, and signed by a certificate trusted by web browsers.
- If private-key and public-certificate files are available (e.g. mycert.priv_key and mycert.pub_cert) use them to configure HTTPS:
  1. Create the following directories - hvr_config, etc, cert.
```
mkdir -m 744 $HVR_CONFIG
```
```
mkdir -m 744 $HVR_CONFIG/etc
```
```
mkdir -m 700 $HVR_CONFIG/etc/cert
```
  2. Copy the private-key and public-certificate files into the cert directory, and rename them as hvrhubserver.priv_key, hvrhubserver.pub_cert respectively.
```
cp mycert.priv_key $HVR_CONFIG/etc/cert/hvrhubserver.priv_key
```
```
cp mycert.pub_cert $HVR_CONFIG/etc/cert/hvrhubserver.pub_cert
```
  3. Set the HTTPS and HTTP ports by using the command hvrhubserverconfig.
```
hvrhubserverconfig HTTPS_Port=4341 HTTP_Port=4340
```
    Port 4341 and 4340 is recommended for HVR's use of HTTPS and HTTP protocol respectively.
    If HTTPS is configured, then connections to the (unencrypted) HTTP port are simply redirected to the HTTPS port.
  4. If the private-key is encrypted, optionally, you can set password for the private-key.
```
hvrhubserverconfig HTTPS_Private_Key_Password=@prompt
```
    Supply a password when prompted.
- If HTTPS private-key and public-certificate files are not available, configure HTTP instead:
  - Set the HTTP port by using the command hvrhubserverconfig.
```
hvrhubserverconfig HTTP_Port=4340
```
    Port 4340 is recommended for HVR's use of HTTP protocol.
    Browser may give warnings that HTTP is insecure. These warnings must be ignored (until HTTPS is configured).
Set up the HVR Hub System, which requires connecting it to its repository database and initializing that database's repository tables. This can be done from a web browser (UI) or from the command-line (CLI).
- Setting up system from browser.
  1. Start the HVR Hub Server by using the command hvrhubserver:
```
hvrhubserver
```
    It should show output similar to this:
```
2020-09-10T12:24:21+02:00: hvrhubserver: Fivetran 6.1.0/0 (linux_glibc2.17-x64-64bit)
2020-09-10T12:24:21+02:00: hvrhubserver: Listening on http://mynode:4340/
2020-09-10T12:24:21+02:00: hvrhubserver: No Repository_Class property configured. 
2020-09-10T12:24:21+02:00: hvrhubserver: Setup mode enabled. To set up, browse to the URL mentioned above.
```
  2. In the web browser, connect to the URL shown (e.g. http://mynode:4340/) in the command hvrhubserver output above. The HVR Hub System will be running in a 'setup mode'. Once the system setup steps are completed, the HVR Hub System will automatically exit the 'setup mode'. For more information about setting up the HVR Hub System from browser, see Setting up HVR Hub from Browser.
- Setting up system from command-line (advanced usage). For more information about setting up the HVR Hub System from CLI, see Setting up HVR Hub from CLI.
Configure alerts. HVR can send alert notifications if a problem affects replication. Alerts can also be configured to be sent if the replication latency (the delay between capturing a change and delivering that change to the target) exceeds an SLA (Service Level Agreement).
Alerts are sent by a separate process called hvralertmanager, which should be scheduled to run at a fixed frequency (e.g. every 10 minutes)
1. To check alerts every 10 minutes, add the following line to the crontab for user root (these should be single line without wrapping):
```
0,10,20,30,40,50 * * * * su hvr -c /home/fivetran/hvr_home/bin/hvr -EHVR_HOME=/home/fivetran/hvr_home -EHVR_CONFIG=/home/fivetran/hvr_config hvralertmanager
```
  Alternatively, the crontab can be run directly as the HVR user. Typically, the HVR user does not have this permission, unless it is named in file /etc/cron.allow, or file /etc/cron.deny exists. In that case the following line should be added to crontab for HVR user (e.g. fivetran):
```
0,10,20,30,40,50 * * * * /home/fivetran/hvr_home/bin/hvr -EHVR_HOME=/home/fivetran/hvr_home -EHVR_CONFIG=/home/fivetran/hvr_config hvralertmanager
```
  Output/error redirection to cronout.log is optional.
2. To verify that hvralertmanager is running correctly, check 10 minutes later that lines are being written to file alertmanager.out available in HVR_CONFIG/logs directory.

Configuring Restarting of Hub Server after System Reboot

After setting up the HVR Hub System, it is normally necessary to ensure that the HVR Hub Server service is restarted after the hub machine gets rebooted. Note that a reboot is not necessary now; rather setting this up should be done because eventually a reboot is inevitable.

The necessary steps depend on the service management system used by the operating system:

Some Linux distributions use systemd
Other Linux systems use the older 'Unix init daemon' system

Linux systemd

The following steps should be performed as user root:

Create a systemd unit file hvrhubserver.service in /etc/systemd/system directory. This unit file should contain the following:

[Unit]
Description=HVR Hub Server

[Service]
# The process start-up type 'forking' allows this service to spawn new processes
Type=forking
Environment="HVR_HOME=/home/fivetran/hvr_home"
Environment="HVR_CONFIG=/home/fivetran/hvr_config"
Environment="HVR_TMP=/home/fivetran/hvr_tmp"

# This should be user that owns HVR_HOME, HVR_CONFIG etc..
User=fivetran
ExecStart=/home/fivetran/hvr_home/bin/hvrhubserver

# Restart this service after a crash
Restart=always

# The number of seconds to wait before attempting a restart 
RestartSec=5s

[Install]
WantedBy=multi-user.target

User must be set to the user under which HVR Hub System is installed/running.

Enable and start the service:

systemctl enable hvrhubserver

systemctl start hvrhubserver

Verify whether the service is active:

systemctl status hvrhubserver

It should show output similar to this:

hvrhubserver.service - Fivetran HubServer
Loaded: loaded (/etc/systemd/system/hvrhubserver.service; disabled; vendor preset: disabled)
Active: active (running) since Mon 2020-09-12 10:03:18 EST; 14min ago
Process: 7587 ExecStart=/home/fivetran/hvr_home/bin/hvrhubserver
Main PID: 7588 (hvrhubserver)

For the steps to configure connection via proxy server, see section Configuring Connection via Proxy Server on Linux.