Connecting Through Reverse SSH Tunnel

Last updated on Jun 02, 2023

Hevo can connect to your database via a Reverse SSH Tunnel. This is only available under business plan. Reverse SSH tunneling or remote port forwarding helps you connect to a remote (and private) network without needing 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 was formed from the remote system to your local system, it is called a 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 Flowchart


Installing an SSH Client

SSH is installed by default on Linux-based systems (for example, Ubuntu and Red Hat) and the latest version of Windows (Version 10). Read Get started with OpenSSH.

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

  1. 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
    
    
  2. 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 SSH public key you wish to connect with.

Once Hevo gets your request it creates an SSH user for your team and allocates a set of ports that you can use to tunnel the traffic. Hevo provides you the following details that you can use to set up the reverse SSH tunnel and configure your Source:

  • ssh_host: The hostname of the SSH instance.

  • ssh_user: The username you would be using to connect to the SSH instance. This applies to your entire team.

  • a set of remote_forward_ports: A list of ports that Hevo allocates to you for tunneling the traffic. You can use one port for each DB host you want to fetch the data from.


Connecting to the SSH Instance Using CLI

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

  • Run the following 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
    

    Refer to the following table for the values of the variables.

    Configuration Description
    <REMOTE_FORWARD_PORT> Any port from the list of ports allocated by Hevo to tunnel the traffic.
    <DB_HOSTNAME_OR_IP> The hostname or IP address of the DB instance you want to connect to.
    <DB_PORT> The port your database is listening on.
    <SSH_USER>@<SSH_HOST> -g -i The SSH user name provided to you by Hevo.
    <SSH_HOST> The hostname of the SSH server provided to you by Hevo. This starts with the region your account is created in. For example, us-tunnel.hevodata.com.
    <PATH_TO_PRIVATE_KEY> -o The path to the SSH private key available with you.
    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.

    If you prefer to connect using the SSH config, use the following option.

  • Provide the settings using the SSH configuration file:

    1. Edit your SSH config file, normally 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 command with the values of the variables as defined in the SSH config file. Specify the port number to be assigned to the database from the list provided by Hevo.

         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
      

    This sets up the reverse SSH tunnel.


Connecting to the SSH Instance in Windows using PuTTY

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

  1. Download PuTTY.

  2. Start a new PuTTY session and specify the following settings, provided to you by Hevo. Refer to section, Requesting a Reverse SSH Tunnel.

    1. Host Name: The IP address or DNS of the Hevo host (ssh_host). Default value: us-tunnel.hevodata.com.

    2. Port: The port provided by Hevo to listen for connection. Default value: 22

      Host Name

    3. Under Connection, click Data, and then specify the ssh_user in the Auto-login username.

      Username

  3. Click SSH, and select the Don’t start a shell or command at all check box.

    SSH Checkbox

  4. Click Auth, and then click Browse to search for your PuTTY Private Key (PPK) that matches the public key you added in Hevo. Refer to Changing the passphase of a key to know how to convert your SSH private key to PPK.

    Auth Browse

  5. Click TTY, and select the Don’t allocate a pseudo-terminal check box.

    TTY Checkbox

  6. Click Tunnels, and specify the following:

    1. Source port: The port assigned to your connection. For example, 1504.

    2. Destination: The host and port of the database that you want to connect to. For example mysql.mydb.com:3306.

      Source Port

  7. Select the Remote option, and click Add.

  8. Click Session, and under the Saved Sessions section, enter a name for your session. For example, Hevo.

    Saved Sessions

  9. Click Save. Double-click the Hevo session to initiate the connection.


Connecting the Database to Hevo

While connecting the database to Hevo, for the Database Host specify the <SSH_HOST>, and for the Database Port, specify the <REMOTE_FORWARD_PORT>.

Reverse SSH settings

Example

Let us suppose that you are configuring a MySQL Source and have:

  • A MySQL server (can also be a private subnet), and

  • An internet gateway with an ssh client installed with the following configuration:

    • Host: mysql-server.my-org.com

    • Port: 3306

    • Username: mysql_server_user

    • Password: mysql_s3rv3r_p@@5w0rd

    • Private_key_path: /Users/my_user/.ssh/id_rsa

When you request for a reverse SSH tunnel, Hevo provides you the following details:

  • Host: us-tunnel.hevodata.com

  • Username: my_org_hevo_user

  • Ports: 1500, 1501, 1502, 1503, 1504, 1505, 1506, 1507, 1508, 1509

Based on these details:

  1. Connect to the reverse SSH tunnel by entering the following command on your terminal:

      ssh -f -N -R 1504:mysql-server.my-org.com:3306 my_org_hevo_user@region-tunnel.hevodata.com -g -i /Users/my_user/.ssh/id_rsa -o ServerAliveInterval=30 -o ServerAliveCountMax=1 -o ExitOnForwardFailure=yes
    
  2. As part of configuring MySQL as the Source in your Hevo Pipeline using reverse SSH tunnel, you specify the settings as follows:

    Reverse SSH Example

    • Database Host: us-tunnel.hevodata.com

    • Database Port: 1504

    • Database User: mysql_server_user

    • Database Password: mysql_s3rv3r_p@@5w0rd


Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Aug-10-2022 NA - Added sections, Installing an SSH Client and Connecting to the SSH Instance in Windows using Putty.
- Renamed section, Connecting to the SSH Instance to Connecting to the SSH Instance Using CLI.
Oct-25-2021 NA Improved the content on the page for better guidance on using a reverse SSH tunnel.

Tell us what went wrong