Connecting Through SSH

Last updated on Feb 28, 2024

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.

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.

Hevo does not recommend configuring a log-based Pipeline for database Sources that receive connection requests through a network load balancer (NLB). This is because the database endpoint that Hevo connects to for ingesting data from the logs varies depending on the network node. As a result, Hevo may fetch data from different logs in each Pipeline run, causing the Pipeline to break.

Establishing an SSH connection involves specifying the SSH server details and the SSH host key to be used for data encryption. Hevo supports both Rivest-Shamir-Adleman (RSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) encryption algorithms. However, we recommend ECDSA encryption, as these keys are generated using modern cryptographic operations and are more secure. The corresponding SSH client keys (private keys) are maintained by Hevo on its servers and are used to decrypt the data for loading.

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

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

Connect Through SSH Flowchart


Select the SSH Option

While configuring the respective Source or Destination in your Hevo Pipeline, select the Connect through SSH option. Hevo displays its ECDSA and RSA public host keys in the UI. You need to specify one of these host keys while setting up the SSH connection.

Connect Through SSH option


Set up SSH Connection

Based on the server you are using, perform the steps in one of the following sections to set up your SSH connection with Hevo:

Note: Read Unable to Verify SSH Details if you are using our RSA public key and your SSH server runs on a newer Linux version, such as Ubuntu 22 or Amazon Linux 2023.

Set up an 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 run 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 host 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:

By default, Azure and Google Cloud Platform (GCP) allow port access for SSH connections on port 22. However, in AWS, you must allow port access on this port by performing the following steps:

Note: To set up an SSH connection on a different port, you must contact Hevo Support.

  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 the section, Specify your SSH Server Details.

Set up an 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.

You can set up your SSH connection:

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:

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

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 placeholder value in the command above with your own. For example, <password> with a 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\
    
  4. Start the notepad and open the sshd_config file:

    start notepad .\sshd_config
    
  5. In the sshd_config file, do the following:

    1. Allow password authentication for the Hevo user:

      PasswordAuthentication yes
      
    2. Add the following line to the file to allow the Hevo user to connect to the SSH server:

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

      # Match Group administrators
      # AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys
      
    4. 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

Note: Replace the placeholder values in the commands with your own. For example, <Hevo-public-key> with the SSH host key (ECDSA or RSA public key) copied from the Hevo UI.

  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>
    
  2. Specify your password.

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

    mkdir .ssh
    
  4. Change the directory to the .ssh folder:

    cd .ssh
    
  5. 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 6 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
      
  6. (For non-elevated PowerShell users only) Perform the following steps to set up 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, Security, and Advanced.

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

      4. 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 or Destination 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 that you created in Step 2 above.

To connect to your SSH server, add one of the Hevo public keys in the authorized_keys file on your SSH server:

  • ECDSA Public Key (Recommended): This public key is generated using the Elliptic Curve Digital Signature Algorithm (ECDSA), which is a newer asymmetric encryption algorithm. This algorithm generates a key pair by performing mathematical operations on elliptic curves. ECDSA keys are faster due to their smaller sizes (256 or 348 bits) and are also more secure.

  • RSA Public Key: This public key is generated using Rivest-Shamir-Adleman (RSA), which is an older asymmetric encryption algorithm. This algorithm generates a key pair by factorizing large numbers. RSA keys provide a high level of security if the key size is at least 2048 bits.

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-22-2024 NA Added information about not using NLB for log-based Pipelines.
Aug-16-2023 2.15.3 Added information about support for ECDSA-generated public keys.
Mar-09-2023 NA Updated section, Allow port access to add information about allowing port access on Azure and GCP.
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