Skip to main content

Connect to Sylvan via SSH Tunnel

Step-by-step guide to connecting your database to Sylvan through an SSH bastion host

Written by Sylvan Team
Updated this week

Use this method when your database is on a private network and can't be made publicly accessible.

This article is source-agnostic. It applies to Redshift, PostgreSQL, SQL Server, and any other direct-connection source that supports SSH tunneling.

In this article we are going to cover the following topics:

When do you need an SSH tunnel?

Sylvan connects directly to your database endpoint over the internet. If your database is in a private VPC with no public IP, Sylvan can't reach it. An SSH tunnel routes the connection through a bastion host (also called a jump box) that sits in a public subnet and can reach your private database.

You need an SSH tunnel if:

  • Your database cluster has "Publicly accessible" disabled and your security team won't enable it

  • Your database endpoint resolves to a private IP (e.g. 10.x.x.x, 172.16.x.x)

  • Your organization requires all external vendor connections to go through a bastion

You do NOT need an SSH tunnel if:

  • Your database has a public endpoint and you can whitelist Sylvan's IP (34.123.149.4) in your security group

Prerequisites

Before configuring SSH tunneling in Sylvan, make sure you have:

  1. A bastion host (e.g. an EC2 instance) in a public subnet within the same VPC as your database

  2. The bastion must be able to reach your database on the relevant port (e.g. 5439 for Redshift, 5432 for PostgreSQL)

  3. The bastion must allow inbound SSH (port 22) from Sylvan's IP: 34.123.149.4

  4. A sylvan user on the bastion with Sylvan's public key in its authorized_keys (setup instructions below)

Most teams already have a bastion host for tools like dbt, Fivetran, or Looker. You can reuse the same host.

Step 1: Generate Sylvan's public key

In the Sylvan connection form, select SSH tunnel as the connection method and click Generate Public Key. Sylvan creates a unique key pair for your account. The public key is displayed in the UI for you to copy.

Step 2: Create the sylvan user on your bastion

SSH into your bastion host and create a user for Sylvan. Do not create a password for the sylvan user.

Ubuntu / Debian:

sudo adduser sylvan --disabled-password

Amazon Linux / RHEL / CentOS:

sudo adduser sylvan --password NP

Step 3: Add Sylvan's public key to the bastion

To authorize Sylvan to connect to the host, add the contents of the public key from Step 1 on a new line in

/home/sylvan/.ssh/authorized_keys

# Login as root sudo su # Create the authorized_keys file if it does not exist yet mkdir -p /home/sylvan/.ssh touch /home/sylvan/.ssh/authorized_keys # Use your favorite editor to add Sylvan's public key to the file vim /home/sylvan/.ssh/authorized_keys # Set permissions on the authorized_keys file chmod 644 /home/sylvan/.ssh/authorized_keys # Change owner of authorized_keys file to Sylvan chown sylvan:sylvan /home/sylvan/.ssh/authorized_keys

Step 4: Whitelist Sylvan's IP on the bastion (optional)

If you want to minimize access to your servers, add Sylvan's IP address to your allowlist. In the security group attached to your bastion host, add an inbound rule:

Type

Port

Source

SSH

22

34.123.149.4/32

How it works

When you click Connect or when a sync runs:

  1. Sylvan opens an SSH connection to your bastion host as the sylvan user, authenticating with the generated key pair

  2. Traffic is forwarded through the bastion to your database's private endpoint

  3. The database connection runs through this encrypted tunnel

  4. When the sync completes, the tunnel is torn down

Your database never needs a public IP. The only publicly exposed surface is the bastion host, which only accepts SSH from Sylvan's IP.

Troubleshooting

"SSH connection failed" / "Authentication failed"

  • Verify the sylvan user exists on the bastion: id sylvan

  • Verify the public key is in /home/sylvan/.ssh/authorized_keys

  • Check file permissions: authorized_keys should be 644, .ssh directory should be 700

  • Check that the bastion's security group allows inbound SSH from 34.123.149.4

"Tunnel established but database connection failed"

  • The SSH tunnel is working but Sylvan can't reach the database through the bastion

  • Verify the bastion can reach the database: from the bastion, run nc -zv <db-host> <db-port>

  • Check that the database security group allows inbound traffic from the bastion's private IP

  • Verify DB credentials are correct

"Connection timed out"

  • The bastion may not be reachable. Verify it has a public IP or elastic IP

  • Check that port 22 is open in the bastion's security group for 34.123.149.4/32

  • Confirm the bastion instance is running

Did this answer your question?