Connecting Through Reverse SSH Tunnel

Hevo can connect to your database via a Reverse SSH Tunnel. This option is available only under the business plan. Reverse SSH tunneling or remote port forwarding helps you connect to a remote (and private) network without a public gateway.

Contrary to how SSH works, where you establish a secure connection with a remote system and can receive and send data, in reverse SSH, the remote system connects with your local system. Then, using the established connection, you can set up a connection to the remote system and fetch the data from that system. As the original connection is formed from the remote system to your local system, it is called reverse SSH.

The following diagram illustrates the steps to connect your Source database through reverse SSH in Hevo. These steps are explained in detail further in this document.

Connect Through Reverse SSH Process Flow

Installing an SSH Client

SSH is installed by default on Linux-based systems (for example, Ubuntu and Red Hat) and on Windows servers, version 10 onwards. Read Get started with OpenSSH if you need to install OpenSSH on your Windows server.

Perform the following steps to verify and install the SSH client on your machine if it is not already installed:

Verify whether your Windows machine has the SSH client installed. Run the following command in Windows PowerShell to do this:
```
Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH.client*'
```
The expected output:
```
Name : OpenSSH.Client~~~~0.0.1.0
State : Installed
```
If the State is NotPresent, run the following command to install the SSH client:
```
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```

Requesting a Reverse SSH Tunnel

To request a reverse SSH tunnel, contact Hevo either through the in-app support or by mailing us at support@hevodata.com with the public key for your SSH server.

Once Hevo processes your request, it provides you with the following details:

SSH Host: The hostname or IP address of the SSH instance.
SSH User: The username created by Hevo for your team to connect to the SSH instance.
Remote Forward Ports: A list of ports allocated by Hevo to your team for tunneling the traffic through reverse SSH. You can use one port for each database host from which you want to fetch data.

You can use these details to set up the reverse SSH tunnel and configure your Source.

Connecting to the SSH Instance Using CLI

To connect the reverse SSH host, do one of the following:

Connect directly using the following ssh command:

ssh -f -N -R <REMOTE_FORWARD_PORT>:<DB_HOSTNAME_OR_IP>:<DB_PORT> <SSH_USER>@<SSH_HOST> -g -i <PATH_TO_PRIVATE_KEY> -o ServerAliveInterval=30 -o ServerAliveCountMax=1 -o ExitOnForwardFailure=yes

Note:

In this option, all parameter values are provided on the command line.
Replace the placeholder values in the command above with your own. For example, <SSH_USER> with hevo_user.

Refer to the following table for a description of the parameters used in the command above:

Configuration	Description
<REMOTE_FORWARD_PORT>	Any port from the list of remote forward ports allocated by Hevo for tunneling the traffic.
<DB_HOSTNAME_OR_IP>	The hostname or IP address of your database instance.
<DB_PORT>	The port number on which your database listens for connections.
<SSH_USER>	The SSH username provided to you by Hevo.
<SSH_HOST>	The hostname of the SSH server provided to you by Hevo. This starts with the region in which your Hevo account is created. For example, us-tunnel.hevodata.com.
<PATH_TO_PRIVATE_KEY>	The location of the private key on your SSH server. This key must be the pair of the public key that you gave Hevo.
ServerAliveInterval	The interval in seconds, at which the server checks the connection. For example, 30, to indicate 30 seconds.
ServerAliveCountMax	The maximum number of server-alive messages for which a response may not be received before ssh disconnects from the server and terminates the session. For example, 1.

Connect using the SSH configuration file. For this:

Note: In this option, the values for your reverse SSH parameters are provided in the SSH configuration file.
1. Edit your SSH config file, generally found at the path, ~/.ssh/config.
2. Add the following reverse SSH settings to the file:
```
Host <SSH_HOST>
user <SSH_USER>
IdentityFile <PATH_TO_PRIVATE_KEY>
ServerAliveInterval 30
ServerAliveCountMax 1
ExitOnForwardFailure yes
```
3. Run the following ssh command to connect using the parameter values defined in the SSH config file. Refer to the table above for a description of the parameters.
```
ssh -f -N -R <REMOTE_FORWARD_PORT>:<DB_HOSTNAME_OR_IP>:<DB_PORT> <SSH_HOST> -g
```
  If you are using an SSH process manager, such as autossh, use the command:
```
autossh -M 0 -f -N -R <REMOTE_FORWARD_PORT>:<DB_HOSTNAME_OR_IP>:<DB_PORT> <SSH_HOST> -g
```
Note: Replace all placeholder values in the SSH configuration file and the commands above with your own. For example, <SSH_USER> with hevo_user.

Your reverse SSH tunnel is set up.

Connecting to the SSH Instance in Windows using PuTTY

Perform the following steps to create an SSH tunnel on Windows using PuTTY:

Download PuTTY.
Start a new PuTTY session and specify the following settings, provided to you by Hevo. Refer to section, Requesting a Reverse SSH Tunnel.
- Host Name: The IP address or DNS of the SSH instance (SSH Host).
- Port: The port provided by Hevo to listen for connections. Default value: 22
Under Connection, click Data, and in the Auto-login username, specify the SSH user created by Hevo for you.
Click SSH, and select the Don’t start a shell or command at all check box.
Click Auth, Credentials, and then click Browse to search for your PuTTY Private Key (PPK) that pairs with the public key you added in Hevo. Refer to Changing the passphase of a key to know how to add a passphrase to your SSH private key.
Click TTY, and select the Don’t allocate a pseudo-terminal check box.
Click Tunnels, and specify the following:
- Source port: The port assigned to your connection. For example, 1504.
- Destination: The host and port of the database that you want to connect to. For example pgsql.mydb.com:5432.
Select the Remote option, and click Add.
Click Session, and under the Saved Sessions section, enter a name for your session. For example, Hevo.
Click Save. Double-click the Hevo session to initiate the connection.

Connecting the Database to Hevo

While configuring your database Source in Hevo, specify the following for the database host and port:

Reverse SSH Settings

Example

Let us suppose that you are configuring a PostgreSQL Source, and the following are available to you:

A PostgreSQL server (can also be a private subnet).
An internet gateway with the following configuration:
- Host: postgresql-server.my-org.com
- Port: 5432
- Username: postgresql_server_user
- Password: pgsql_s3rv3r_p@@5w0rd
- Private_key_path: /Users/my_user/.ssh/id_rsa
An SSH client on the machine that acts as the internet gateway.

In response to your request for a reverse SSH tunnel, Hevo provides you with the following details:

SSH Host: us-tunnel.hevodata.com
SSH User: hevo_user
Remote Forward Ports: 1500, 1501, 1502, 1503, 1504, 1505, 1506, 1507, 1508, 1509

Based on these details:

Run the following command to connect to the reverse SSH tunnel:

ssh -f -N -R 1504:postgresql-server.my-org.com:5432 hevo_user@us-tunnel.hevodata.com -g -i /Users/my_user/.ssh/id_rsa -o ServerAliveInterval=30 -o ServerAliveCountMax=1 -o ExitOnForwardFailure=yes

As part of configuring your PostgreSQL instance as the Source in your Hevo, specify the settings as follows:
- Database Host: us-tunnel.hevodata.com
- Database Port: 1504
- Database User: postgresql-server.my-org.com
- Database Password: postgresql_s3rv3r_p@@5w0rd
- Database Name: my_database
- Publication Key: my_db_publication_key

Note: Hevo provides only the database host and port. The remaining information should be available to you.

Last updated on Sep 24, 2024