Skip to main content

SSH data connections

Prepare the SSH host​

Prerequisites

You will need a host in your environment that can access the data source you would like to connect to from Hex. This host is often referred to as a bastion and must have a port accessible from Hex. SSH uses port 22 by default.

Currently, Hex supports connecting to the following data sources via SSH tunneling:

  • Amazon Athena
  • MySQL
  • Postgres
  • SQL Server
  • MariaDB
  • PrestoDB
  • Amazon Redshift

Configure SSH access​

On the bastion host, create a group and a user named hex then switch to this user. This user will be the SSH user used for tunneling.

tip

If the bastion host already has a user for tunneling, this section may be skipped in favor of using that user.

$ sudo groupadd hex
$ sudo useradd -m -g hex hex
$ sudo su - hex

Create a .ssh directory and authorized_keys files with appropriate permissions for the hex user.

$ mkdir ~/.ssh
$ chmod 700 ~/.ssh
$ cd ~/.ssh
$ touch authorized_keys
$ chmod 600 authorized_keys

Add your Workspace's Hex SSH public key to the bastion​

tip

You must be a workspace Admin to access the SSH public key.

Copy the public key from the bottom of the Settings → Data sources tab, under the "Workspace" header.

Import the public key into the authorized_keys file using the command below. Please replace <PUBLIC_KEY> with the public key.

echo "<PUBLIC KEY>" >> ~/.ssh/authorized_keys

Configure data connections to use SSH​

Once your ssh host is prepared with the public key. You can configure your data connections in Hex to use SSH. Toggle Connect via SSH on in your data connection configuration and add the details for:

  • SSH machine hostname or IP address
  • SSH port. This is usually 22.
  • SSH username ("hex" in our example)

SSH Tunneling Architecture Details​

  • Our client remains within our network perimeter and connects through this tunnel. No client software is installed on your bastion or within your network—it operates as a port forwarding mechanism from our database client into your environment.
  • The SSH connection is established on-demand rather than as a persistent tunnel. Each request initiates a new SSH session with appropriate port forwarding for that specific transaction.
  • All outbound connections originate from a dedicated static IP address for consistent security policy management.
  • Multiple bastion hosts can be configured behind a single DNS entry, providing redundancy and high availability.

On this page