SSH tunneling

Retool supports connecting to Postgres, MySQL, MSSQL, MongoDB, Cassandra, Redis, Vertica, and Rethink databases that are hosted within a private network via SSH tunneling using the following steps

  1. Open up a new connection for your database type. At the bottom of the form, there is a section that allows you to connect via an SSH Tunnel. Once enabled, the following form will appear:

  1. You will be asked for the host that Retool should establish the SSH tunnel to as well as a link to download Retool's public key. Retool will attempt to connect to your bastion host with the corresponding private key and the username retool.

  2. In order for Retool to successfully establish the tunnel you will need to configure your bastion host to allow Retool to connect.

  3. Create a user account for Retool. Below is a sample script run for different environments.

[email protected]:~$ sudo adduser retool --disabled-password
Adding user `retool' ...
Adding new group `retool' (1003) ...
Adding new user `retool' (1003) with group `retool' ...
Creating home directory `/home/retool3' ...
Copying files from `/etc/skel' ...
Changing the user information for retool3
Enter the new value, or press ENTER for the default
Full Name []:
Room Number []:
Work Phone []:
Home Phone []:
Other []:
Is the information correct? [Y/n] y
# Do not create a password for the retool user
[email protected]:~$ sudo adduser retool --password NP

To authorize Retool to connect to the host, you will now need to edit the contents at the file /home/retool/.ssh/authorized_keys to also include the contents of the public key from step 2 in a newline.

# Login as root
sudo su

# Create the authorized_keys file if it does not exist yet
mkdir -p /home/retool/.ssh
touch /home/retool/.ssh/authorized_keys

# Use your favorite editor to add Retool's public key to the file
vim /home/retool/.ssh/authorized_keys

# Set permissions on the authorized_keys file
chmod 644 /home/retool/.ssh/authorized_keys

# Change owner of authorized_keys file to Retool
chown retool:retool /home/retool/.ssh/authorized_keys

If you want to minimize access to your servers, add our IP addresses to your allowlist:
  1. Once that has been successfully configured, you can now use your database's private IP address within the rest of the connection form.

On-premise Environment

The above steps should also work in most on-premise deployments - Retool in most cases will auto-provision your environment with a keypair.

Retool on-premise also supports the use of custom ssh keys and usernames. Inside your retool_onpremise git repository, there is "keys" directory. This directory is mounted as a volume into the Retool container. You may now put any private key you wish to use from within Retool into this directory. For example, if you wanted to use mykey.pem, you would place it under the keys directory, and then in the interface for connecting my database, you would use something resembling below.

Debugging Common Connection Errors

All configured authentication methods failed.

This error usually means Retool is able to reach the SSH host, but can't authenticate. Confirm that you have created a retool user and the Retool public key has been added to your authorized keys.

Channel open failure: Connection refused

This error occurs when the SSH tunneling config is working but the host/port you tried to connect to has refused the connection.

Could not establish a connection. Try checking your database firewall configuration and whitelisting Retool's IP address.

This error usually occurs when you run into a firewall or other configurations aren't properly setup. For example, trying to connect Postgres to an HTTP port, incorrect SSH tunnel configs or the database host/port are wrong. Try going through the steps below to identify the specific error:

  1. Did you create a retool user on your SSH host and add the public key?
  2. If you have access to the SSH host, try connecting Retool while monitoring the auth logs (tail -f /var/log/auth.log). if you're not seeing any connection attempts, then you may not have whitelisted Retool's IP.
  3. While debugging, use the proper SSH tunnel configs, but set the database configs to something bogus, e.g. localhost:5555. If the SSH tunnel is fine, you should see the "Connection refused" error, and you'll know that your database configs are the problem, not the SSH tunnel configs.

Did this page help you?