SSH Tunnel

An SSH Tunnel lets you connect Gravity to your database or file server through a bastion host or a tunnel server. This connection type is used if you are unable to add an inbound firewall rule to your data warehouse, or your data warehouse IP address is on an internal network (no outside network access)

Gravity supports both SSH Tunnel and Reverse SSH Tunnel.

SSH Tunnel

Preparing the user and tunnel

You will need to prepare your host (either bastion host or tunnel server) by creating an gravity user and adding your account’s public key to the gravity ~/.ssh/authorized_keys file. Here’s how:

1. Create group gravity

   sudo groupadd gravity

2. Create user gravity and its home directory:

   sudo useradd -m -g gravity gravity

3. Switch to the gravity user

   sudo su - gravity

4. Create the .ssh directory and change permission

   mkdir ~/.ssh && chmod 700 ~/.ssh

5. Create the authorization_keys file and change permission

   touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys

   Using your favorite text editor, add your account’s public key to the authorized_keys.

6. Allow access to your server's host and port from Gravity's IP addresses

Tunnel Security Notes

By default, opening SSH access also allows forwarding of any ports, circumventing any firewalls between Grand the database host that is terminating the SSH tunnel. For better security, limit port forwarding and the ability to log in to your tunnel server. This can be controlled by properly configuring the ~/.ssh/authorized_keys entry for your account's public key.

For example, the following text could be prepended to your SSH key in your authorized_keys file. Please note that this text MUST be customized for your environment.

no-pty,no-X11-forwarding,permitopen="localhost:5432",permitopen="localhost:3306",
command="/bin/echo Login Not Permitted"

See the man ssh and man authorized_keys pages for examples and full details.

Reverse SSH Tunnel

Step 1: Contact GravityData with your SSH public key

To set up a reverse SSH tunnel, you’ll need to provide GravityData with the following:

• The public key corresponding to the SSH keypair you plan to use to establish the tunnel

• The SSH user you plan to use to establish the tunnerl

• The IP address(es) that you’ll connect to the Gravity SSH server from

• GravityData user's SSH public key

  • Goto Sources -> New Connection -> Select Source -> Check Connect via SSH -> Copy Public Key

Once our team receives this information, we’ll set up a secure SSH server for you to connect to. We’ll provide you with the SSH_HOST and TUNNEL_PORT info needed to establish the SSH connection.

Step 2: Establish the reverse SSH tunnel

After you receive the SSH connection information from us, you can establish the SSH tunnel. There are two methods you can use to accomplish this:

• With autossh (recommended)

• Without autossh

With autossh (recommended)

We recommend running SSH through autossh, which will start a copy of SSH, monitor it, and automatically restart the tunnel if it goes down or stops passing traffic. If you don’t already have autossh installed, you’ll need to do so before continuing. Refer to autossh’s documentation for instructions.

The following command will establish the tunnel using autossh. When you run this, replace the items in brackets:

autossh -M 0 -f -N -R <TUNNEL_PORT>:<DATABASE_HOST_OR_IP>:<DATABASE_PORT> -i <SSH_PRIVATE_KEY> <SSH_USER>@<SSH_HOST> -o ServerAliveInterval=10 -o ServerAliveCountMax=1 -o ExitOnForwardFailure=ye

The <DATABASE_HOST_OR_IP> and <DATABASE_PORT> values are the host/endpoint and port of the database you’re connecting from, respectively. For <TUNNEL_PORT> and <SSH_HOST>, use the values you received from our team.

For example: Here’s the same command, but with all the values inserted:

autossh -M 0 -f -N -R 15432:database.yourcompany.com:5432 -i id_rsa.pem yourcompany@11.22.33.44 -o ServerAliveInterval=10 -o ServerAliveCountMax=1 -o ExitOnForwardFailure=yes

Without autossh

To establish the tunnel without using autossh, run the following command, replacing the items in brackets:

ssh -f -N -R <TUNNEL_PORT>:<DATABASE_HOST_OR_IP>:<DATABASE_PORT> -i <SSH_PRIVATE_KEY> <SSH_USER>@<SSH_HOST>

The <DATABASE_HOST_OR_IP> and <DATABASE_PORT> values are the host/endpoint and port of the database you’re connecting from, respectively. For <TUNNEL_PORT> and <SSH_HOST>, use the values you received from our team.

Here’s the same command, but with all the values inserted:

ssh -f -N -R 15432:database.yourcompany.com:5432 -i id_rsa.pem yourcompany@11.22.33.44

Step 3: Create Source in Gravity App

After establishing a successful Reverse SSH connection, enter the following into the GravityData setup form for your database:

FIELD		DESCRIPTION
Server	localhost
Port	<TUNNEL_PORT>	e.g., 15432. Use the value you received from our team
DB user	{Database user}
DB password	{Database user's password}
Database	{Database name}	The name of the database you want to replicate
Connection Method	Connect via an SSH
SSH server	<SSH_HOST>	Use the value you received from our team
SSH Port	22
SSH User	gravitydata