Skip to main content

Configure SSH tunneling for resources

Learn how to enable SSH tunnels to your data sources.

Version: Self-hosted 3.148 Stable

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

Retool is building support for querying firewalled resources without SSH tunnels and firewalled resources that do not support SSH. To learn more or be considered for early access, contact cloud-connect@retool.com.

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.

Self-hosted Retool also supports the use of custom SSH keys and usernames. To configure these, create a volume mount for the /retool_backend/keys directory in the Retool container, and add any private key you wish to use from within Retool into this directory. For example, if you want to use myprivatekey.pem, the SSH tunnel configuration for the resource would resemble the following:

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