Connecting Through SSH

Last updated on Jan 17, 2023

Hevo provides you the option of connecting to your database host via an SSH tunnel. This SSH tunnel provides an additional layer of security to your connection. You should use an SSH connection when:

  • You are trying to connect with the local IP address of your database

  • The database(s) you want to connect to is(are) not publicly available

  • You cannot provide direct access to your database host

Before connecting through SSH, you must whitelist the IP addresses for your region on the SSH server.

You can configure multiple Sources in Hevo using the same SSH tunnel, but this might cause a delay in the replication of data from your Pipelines.

To establish a connection to Hevo through SSH, perform the following steps:

Select the SSH Option

While configuring the respective Source in your Hevo Pipeline, select the Connect through SSH option.

SSH option


Set up SSH Connection

When you select the Connect through SSH option, Hevo displays a public key on the UI. You must add this public key to the authorized_keys file in your SSH server. Based on the server you are using, perform the steps in one of the following sections to set up your SSH connection with Hevo:

SSH connection flowchart

Set up SSH connection on a Linux server

Perform the steps in this section if you are a Linux user, and want to connect to Hevo through SSH.

1. Create an SSH user and group

Log in to your SSH tunnel host and execute the following commands:

  1. Create a Hevo group:

    sudo groupadd Hevo
    
  2. Create a Hevo user:

    sudo useradd -m -g Hevo Hevo
    
  3. Switch to the Hevo user:

    sudo su - Hevo
    
  4. Create the .ssh directory:

    mkdir ~/.ssh
    
  5. Set the ssh permissions:

    chmod 700 ~/.ssh
    
  6. Switch to the .ssh directory:

    cd ~/.ssh

  7. Create the authorized_keys file:

    touch authorized_keys
    
  8. Set the permissions:

    chmod 600 authorized_keys
    
  9. Add the public SSH key visible in the Hevo UI to the authorized_keys file using a text editor of your choice.

2. Allow port access

You must ensure that Hevo is allowed port access from:

Perform the following steps to allow port access for your SSH tunnel servers and databases present in AWS:

  1. Navigate to the AWS EC2 console.

  2. In the Resources section, click Instances (running).

    Running instances

  3. In the Instances page, select the instance you want to use as an SSH tunnel.

    Select instance

  4. In the instance description, click the Security tab.

    Security tab

  5. Under Security groups, select the default security group.

    Default SG

  6. In the security group page, Inbound rules section, click Edit Inbound rules.

    Edit inbound rules

  7. In the Edit inbound rules page, click Add rule.

    Add rule

  8. To add the rule, do the following:

    Specify settings

    1. Under the Type column, select SSH for your rule.

    2. Under the Source column, select Custom, and specify Hevo’s IP address for your region.

    3. Click Save.

  9. To complete setting up your Source configuration, refer to section, Specify your SSH Server Details.

Set up SSH connection on a Windows server

Perform the steps in this section if you are a Windows user, and want to connect to Hevo through SSH. Hevo provides you two methods to do this:

Connecting to the SSH instance using OpenSSH

OpenSSH is a tool used to create a secure SSH connection to a remote system. Use the following steps to install OpenSSH on your system, create a user and group to be able to create a secure connection and prevent access from unauthorized users, and set up your PowerShell or Linux client in it.

1. Install OpenSSH

  1. Install the sshd server:

    Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
    
  2. Verify that the OpenSSH server is installed.

    Get-WindowsCapability -Online | ? Name -like 'OpenSSH.Server*'
    

    You must see the following message:

    Name : OpenSSH.Server~~~~0.0.1.0
    State : Installed
    
  3. Set the firewall to allow the following:
    Connection Direction: Inbound
    Protocol type: TCP
    Port: Default value: 22

    New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22
    
  4. Start the sshd service and ssh-agent:

    Start-Service sshd
    Set-Service -Name sshd -StartupType 'Automatic'
    Start-Service ‘ssh-agent’
    Set-Service -Name ‘ssh-agent’ -StartupType 'Automatic'
    

2. Create a Hevo user and group

  1. Add a local Hevo user:

    net user Hevo <password> /add /comment:"User for connecting to Hevo using SSH." /passwordchg:no /passwordreq:no /logonpasswordchg:no
    

    Note: Replace the <password> in the command above with the password of your choice.

  2. Add a Hevo group:

    net localgroup Hevo-group /comment:"Group for connecting to Hevo using SSH." /add
    

    Note: The user and group must have different names.

  3. On the Windows command prompt, change the directory to SSH server:

    cd C:\ProgramData\ssh\ && start notepad .\sshd_config
    
  4. Allow password authentication for the Hevo user:

    PasswordAuthentication yes
    
  5. In the sshd_config file, do the following:

    1. Add the following line to the file to allow the Hevo user to connect to the SSH server:

      AllowUsers Hevo
      
    2. Comment out the following lines, if your Windows version is 1809 or later:

      # Match Group administrators
      # AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys
      
    3. Save the file.

  6. Restart the ssh-agent and the sshd service for the changes to be reflected:

    Restart-Service ssh-agent; Restart-Service sshd
    

3. Set up your SSH client

  1. Enter the following command on the command prompt to log in to the SSH server using your Windows virtual machine:

    ssh Hevo@<Public IPv4 DNS>
    

    Note: Replace the <Public IPv4 DNS> in the command above with your own IP address.

  2. Specify your password.

  3. Create an .ssh folder in your home directory:

    mkdir .ssh
    
  4. Add the Hevo public key to the authorized_keys file, in one of the following ways:

    • If you are setting up a Windows PowerShell client:

      type nul > authorized_keys
      echo <Hevo-public-key> >> authorized_keys
      icacls C:\Users\Hevo\.ssh\authorized_keys /inheritance:r
      

      If you are using a non-elevated PowerShell, refer to step 5 for the additional steps to set up the client.

      Note: The elevated PowerShell displays Administrator: Windows PowerShell on the top of the window.

    • If you are setting up a Linux client:

      touch authorized_keys
      chmod 600 authorized_keys
      echo <Hevo-public-key> >> authorized_keys
      

      Note: Replace the <Hevo-public-key> in the commands above with the public key displayed on the Hevo UI.

  5. (For non-elevated PowerShell users only) Perform the following steps to setup the client:

    1. Enable public key authentication.

      PubkeyAuthentication yes
      
    2. Disable password authentication.

      PasswordAuthentication no
      PermitEmptyPasswords no
      
    3. Save the sshd_config file.

    4. Verify that inheritance is disabled and remove Administrator permissions to prevent the created user (Hevo) from inheriting administrative level permissions. To do this:

      1. Right click on the authorized_keys file.

      2. Click Properties.

      3. Click Security.

      4. Click Advanced.

      5. Verify that Enable Inheritance is visible on the bottom left. This means that inheritance is disabled.

      6. Remove Administrator from the file security permissions.

    5. Restart the ssh-agent and the sshd service for the changes to be reflected.

      Restart-Service ssh-agent; Restart-Service sshd
      

Connecting to the SSH instance using PuTTY and KiTTY

PuTTY and KiTTY are tools that allow you to set up a remote SSH client environment. Use the following steps to install PuTTY and KiTTY on your system, generate a private key, and set up your SSH connection with it.

1. Generate the public and private keys

  1. Download PuTTY and launch PuTTYgen.

  2. In the Actions section, click Generate to obtain the keys.

    Generate Key

    The OpenSSH public key appears in the top box.

  3. Copy the OpenSSH public key, and save it securely like any other password.

    Public Key

  4. Click Save private key, and save the .ppk file on your desktop.

    Private Key

2. Configure your SSH connection

  1. Run kitty-0.74.4.7.exe on your desktop to launch KiTTY.

  2. Configure your session using the following:

    • Host Name: Hevo@<Your Public IPv4 DNS>. For example, Hevo@192.4.7.146.

    • Port: Default value: 22.

  3. In the left navigation pane, under Connection, SSH, Auth, click Credentials.

  4. In the Private key file for authentication field, specify the private key that you downloaded, and click Tunnels.

  5. In the Port forwarding section, do the following:

    1. Select the following check boxes, if not selected already:

      • Local ports accept connections from other hosts

      • Remote ports do the same

    2. In the Source port field, specify the port assigned for your connection. Default value: 55432.

    3. In the Destination field, add your Destination address and its corresponding port. For example, localhost:55432 for a server hosted on the same virtual machine.

    4. Ensure that Remote is selected, and click Add.

  6. In the left navigation pane, click Connection, and set the value for seconds between keepalives to 5.

  7. Select both Reconnect options.

  8. Return to the Tunnels page.

  9. In the Saved Sessions/New Folder field, specify a name for the connection, and click Save.
    Another session is created in the bottom box.

  10. Click Open, and leave the window open.


Specify your SSH Server Details

Specify the following details while configuring the Source in your Hevo Pipeline:

Connection Settings

  • SSH IP: The IP address or DNS of the SSH server.

  • SSH Port: The port of the SSH server as seen from the public internet. Default value: 22

  • SSH User: The username on the SSH server as created in Step 2 above.

Refer to your respective Source page to complete the remaining Source configurations for creating the Pipeline.


Revision History

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

Date Release Description of Change
Jan-10-2023 NA Updated the page to add information about setting up an SSH connection on Linux and Windows.

Tell us what went wrong