Proxy Agent Binary Distribution Setup Guide

This guide covers deploying the Proxy Agent on Linux or Windows Server using the binary distribution, a standalone ZIP file that includes the Proxy Agent and a bundled Java Runtime Environment (JRE). To deploy the Proxy Agent as a container instead, see the Docker-based setup guide.

System requirements

Proxy Agent requires the following system resources:

CPU: Minimum 4 vCPUs with x86-64 processors
Memory: Minimum 5 GB of RAM
Storage: Minimum 2 GB allocated disk space for the executables and logs
Java: The Proxy Agent includes a bundled Java Runtime Environment (JRE) based on open-source Azul Zulu JDK. You do not need to install or purchase any additional Java licenses.

Configure Proxy Agent

Follow the instructions below to configure a connection through the Proxy Agent.

Certificate management options

The Proxy Agent uses a client certificate and private key to authenticate to Fivetran. You can manage these credentials using one of the following methods:

Embedded certificate method (default): Fivetran generates the client certificate and private key and embeds them directly inside the Proxy Agent configuration file (config.json). This is the simplest and recommended method for most deployments.
KeyStore method (advanced): You store the Fivetran-generated client certificate and private key in a secure PKCS12 KeyStore file. This method is available in Proxy Agent version 1.1.4 or later.
Using a KeyStore provides the following benefits:
- Encrypted, password-protected storage for the certificate and private key
- Separation of configuration (config.json) and sensitive credentials (certificate and private key)

Both methods require generating the Proxy Agent configuration file (config.json). If you plan to use the KeyStore method, you will extract the embedded certificate and private key from this file for use in your KeyStore. See Configure Proxy Agent to use KeyStore.

Generate Proxy Agent settings

Follow the instructions below to generate the Proxy Agent configuration file (config.json), which contains the settings and authentication parameters required to establish secure communication between the Proxy Agent and Fivetran. This file is also required to install the Proxy Agent.

In your Fivetran setup form, do the following:

In the Connection Method drop-down menu, select Connect via Proxy Agent.
Click + Configure a new proxy agent.
In the Agree to terms step, review the License Addendum and Software Specific Requirements.
Select the I have read and agree to the terms of the License Addendum and the Software Specific Requirements checkbox.
Click Next.
In the Choose your deployment type step, select Binary Distribution for Linux and Windows Server.
If you haven't already, download the Proxy Agent ZIP file for your platform.
Click Next.
In the Name the proxy agent step, enter a name in the Proxy agent name field.
Click Generate proxy agent config.
In the Download proxy agent configuration file section, click the config.json download link.
You can't download the file again after you click Save. Store it securely before completing this step.
The configuration file contains the settings and authentication parameters required to establish secure communication between the Proxy Agent and Fivetran.
Store the config.json file securely in an easily accessible location. The installation procedure requires its contents.
Select the I have downloaded the file checkbox.
Click Save.
Confirm that the new Proxy Agent is selected in the Proxy agents drop-down menu.

(Optional) If the Proxy Agent needs to forward traffic through an intermediate network proxy to reach Fivetran, add the proxy_host and proxy_port fields to your config.json file.

Do not include http:// or https:// in the <proxy_host> value.

Example config.json with intermediate proxy settings:

{
  "agent_id": "<your_agent_id>",
  "auth_token": "...",
  "orchestrator_host": "orchestrator.fivetran.com",
  "client_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "client_private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
  "proxy_host": "<proxy_host>",
  "proxy_port": <proxy_port>
}

Configure Proxy Agent to use KeyStore (optional)

If you are using the KeyStore method for certificate management, follow the steps in this section. Skip this step if you are using the default Embedded certificate method.

Configure the Proxy Agent to use a KeyStore

Prerequisites:

Proxy Agent version 1.1.4 or later
On Linux, the Proxy Agent service runs as root
On Windows, the Proxy Agent service runs under the LocalSystem account
OpenSSL version 1.0.1 or later installed (which is required to convert PEM files into a PKCS12 KeyStore)

Perform the following steps to prepare and configure the KeyStore:

Extract the certificate and private key from the generated config.json file into PEM files. Run the following commands in the directory where the config.json file is located:
Ensure you have jq installed on your system. If not, follow the instructions in the jq installation guide.
```
jq -r .client_cert < config.json > certificate.pem
jq -r .client_private_key < config.json > private_key.pem
```
Convert the PEM certificate and private key into a PKCS12 KeyStore file.
OpenSSL is required to convert the PEM certificate and private key into a PKCS12 KeyStore file. Ensure that OpenSSL version 1.0.1 or later is installed. Earlier versions do not support the SHA-256 algorithms required for PKCS12 keystores. If OpenSSL is not installed already, install it using either your operating system’s package manager or by downloading the source from the OpenSSL project website.
- Linux:
```
sudo openssl pkcs12 -export \
  -in certificate.pem \
  -inkey private_key.pem \
  -out keystore.p12 \
  -name orchestrator.fivetran.com \
  -passout pass:<your_secure_password>
```
- Windows:
```
openssl pkcs12 -export -in certificate.pem -inkey private_key.pem -out keystore.p12 -name orchestrator.fivetran.com -passout pass:<your_secure_password>
```
Delete the certificate.pem and private_key.pem files. The KeyStore now contains the certificate and private key, so you no longer need the PEM files, and the private_key.pem file stores the private key unencrypted.
- Linux:
```
rm certificate.pem private_key.pem
```
- Windows:
```
del certificate.pem, private_key.pem
```
Ensure the KeyStore file is readable by the account that runs the Proxy Agent service:
- On Linux, the Proxy Agent service runs as root. Creating the KeyStore file with sudo ensures that root can read the file. Restrict the file so that only root can read it. Replace <path_to_keystore> with the full path to your KeyStore file:
```
sudo chmod 600 <path_to_keystore>
```
- On Windows, the Proxy Agent service runs under the LocalSystem account.
  Grant read access to the KeyStore file for LocalSystem, and remove the permissions the file inherits from its parent directories, such as read access for all users. Replace <path_to_keystore> with the full path to your KeyStore file:
```
icacls <path_to_keystore> /inheritance:r /grant:r "NT AUTHORITY\SYSTEM":R "BUILTIN\Administrators":F /C
```
Keep the client_cert and client_private_key fields in your configuration file for now. The Proxy Agent uses them for its first start. You remove them after you configure the Proxy Agent service to load the KeyStore, as described in the KeyStore steps of the Windows and Linux installation instructions.

Network configuration and validation

Before installing the Proxy Agent, safelist the Proxy Broker hostname, and the Proxy Server hostname for every Fivetran cloud processing region your connections will use, in your firewall so that the Proxy Agent can connect to our servers. For the full list of hostnames, see Fivetran Proxy users. After configuring your firewall, do the following to verify connectivity from the machine on which the Proxy Agent will be installed.

Verify connectivity to the Proxy Broker

Using Telnet:
```
 telnet orchestrator.fivetran.com 443
```
Using Netcat:
```
 nc orchestrator.fivetran.com 443 -v
```

Verify connectivity to the Proxy Server

Replace <proxy server hostname> with a valid hostname for one of the regions your connections will use. For example, if a region's wildcard hostname is *.us-east-1.aws.proxy.prod.fivetran.com, replace the leading * with any valid string, such as primary.us-east-1.aws.proxy.prod.fivetran.com. For the full list of wildcard hostnames, see Fivetran Proxy users:

Using Telnet:
```
 telnet <proxy server hostname> 443
```
Using Netcat:
```
 nc <proxy server hostname> 443 -v
```

Repeat the test for each region your connections will use.

Verify connectivity to the database

Replace <host> and <port> with your database's hostname and port. The Proxy Agent host's IP address must be allowlisted in your database's firewall or security group before running these checks.

Using Telnet:
```
 telnet <host> <port>
```
Using Netcat:
```
 nc <host> <port> -v
```

Download Proxy Agent

The Proxy Agent binary distribution is a ZIP file for each supported platform. Each ZIP file includes the Proxy Agent application (proxyagent.jar) and a bundled Java Runtime Environment (JRE). The Windows ZIP file also includes prunsrv.exe, which registers the Proxy Agent as a Windows service.

Download the ZIP file for your platform using one of the following methods:

Fivetran dashboard: Go to the Downloads page and, in the Proxy Agent section, download the latest version for your platform.
REST API: Call the Proxy Agent downloads endpoint with your API key and secret:
```
curl -u "<api_key>:<api_secret>" https://api.fivetran.com/proxy-agent/downloads
```
The response lists the available versions for each platform, with a signed download URL for each version. The signed URL is valid for 24 hours.

The ZIP file names have the format fivetran-proxy-agent-<version>-<platform>.zip, where <platform> is win_x64 for Windows or linux_x64 for Linux (for example, fivetran-proxy-agent-1.2.9-linux_x64.zip). Replace <version> with the version you downloaded in all the commands below.

Install Proxy Agent

Follow the Proxy Agent installation instructions for your operating system.

You can install the Proxy Agent on any host in your network that has network access to your database. If a separate virtual machine isn't available, you can install the Proxy Agent directly on the database server.

Install Proxy Agent on Windows Server

Perform the following steps as an Administrator user in a Command Prompt window.

Configure the environment variable PROXY_HOME to point to the installation directory (for example, C:\fivetran\proxy-agent). Run both commands. The setx command saves the variable for future command windows, and the set command makes it available in the current command window:
```
setx PROXY_HOME C:\fivetran\proxy-agent
set PROXY_HOME=C:\fivetran\proxy-agent
```
Create the installation directory and its config and logs subdirectories:
```
md %PROXY_HOME%
md %PROXY_HOME%\config
md %PROXY_HOME%\logs
```
The config directory contains the Proxy Agent configuration file.
The logs directory contains the Proxy Agent log files and heap dumps.
Extract the ZIP file into the PROXY_HOME directory. The ZIP file contains a top-level folder, which the --strip-components=1 option removes so that the files are extracted directly into PROXY_HOME:
```
tar -xf C:\Users\Admin\Downloads\fivetran-proxy-agent-<version>-win_x64.zip --strip-components=1 -C %PROXY_HOME%
```
After extraction, the jre directory and the proxyagent.jar and prunsrv.exe files are in the PROXY_HOME directory.
Create the %PROXY_HOME%\config\proxyagent.conf file and paste the entire contents of the configuration file (config.json) you've generated into it. Then restrict access to the file so that only the LocalSystem account, which runs the Proxy Agent service, can read it and only Administrators can modify it:
```
icacls "%PROXY_HOME%\config\proxyagent.conf" /inheritance:r /grant:r "NT AUTHORITY\SYSTEM":R "BUILTIN\Administrators":F
```
The /inheritance:r option removes the permissions the file inherits from its parent directories, such as read access for all users.
The configuration file contains the settings and authentication parameters required to establish secure communication between the Proxy Agent and Fivetran, including the authentication token and private key. Don't make it readable by other users.
Run the following command to validate the Proxy Agent settings:
```
%PROXY_HOME%\jre\bin\java -jar %PROXY_HOME%\proxyagent.jar -v %PROXY_HOME%\config\proxyagent.conf
```
If the configuration file is valid, the command prints:
```
Config is valid: {"agent_id":"<your_agent_id>","auth_token":"***","orchestrator_host":"orchestrator.fivetran.com","client_cert":"-----BEGIN CERTIFICATE-----\n...","client_private_key":"***"}
```
The auth_token and client_private_key values are masked in the output. If the command returns an error such as Config has invalid contents or Config has unexpected contents, check that your proxyagent.conf file contains valid JSON and all required fields.

Create a .bat file (for example, %PROXY_HOME%\install_and_run_proxy_service.bat) with the following contents:

REM If you run multiple Proxy Agents on this machine, use a unique service name for each agent
REM (for example, FivetranProxyAgent_prod).
SET SERVICE_NAME=FivetranProxyAgent

REM Use "DomainName\UserName" for --ServiceUser and specify the --ServicePassword parameter if needed.
REM Adjust the other parameters as necessary.
%PROXY_HOME%\prunsrv.exe //IS//%SERVICE_NAME% ^
    --StartParams "%PROXY_HOME%\config\proxyagent.conf" ^
    --ServiceUser "LocalSystem" ^
    --DisplayName "Fivetran Proxy Agent" ^
    --Description "Fivetran Proxy Agent installed in %PROXY_HOME%" ^
    --Jvm "%PROXY_HOME%\jre\bin\server\jvm.dll" ^
    --JavaHome "%PROXY_HOME%\jre" ^
    --Classpath "%PROXY_HOME%\proxyagent.jar" ^
    --StartPath "%PROXY_HOME%" ^
    --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;-XX:HeapDumpPath=%PROXY_HOME%\logs" ^
    --StdOutput "%PROXY_HOME%\logs\agent-out.log" ^
    --StdError "%PROXY_HOME%\logs\agent-err.log" ^
    --Environment "PROXY_HOME=%PROXY_HOME%"

%PROXY_HOME%\prunsrv.exe //ES//%SERVICE_NAME%

Run the .bat file to install and start the Proxy Agent service:
```
%PROXY_HOME%\install_and_run_proxy_service.bat
```
Verify that the service is running:
```
sc query FivetranProxyAgent
```
The output should include STATE : 4 RUNNING. If the service isn't running, check the %PROXY_HOME%\logs\agent-out.log and %PROXY_HOME%\logs\agent-err.log files for errors.
(Optional) If you are using a KeyStore for certificate management, configure the Proxy Agent to load the KeyStore by setting the required JVM system properties.
Expand for instructions

Configure KeyStore settings for Windows installation
1. (Optional) Validate that the JRE bundled with the Proxy Agent can read the KeyStore you created. Replace <path_to_keystore> with the full path to your KeyStore file:
```
%PROXY_HOME%\jre\bin\keytool -list -keystore <path_to_keystore> -storetype PKCS12 -storepass <your_secure_password>
```
  Expected output:
```
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 1 entry

orchestrator.fivetran.com, Jan 15, 2025, PrivateKeyEntry,
Certificate fingerprint (SHA-256): AA:BB:CC:...
```
2. Stop the Proxy Agent service and delete its registration. Replace FivetranProxyAgent with your service name if you used a custom name:
```
%PROXY_HOME%\prunsrv.exe //SS//FivetranProxyAgent
%PROXY_HOME%\prunsrv.exe //DS//FivetranProxyAgent
```
3. Open the install_and_run_proxy_service.bat file you created earlier and modify the --JvmOptions line to include the KeyStore properties:
```
--JvmOptions "-XX:+HeapDumpOnOutOfMemoryError;-XX:HeapDumpPath=%PROXY_HOME%\logs;-Djavax.net.ssl.keyStore=<path_to_keystore>;-Djavax.net.ssl.keyStorePassword=<your_secure_password>" ^
```
  The .bat file now contains your KeyStore password. Restrict access to the file so that only the SYSTEM account and administrators can access it:
```
icacls "%PROXY_HOME%\install_and_run_proxy_service.bat" /inheritance:r /grant:r "NT AUTHORITY\SYSTEM":R "BUILTIN\Administrators":F
```
4. Remove the client_cert and client_private_key fields from the %PROXY_HOME%\config\proxyagent.conf file, so that the Proxy Agent relies only on the KeyStore for the certificate and private key. The file should look like this:
```
{
  "agent_id": "<your_agent_id>",
  "auth_token": "...",
  "orchestrator_host": "orchestrator.fivetran.com"
}
```
5. Rerun the updated .bat file to reinstall and start the service:
```
%PROXY_HOME%\install_and_run_proxy_service.bat
```
6. Check the Proxy Agent logs to confirm that the KeyStore was loaded successfully. By default, the log file is located at %PROXY_HOME%\logs\agent-out.log.
  If you configured a custom log directory using the log_folder_path setting in proxyagent.conf, the logs are written to that directory instead, for example, <log_folder_path>\agent-out.log.
  Look for entries similar to:
```
INFO: Certificates not found in config, attempting to load from KeyStore
INFO: Using KeyStore from javax.net.ssl.keyStore: <path_to_keystore>
INFO: Successfully loaded certificates from KeyStore for alias: orchestrator.fivetran.com
```

Install Proxy Agent on Linux

Perform the installation steps as a regular user (for example, fivetran). Use sudo only for steps that create system users, modify files under /etc, or manage the systemd service.

The Proxy Agent service runs as root. The examples below use the fivetran home directory for installation paths. Ensure that the installation directories and files are readable by root so the service can access the binaries and configuration.

The commands to set the environment variable depend on the shell you use. The examples below work in Bourne Shell (sh), KornShell (ksh), and bash.

Run the following command to verify that the Linux machine uses systemd. The output of the command should be systemd:
```
ps -p 1 -o comm=
```
Create a regular user account to set up the installation directory and environment variable (for example, fivetran):
```
sudo useradd -m fivetran
```
Switch to the fivetran user:
```
sudo su - fivetran
```
Configure the environment variable PROXY_HOME to point to the installation directory, and add it to the startup file (for example, .profile) so that it is available in future sessions:
```
export PROXY_HOME=/home/fivetran/fivetran-proxy-agent
echo 'export PROXY_HOME=/home/fivetran/fivetran-proxy-agent' >> ~/.profile
```
Create the installation directory and its config and logs subdirectories:
```
umask 022
mkdir -p $PROXY_HOME/config $PROXY_HOME/logs
```
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. The proxyagent.conf file is the exception: it contains credentials, so you restrict it to its owner when you create it.
Copy the downloaded ZIP file to the /tmp directory of the Linux machine. Alternatively, download it directly using the signed download URL:
```
cd /tmp
wget -O fivetran-proxy-agent-<version>-linux_x64.zip "<signed_download_url>"
```
Extract the ZIP file and move its contents into the PROXY_HOME directory. The ZIP file contains a top-level folder named fivetran-proxy-agent-<version>-linux_x64:
The unzip utility is required. If it isn't installed, install it using your distribution's package manager (for example, sudo apt install unzip or sudo yum install unzip).
```
unzip -q /tmp/fivetran-proxy-agent-<version>-linux_x64.zip -d /tmp
cp -r /tmp/fivetran-proxy-agent-<version>-linux_x64/. $PROXY_HOME/
rm -rf /tmp/fivetran-proxy-agent-<version>-linux_x64 /tmp/fivetran-proxy-agent-<version>-linux_x64.zip
```
After extraction, the jre directory and the proxyagent.jar file are in the PROXY_HOME directory.
Create the $PROXY_HOME/config/proxyagent.conf file and paste the entire contents of the configuration file (config.json) you've generated into it. Then restrict the file so that only its owner can read and write it:
```
chmod 600 $PROXY_HOME/config/proxyagent.conf
```
The configuration file contains the settings and authentication parameters required to establish secure communication between the Proxy Agent and Fivetran, including the authentication token and private key. Don't make it readable by other users.
Run the following command to validate the Proxy Agent settings:
```
$PROXY_HOME/jre/bin/java -jar $PROXY_HOME/proxyagent.jar -v $PROXY_HOME/config/proxyagent.conf
```
If the configuration file is valid, the command prints:
```
Config is valid: {"agent_id":"<your_agent_id>","auth_token":"***","orchestrator_host":"orchestrator.fivetran.com","client_cert":"-----BEGIN CERTIFICATE-----\n...","client_private_key":"***"}
```
The auth_token and client_private_key values are masked in the output. If the command returns an error, check that your proxyagent.conf file contains valid JSON and all required fields.

Using sudo, create the /etc/systemd/system/fivetran_proxy.service file with the following contents. Replace /home/fivetran/fivetran-proxy-agent with your PROXY_HOME path, and <your_agent_id> with your agent ID to distinguish multiple agents on the same machine:

[Unit]
Description=Fivetran Proxy Agent - <your_agent_id>

[Service]
Type=simple

ExecStart=/home/fivetran/fivetran-proxy-agent/jre/bin/java \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/home/fivetran/fivetran-proxy-agent/logs/ \
  -jar /home/fivetran/fivetran-proxy-agent/proxyagent.jar \
  /home/fivetran/fivetran-proxy-agent/config/proxyagent.conf

# 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

Using sudo, execute the following commands to start the Proxy Agent service.
a. Reload the systemd daemon to register the new service file:
```
sudo systemctl daemon-reload
```
b. Enable the service:
```
sudo systemctl enable fivetran_proxy.service
```
c. Start the service:
```
sudo systemctl start fivetran_proxy.service
```
d. Verify the status of the service. The output should include Active: active (running):
```
sudo systemctl status fivetran_proxy.service
```
If the status is failed or inactive, check the $PROXY_HOME/logs/agent-out.log file or run journalctl -u fivetran_proxy.service for details.
(Optional) If you are using a KeyStore for certificate management, configure the Proxy Agent to load the KeyStore by setting the required JVM system properties.
Expand for instructions

Configure KeyStore settings for Linux installation
1. (Optional) Validate that the JRE bundled with the Proxy Agent can read the KeyStore you created. Replace /path/to/keystore.p12 with the full path to your KeyStore file:
```
sudo $PROXY_HOME/jre/bin/keytool -list -keystore /path/to/keystore.p12 -storetype PKCS12 -storepass <your_secure_password>
```
  Expected output:
```
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 1 entry

orchestrator.fivetran.com, Jan 15, 2025, PrivateKeyEntry,
Certificate fingerprint (SHA-256): AA:BB:CC:...
```
2. Edit the /etc/systemd/system/fivetran_proxy.service file and add the KeyStore properties before the -jar argument in ExecStart:
```
ExecStart=/home/fivetran/fivetran-proxy-agent/jre/bin/java \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/home/fivetran/fivetran-proxy-agent/logs/ \
  -Djavax.net.ssl.keyStore=/path/to/keystore.p12 \
  -Djavax.net.ssl.keyStorePassword=<your_secure_password> \
  -jar /home/fivetran/fivetran-proxy-agent/proxyagent.jar \
  /home/fivetran/fivetran-proxy-agent/config/proxyagent.conf
```
  The service file now contains your KeyStore password. Restrict the file so that only root can read it:
```
sudo chmod 600 /etc/systemd/system/fivetran_proxy.service
```
3. Remove the client_cert and client_private_key fields from the $PROXY_HOME/config/proxyagent.conf file, so that the Proxy Agent relies only on the KeyStore for the certificate and private key. The file should look like this:
```
{
  "agent_id": "<your_agent_id>",
  "auth_token": "...",
  "orchestrator_host": "orchestrator.fivetran.com"
}
```
4. Reload the systemd daemon and restart the Proxy Agent service:
```
sudo systemctl daemon-reload
sudo systemctl restart fivetran_proxy.service
```
5. Check the Proxy Agent logs to confirm that the KeyStore was loaded successfully. By default, the log file is located at $PROXY_HOME/logs/agent-out.log.
  If you configured a custom log directory using the log_folder_path setting in proxyagent.conf, the logs are written to that directory instead (for example, <log_folder_path>/agent-out.log).
  Look for entries similar to:
```
INFO: Certificates not found in config, attempting to load from KeyStore
INFO: Using KeyStore from javax.net.ssl.keyStore: <path_to_keystore>
INFO: Successfully loaded certificates from KeyStore for alias: orchestrator.fivetran.com
```

After the service starts, confirm that the Proxy Agent status is Connected on the Proxy Agents page of your Fivetran dashboard.

Proxy Agent directory structure

After installation, the PROXY_HOME directory contains the following directories and files:


📁 proxy-agent
│
├─ 📁 config         --  Proxy Agent configuration file (proxyagent.conf)
│
├─ 📁 jre            --  Bundled Java Runtime Environment
│
├─ 📁 logs           --  Log files, heap dumps, and thread dumps
│
├─ 📄 proxyagent.jar                       --  Proxy Agent application
│
├─ 📄 proxyagent.ver                       --  Proxy Agent version number
│
├─ 📄 prunsrv.exe                          --  Windows service wrapper (Windows only)
│
├─ 📄 RELEASE_NOTES.md                     --  Proxy Agent release notes
│
└─ 📄 proxyagent-<version>.3rdparty.html.zip  --  Third-party software licenses and notices

Do not modify the jre directory or the proxyagent.jar file. These must remain unchanged to ensure security and integrity during updates or upgrades. User-specific configuration is stored in the config directory, and runtime data is written to the logs directory.

Configure Proxy Agent recovery (recommended for Windows)

Expand for instructions

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:

This process is not required on Linux systems.

Go to Control Panel > Administrative Tools > Computer Management > Services and Applications > Services or use the services.msc command to open the Services console.
In the Services console, locate the Fivetran Proxy Agent service. Ensure the service description matches the installation directory.
Right-click the service and select Properties.
Go to the Recovery tab.
Set your preferred recovery options for the failure scenario.

The SC failure command-line utility is also available for more advanced configurations. This tool allows you to automate recovery actions directly through the command line.

Upgrade Proxy Agent

The following sections explain how to migrate a legacy JAR-based Proxy Agent to the current infrastructure and upgrade a supported JAR-based installation.

Migrate a legacy JAR-based Proxy Agent to the current infrastructure

Fivetran has retired the legacy Proxy Agent infrastructure. A Proxy Agent running a version earlier than 1.1.0, or version 1.1.0 or later with "enable_migration": false in its configuration file (proxyagent.conf), may no longer connect, causing affected connections to fail. If the Proxy Agent can still connect through the legacy infrastructure, upgrade it to version 1.1.0 or later, remove "enable_migration": false from the configuration file if present, and start the upgraded agent. This migration only works in regions where the legacy infrastructure is still available. If the Proxy Agent can no longer connect, upgrading it in place or changing enable_migration alone will not restore connectivity. Instead, create a new Proxy Agent using the Configure Proxy Agent instructions and assign it to the affected connections.

Upgrade a JAR-based Proxy Agent

If you're replacing a Proxy Agent running a version earlier than 1.1.0 with a new Proxy Agent, your existing firewall rules may not be sufficient for the new Proxy Agent. Before you start the new Proxy Agent, confirm your firewall meets the current network requirements, including access to the Proxy Broker and the Proxy Server hostname for every Fivetran cloud processing region used by connections routed through this Proxy Agent. If your outbound network policy uses IP addresses resolved from our domains, you will need to re-resolve and update them. We recommend using domain names rather than IP addresses in your outbound network policy.

Before upgrading the Proxy Agent, we recommend making a copy of the Proxy Agent configuration file located on the Proxy Agent machine: PROXY_HOME/config/proxyagent.conf for the binary distribution, or hvr_config/proxy/proxyagent.conf for a Proxy Agent installed with the High-Volume Agent installer. Backing it up preserves the existing Proxy Agent configuration. If you use the embedded certificate method (the default), this also preserves the certificates used to establish secure communication with us. If you use the KeyStore method instead, back up your KeyStore file separately, since your certificate and private key are not stored in the configuration file. This lets you quickly restore your configuration if you need to revert to an earlier Proxy Agent version after an upgrade or reinstall, without having to generate a new Proxy Agent configuration file.

Upgrade Proxy Agent installed using the binary distribution

Download the latest Proxy Agent ZIP file for your platform.
Stop the Proxy Agent service:
- Windows Server: Replace FivetranProxyAgent with your service name if you used a custom name.
```
%PROXY_HOME%\prunsrv.exe //SS//FivetranProxyAgent
```
- Linux:
```
sudo systemctl stop fivetran_proxy.service
```
Delete the jre directory and the other files in the PROXY_HOME directory, except the config and logs directories, your KeyStore file if you stored it in PROXY_HOME, and, on Windows, the install_and_run_proxy_service.bat file.
Extract the new ZIP file into the PROXY_HOME directory, as described in the extraction step of Install Proxy Agent on Windows Server or Install Proxy Agent on Linux.

Start the Proxy Agent service:

Windows Server:

%PROXY_HOME%\prunsrv.exe //ES//FivetranProxyAgent

Linux:

sudo systemctl start fivetran_proxy.service

Confirm that the Proxy Agent status is Connected in your Fivetran dashboard.

Migrate Proxy Agent installed using the High-Volume Agent installer

The Proxy Agent is no longer distributed with the High-Volume Agent (HVA) installer. If you installed the Proxy Agent using the HVA installer (EXE or ZIP file on Windows, or the HVA package on Linux), migrate it to the binary distribution:

Back up your existing Proxy Agent configuration file, hvr_config/proxy/proxyagent.conf.
Stop and remove the existing Proxy Agent service:
- Windows: Open the Services console (services.msc), locate the Fivetran Proxy Agent service, and note its service name. The EXE installer names the service FivetranProxyPrunsrv_<HASH>, and the ZIP installation names it FivetranProxy_<HASH>. Then run the following commands as an Administrator, replacing <service_name> with that name:
```
sc stop <service_name>
sc delete <service_name>
```
- Linux: Run the following commands to stop, disable, and remove the fivetran_proxy.service service:
```
sudo systemctl stop fivetran_proxy.service
sudo systemctl disable fivetran_proxy.service
sudo rm /etc/systemd/system/fivetran_proxy.service
sudo systemctl daemon-reload
```
  Don't delete the hvr_home or hvr_config directories at this step. If the High-Volume Agent shares them, it still needs them. To clean up the old Proxy Agent files after migrating, see step 5.
If the High-Volume Agent is installed in the same directory, removing the Proxy Agent service doesn't affect it.
Install the binary distribution using the Install Proxy Agent instructions. In the step where you create proxyagent.conf, use the contents of the configuration file you backed up instead of generating a new one.
If the configuration file you backed up contains the proxy_server_uri field (Proxy Agent versions earlier than 1.1.0, or version 1.1.0 or later with "enable_migration": false), don't reuse it. Instead, create a new Proxy Agent using the Configure Proxy Agent instructions and assign it to your affected connections.
Confirm that the Proxy Agent status is Connected in your Fivetran dashboard.
(Optional) Removing the service doesn't delete the old Proxy Agent files. After the binary distribution is connected, you can delete the old hvr_home/proxy and hvr_config/proxy directories. If the High-Volume Agent uses the same hvr_home and hvr_config directories, delete only these proxy subdirectories and keep the rest. If you don't use the High-Volume Agent, you can delete the hvr_home, hvr_config, and hvr_tmp directories.

Uninstall Proxy Agent

Follow the instructions below to uninstall the Proxy Agent.

The Windows and Linux instructions below apply to the Proxy Agent installed from the binary distribution. If you installed the Proxy Agent using the High-Volume Agent installer (in the hvr_home and hvr_config directories), follow the Uninstall Proxy Agent installed using the High-Volume Agent installer instructions instead.

If you are uninstalling the Proxy Agent to perform an upgrade, we recommend making a copy of the Proxy Agent configuration file (PROXY_HOME/config/proxyagent.conf) located on the Proxy Agent machine. Backing it up preserves the existing Proxy Agent configuration, including the certificates used to establish secure communication with Fivetran. This lets you quickly restore the configuration if you need to revert to an earlier Proxy Agent version after an upgrade or reinstall, without having to generate a new Proxy Agent configuration file.

Uninstall Proxy Agent from Windows

Ensure that no Windows Services management console applications (opened via services.msc) are running.

Run the following commands as an Administrator to stop the Proxy Agent service and remove it. Replace FivetranProxyAgent with your service name if you used a custom name:
```
%PROXY_HOME%\prunsrv.exe //SS//FivetranProxyAgent
%PROXY_HOME%\prunsrv.exe //DS//FivetranProxyAgent
```
(Optional) Delete the PROXY_HOME directory.

Uninstall Proxy Agent from Linux

Stop the Proxy Agent service:

 sudo systemctl stop fivetran_proxy.service

Disable the service from auto-starting at boot:

 sudo systemctl disable fivetran_proxy.service

Remove the service configuration file:

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

Reload the systemd manager configuration:
```
 sudo systemctl daemon-reload
```
Clear the systemd state for any failed services:
```
 sudo systemctl reset-failed
```
(Optional) Delete the PROXY_HOME directory.

Uninstall Proxy Agent installed using the High-Volume Agent installer

If you installed the Proxy Agent using the High-Volume Agent (HVA) installer, its files are in the hvr_home/proxy and hvr_config/proxy directories. The configuration file is hvr_config/proxy/proxyagent.conf.

Uninstall Proxy Agent installed using the HVA installer from Windows

Open the Services console (services.msc), locate the Fivetran Proxy Agent service, and note its service name. The EXE installer names the service FivetranProxyPrunsrv_<HASH>, and the ZIP installation names it FivetranProxy_<HASH>. Close the Services console before you continue.
Run the following commands as an Administrator to stop the service and remove it. Replace <service_name> with the service name you noted:
```
sc stop <service_name>
sc delete <service_name>
```
(Optional) Delete the old Proxy Agent files. See Delete the old Proxy Agent files.

Uninstall Proxy Agent installed using the HVA installer from Linux

Stop, disable, and remove the Proxy Agent service:

 sudo systemctl stop fivetran_proxy.service
 sudo systemctl disable fivetran_proxy.service
 sudo rm /etc/systemd/system/fivetran_proxy.service
 sudo systemctl daemon-reload
 sudo systemctl reset-failed

(Optional) Delete the old Proxy Agent files. See Delete the old Proxy Agent files.

Delete the old Proxy Agent files

Removing the service doesn't delete the Proxy Agent files.

If the High-Volume Agent uses the same hvr_home and hvr_config directories, delete only the hvr_home/proxy and hvr_config/proxy subdirectories. Keep the rest of the directories, because the High-Volume Agent still needs them.
If you don't use the High-Volume Agent, you can delete the hvr_home, hvr_config, and hvr_tmp directories.