Proxy Agent

• Using Telnet:

   telnet orchestrator.fivetran.com 443
  

• Using Netcat:

   nc orchestrator.fivetran.com 443 -v
  

Replace <proxy server hostname> with the hostname for the appropriate region:

• Using Telnet:

   telnet primary. 443
  

• Using Netcat:

   nc primary. 443 -v
  

When installing the Proxy Agent as a service, the user who installs the Proxy Agent must have permission to manage Windows services. We recommend that you install the Proxy Agent as an Administrator user.

1. Run the downloaded .exe file (e.g. fivetran-6.1.0_23-hub_and_agent-windows-x64-64bit_ga_patch-setup.exe).

2. In the installation wizard dialog, click Next.

3. Read the License Agreement, select I accept the agreement and click Next.

4. Specify the installation directories and click Next.

   If this is a first-time installation, the High-Volume Agent (HVA) and Proxy Agent can be installed in the same directory. Otherwise, you can either install the Proxy Agent in a different directory than the HVA or manually install the Proxy Agent using a ZIP file.

   

5. Specify the name for the program folder and click Next.

   

6. Select the role of the installation:

   • Proxy Agent to install only the Proxy Agent or
   • High-Volume Agent (HVA) and Proxy Agent to install both the Proxy Agent and HVA.

7. If you selected High-Volume Agent (HVA) and Proxy Agent in the previous step, enter value for the High-Volume Agent Listener Port and click Next.

   

8. Paste the Proxy Agent settings from the configuration file (config.json) you've generated and click Next.

   The configuration file contains the settings, credentials, and certificates required to establish secure communication between the Proxy Agent and Fivetran.

   

9. Select the user account for running the Proxy Agent service.

• If Specified user is selected, enter values for User, Password, Confirm Password and click Next.

  

• If Local System account is selected, click Next.

  

10. Select Add HVR_HOME, HVR_CONFIG, and HVR_TMP (if required) and click Next. If you are only installing the Proxy Agent, we recommend that you skip this step.

    This is to set the environment variables HVR_HOME, HVR_CONFIG, and HVR_TMP in your operating system. These variables point to the corresponding installation directories you've created above.

    

11. Click Next to initiate the installation.

    If you selected High-Volume Agent (HVA) and Proxy Agent in step 6, this will install both the Proxy Agent and High-Volume Agent under the same installation directory.

    

12. Click Finish to start the Proxy Agent. Once installed, the Proxy Agent service appears running in Windows Services.

    If you selected High-Volume Agent (HVA) and Proxy Agent in step 6, this will start both the Proxy Agent and High-Volume Agent services.

    

Perform the following steps in the user account that will be used for operating the Proxy Agent:

1. Configure the environment variables HVR_HOME, HVR_CONFIG, and HVR_TMP for your operating system using command setx or set. Each of these environment variables should be pointed to the installation directories - hvr_home, hvr_config, and hvr_tmp:

   Environment variables set using setx command are available in the future command windows only and the environment variables set using set command are available in the current command window only.

   setx HVR_HOME C:\fivetran\hvr_home
   setx HVR_CONFIG C:\fivetran\hvr_config
   setx HVR_TMP C:\fivetran\hvr_tmp
   

   set HVR_HOME=C:\fivetran\hvr_home
   set HVR_CONFIG=C:\fivetran\hvr_config
   set HVR_TMP=C:\fivetran\hvr_tmp
   

   Also, add the executable directory path (e.g C:\fivetran\hvr_home\bin) to the environment variable PATH.

   setx PATH "%PATH%C:\fivetran\hvr_home\bin"
   

   set PATH=%PATH%;C:\fivetran\hvr_home\bin
   

   Alternatively, environment variables can be configured using Windows GUI.

   1. Navigate to Control Panel ▶ System and Security ▶ System ▶ Advanced system settings

      Alternatively, use the command sysdm.cpl to open System Properties.

   2. In the Advanced tab, click Environment Variables...

   3. In section System variables or User Variables for user_name, click New.

      1. Enter Variable name (e.g, HVR_HOME) and Variable value (e.g, C:\fivetran\hvr_home).
         
      2. Click OK.
      3. Repeated the above steps for each environment variable.

   4. Add the executable directory path to the environment variable Path.

      1. In section System variables or User Variables for user_name, from the list of variables, select Path and click Edit....
      2. Click New and enter the path for the Proxy Agent executable.
         
      3. Click OK.

2. Create the installation directory - hvr_home (e.g. C:\fivetran\hvr_home):

   md %HVR_HOME%
   

   • Other directories (hvr_config and hvr_tmp) will be created automatically as needed.
   • hvr_home is regarded a read-only directory.

3. Uncompress (unzip) the installation file (e.g. fivetran-6.1.0_23-hub_and_agent-windows-x64-64bit_ga_patch.zip) into the hvr_home directory:

   cd %HVR_HOME%
   C:\fivetran\hvr_home>tar -xf C:\Users\Admin\Downloads\fivetran-6.1.0_23-hub_and_agent-windows-x64-64bit_ga_patch.zip
   

   Alternatively, files can be uncompressed using the 'Extract All' option in Windows GUI.

   

4. Paste the Proxy Agent settings from the configuration file (config.json) you've generated to the proxyagent.conf file located in the HVR_CONFIG/proxy directory. The configuration file contains the settings, credentials, and certificates required to establish secure communication between the Proxy Agent and Fivetran.

   If the proxyagent.conf file is missing, create the file manually.

5. Run the following command to validate the Proxy Agent settings:

   %HVR_HOME%/jre/bin/java -jar %HVR_HOME%/proxy/proxyagent.jar -v %HVR_CONFIG%/proxy/proxyagent.conf
   

6. Create a .bat file (e.g. install_and_run_proxy_service.bat) with the following contents.

    FOR /F "delims=" %%i IN ('CALL "%HVR_HOME%/bin/hvr" hvrhubserversvc -s') DO SET HvrHubServerSvcOutput=%%i
    REM We use a normalized HVR_CONFIG path hash to guarantee a unique service name
    SET HubConfigHash=%HvrHubServerSvcOutput:~13,8%
   
    REM In the CLI below use "DomainName\UserName" for --ServiceUser and specify --ServicePassword parameter if needed
    REM Adjust the other parameters as necessary
    REM Ensure to have unique service name (in //IS//) and display name 
    %HVR_HOME%/proxy/prunsrv.exe //IS//FivetranProxy_%HubConfigHash% ^
       --StartParams "%HVR_CONFIG%/proxy/proxyagent.conf" ^
       --ServiceUser "LocalSystem" ^
       --DisplayName "Fivetran Proxy Agent [%HubConfigHash%]" ^
       --Description "Fivetran Proxy Agent installed into %HVR_HOME%\proxy" ^
       --Jvm "%HVR_HOME%/jre/bin/server/jvm.dll" ^
       --JavaHome "%HVR_HOME%/jre" ^
       --Classpath "%HVR_HOME%/proxy/proxyagent.jar" ^
       --StartPath "%HVR_HOME%/proxy/" ^
       --Startup=auto ^
       --StartMode=jvm ^
       --StartClass=com.fivetran.proxy.agent.ProxyAgent ^
       --StartMethod=main ^
       --StopMode=jvm ^
       --StopClass=com.fivetran.proxy.agent.ProxyAgent ^
       --StopMethod=stop ^
       --JvmOptions "-XX:+HeapDumpOnOutOfMemoryError" ^
       --StdOutput "%HVR_CONFIG%/proxy/logs/agent-out.log" ^
       ++Environment "HVR_CONFIG=%HVR_CONFIG%" ^
       ++Environment "HVR_HOME=%HVR_HOME%" ^
       ++Environment "HVR_TMP=%HVR_TMP%"
   
     %HVR_HOME%/proxy/prunsrv.exe //ES//FivetranProxy_%HubConfigHash%
   

7. Run the .bat file to configure and start the Proxy Agent:

   install_and_run_proxy_service.bat
   

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

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

   PATH=$PATH:$HVR_HOME/bin
   

2. Add the environment 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
   

3. Create the installation directory - hvr_home using the following commands:

   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 created automatically as needed. The HVR_HOME directory is regarded as read-only.

4. Uncompress the installation file (e.g. fivetran-6.1.0_23-hub_and_agent-linux_glibc2.17-x64-64bit_ga.tar.gz) into the HVR_HOME directory:

   cd $HVR_HOME
   

   tar xzf /tmp/hvr-6.1.0_23-hub_and_agent-linux_glibc2.17-x64-64bit_ga.tar.gz
   

   Once installed, the jre and proxy folders are created in your HVR_HOME directory.

5. Create a new directory for the proxyagent.conf file in hvr_config (/home/fivetran/hvr_config/proxy).Paste the Proxy Agent settings from the configuration file (config.json) you've generated to the proxyagent.conf file located in the newly created directory. The configuration file contains the settings, credentials, and certificates required to establish secure communication between the Proxy Agent and Fivetran.

6. Run the following command to verify if the Linux machine is ready for the setup. The output of the command should be systemd.

   ps -p 1 -o comm=
   

7. Update the fivetran_proxy.service file in the /etc/systemd/system directory with the correct path to java.jar, proxyagent.jar, and proxyagent.conf files.

   If missing, create the fivetran_proxy.service file manually. The contents of the file should be as follows:

   [Unit]
   Description=Fivetran Proxy Agent #
   
   [Service]
   
   Type=simple
   Environment="HVR_HOME=/home/fivetran/hvr_home"
   Environment="HVR_CONFIG=/home/fivetran/hvr_config"
   Environment="HVR_TMP=/home/fivetran/hvr_tmp"
   
   ExecStart=${HVR_HOME}/jre/bin/java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=${HVR_CONFIG}/proxy/ -jar ${HVR_HOME}/proxy/proxyagent.jar ${HVR_CONFIG}/proxy/proxyagent.conf
   
   # Restart this service to after a crash
   Restart=always
   
   # The number of seconds to wait before attempting a restart
   RestartSec=5s
   
   [Install]
   WantedBy=multi-user.target
   

8. Execute the following commands as the root user to start the Proxy Agent service.

   a. Enable the service:

   systemctl enable fivetran_proxy.service
   

   b. Start the service:

   systemctl start fivetran_proxy.service
   

   c. Verify the status of the service:

   systemctl status fivetran_proxy.service
   

If your Proxy Agent is installed on a Windows system, you can set up a recovery configuration for the agent by performing the following steps:

1. Go to Control Panel > Administrative Tools > Computer Management > Services and Applications > Services or use the services.msc command to open the Services console.

2. In the Services console, locate the Fivetran Proxy Agent service. Ensure the service description matches the installation directory.

3. Right-click the service and select Properties.

4. Go to the Recovery tab.

5. Set your preferred recovery options for the failure scenario.

   

1. Download the latest High-Volume Agent Installer from the downloads page.

2. Run the Installer

The Proxy Agent installed using a ZIP file or on Linux requires manual upgrade steps. Follow these steps:

1. Download the latest High-Volume Agent for the desired operating system from the downloads page.

2. Uninstall the existing proxy agent using the Uninstall Proxy Agent instructions.

3. Follow the instructions for installing the Proxy Agent using the appropriate section of the installation instructions.

The steps to uninstall the Proxy Agent depend on whether you used an EXE file (Installer) or a ZIP file to install it.

Uninstall Proxy Agent that was installed using an EXE file

1. Navigate to the uninstall folder in the Proxy Agent installation directory %HVR_HOME% (for example, C:\fivetran\hvr_home\uninstall).

2. Double-click the uninstall.exe file to initiate the uninstallation process.

Uninstall Proxy Agent that was installed using a ZIP file

1. Create a .bat file (for example, delete_proxy_agent_service.bat) with the following contents:

      FOR /F "delims=" %%i IN ('CALL "%HVR_HOME%/bin/hvr" hvrhubserversvc -s') DO SET HvrHubServerSvcOutput=%%i
      REM We use a normalized HVR_CONFIG path hash to guarantee a unique service name
      SET HubConfigHash=%HvrHubServerSvcOutput:~13,8%
   
      %HVR_HOME%/proxy/prunsrv.exe //DS//FivetranProxy_%HubConfigHash%
   

2. Run the .bat file as an Administrator to remove all Proxy Agent service entries.

1. Stop the Proxy Agent service:

    sudo systemctl stop fivetran_proxy.service
   

2. Disable the service from auto-starting at boot:

    sudo systemctl disable fivetran_proxy.service 
   

3. Remove the service configuration file:

    sudo rm /etc/systemd/system/fivetran_proxy.service
   

4. Reload the systemd manager configuration:

    sudo systemctl daemon-reload
   

5. Clear the systemd state for any failed services:

    sudo systemctl reset-failed