SSH Tunneling

👤 This documentation is intended for Workspace Admins. Check with your Team Admin for additional access.

Overview

Preset can connect to some databases securely by first establishing a connection to a server in between Preset and your data warehouse. Using this SSH Tunnel, communication between the data warehouse and Preset will be encrypted even across insecure networks.

When to use SSH tunneling

In general, there are two basic use cases for an SSH tunnel:

• When a direct connection is impossible.
• When a direct connection is forbidden due to a security policy.

Sometimes when a data warehouse is inside an enterprise environment, direct connections are blocked by security devices such as firewalls and intrusion prevention systems. Bastion hosts can first connect to a server on the edge of the protected network and then establish a second connection to the data warehouse within the internal network, patching these two connections together. Preset can automate this process using the SSH tunneling.

Another common case where direct connections are impossible is when connecting to a data warehouse that is only accessible locally and does not allow remote connections. In this case you will be opening an SSH connection to the data warehouse.

Before you start

Before starting, allowlist the following IPs to ensure that Preset is whitelisted in your firewall:

If you are not sure where your Preset workspace is located, you can refer to the URL on your browser when accessing Preset. It should look like this: https://xxxxxxxx.us2a.app.preset.io/superset..., where us2a means it is in us-east-1.

How to use SSH tunneling

To use Preset's SSH feature, follow the main instructions for connecting your data. Enter the Primary Credentials portion of the connection form as if connecting to a publicly addressable database.

Specifically:

• In the Host field, enter the hostname for the data warehouse as it is seen from inside the network.
• In the Port field, enter the data warehouse port as seen from inside the network.

Scroll down to the SSH Tunnel and toggle it on.

In the form that shows up, enter the following details:

• In the SSH Host field, enter the external name of the SSH bastion host as seen from the outside of the network (or wherever you are).
• In the SSH Port field, enter the SSH port as seen from outside the network. This is usually 22, regardless of which data warehouse you are connecting to.
• In the SS Username and SSH Password fields, enter the username and password you use to login to the bastion host.

If you're using an SSH Private Key, you can choose Private Key & Password to pull up the Private Key & Private Key Password fields.

When done, select Test Connection to see if it works — a notification message will appear. If no additional connection settings are required, then go ahead and select Connect.

Troubleshooting the SSH connection

If you have problems connecting, verify the SSH host port and password by connecting manually using ssh or PuTTY on older windows systems.

If you’re unable to test the SSH connection, you can try to connect to the SSH server/Bastion Host using ssh directly:
ssh <SSH tunnel username>@<SSH tunnel host> -p <SSH tunnel port>

Running SSH directly

Preset's SSH tunneling feature conveniently wraps around SSH and automates the common cases of connecting through a tunnel. Preset uses a built-in SSH client that doesn’t depend on the installed system’s SSH client. This allows connections from systems where you can’t run SSH manually or do not have shell access. Consequently, Preset can’t take advantage of authentication services provided by the system, such as Windows Domain Authentication or Kerberos Authentication.

If you need to connect using a method not enabled by Preset, you can often accomplish this by running SSH directly:
ssh -Nf -L input-port:internal-server-name:port-on-server username@bastion-host.domain.com
This allows you to use the full array of features included in SSH. If you find yourself doing this often, please let us know so we can make improvements.

Disadvantages of indirect connections

While using an SSH tunnel makes it possible to connect to a data warehouse that is otherwise inaccessible, it’s almost always preferable to use a direct connection when possible. Several limitations include:

• If the enclosing SSH connection is closed because you put your server/computer to sleep or change networks, all established connections will be closed as well. This can cause delays resuming connections after suspending your server/computer.
• SSH will be slower than a direct connection. The connection has to go through an additional host that mediates the connection to your database.
• Multiple operations over the same SSH tunnel can block each other and increase latency.
• The number of connections through a bastion host is often limited by organizational policy. Some organizations have IT security policies forbidding using SSH tunnels to bypass security perimeters.

That's it! You should now be able to connect to your database via SSH.