Skip to main content

Configure SSH tunneling for resources

Learn how to enable SSH tunnels to your data sources.

Retool supports SSH tunneling for the following data sources if they are hosted on a private network:

Configure SSH tunneling​

You can configure SSH tunneling when creating a new resource or update the configuration of an existing resource. To update an existing resource, navigate to the Resources tab in your Retool organization settings, then select the resource to update.

  1. On your resource's configuration page, select the Enable SSH tunnel checkbox in the Advanced Options section.

Enable SSH tunnel from resource configuration

  1. Enter the Bastion host and Bastion port with which Retool connects, then download Retool's public key. If you have multiple Retool organizations, download the public key for each organization you want SSH access for. Retool will attempt to connect to your bastion host with the corresponding private keys and the username retool.

  2. Configure your bastion host to allow connections from Retool.

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

Ubuntu
ec2-user@bastion:~$ 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
Amazon Linux
# Do not create a password for the retool user
ec2-user@bastion:~$ sudo adduser retool --password NP

To authorize Retool to connect to the host, add the contents of the public keys from step two on a new line in /home/retool/.ssh/authorized_keys.

# 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 Retool's 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.

SSH tunneling with OpenSSH 8.7 and newer​

Retool's public key is generated using ssh-rsa. This was deprecated in OpenSSH 8.8, but OpenSSH 8.7 can also be affected. If you are using this or a newer version of OpenSSH, add the following line to your sshd_config file to allow this type of key:

PubkeyAcceptedKeyTypes +ssh-rsa

Ensure that you restart your SSH server once you save your changes.

Self-hosted Retool deployments​

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.

note

Refer to the rotate SSH keys guide for instructions on key rotation. After you download the public key, follow the steps in Configure SSH tunneling to add it to authorized_keys.

Debug 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.

Slow queries or timeouts​

Connections between Retool and the bastion host may be throttled. If queries are timing out or slow to resolve, add the following line to your sshd_config file.

MaxStartups 1000:1000:1000