Skip to main content

SSH Tunnels

Use an SSH tunnel when your database sits in a private network or VPC and should not be exposed on the public internet. The tunnel encrypts traffic and only requires outbound SSH from a small host you control to FunnelStory’s tunnel service.

When to use a tunnel​

Reach for a tunnel when:

  • The database has no public hostname, or your policy forbids opening it to the internet.
  • You prefer a bastion or jump host in front of the data store.

After the tunnel is running, create your database connection in FunnelStory and select the tunnel configuration so queries route through it.

What you need​

A Linux instance (for example a small EC2 instance) that:

  • Can connect to your database on the private network.
  • Can open an outbound SSH session to FunnelStory’s tunnel host.
  • Can keep a long-lived SSH process running (manually, via autossh, or systemd).

Register a tunnel in FunnelStory​

  1. Go to Configuration → Tunnels (or your workspace’s tunnel management screen).
  2. Click Add tunnel and follow the prompts.
  3. Copy the private key FunnelStory provides and install it on your tunnel instance with restrictive permissions:
chmod 0400 /path/to/key.pem

Start the tunnel​

FunnelStory shows an SSH command similar to:

ssh -i key.pem -o "ExitOnForwardFailure=yes" -NR 127.0.0.1:50000:${DB_HOST}:${DB_PORT} tunnel@tunnel.funnelstory.ai

Replace placeholders with your database host, port, and the local port assigned in the UI. ExitOnForwardFailure=yes makes SSH exit if forwarding cannot be established.

Optional: restart loop​

For a simple keep-alive loop:

#!/bin/bash
KEY_PATH="/path/to/key.pem"
while true; do
  ssh -i "$KEY_PATH" -o "ExitOnForwardFailure=yes" -o "ServerAliveInterval=10" -o "ServerAliveCountMax=3" \
      -NR 127.0.0.1:50000:my_private_postgres:5432 tunnel@tunnel.funnelstory.ai
  echo "Tunnel dropped; retrying in 5s..."
  sleep 5
done

Optional: autossh or systemd​

Use autossh or a systemd unit to supervise the tunnel so it restarts on failure and optionally starts on boot. Point ExecStart at the same ssh (or autossh) line the UI provides.

Connect your database in FunnelStory​

When the tunnel process is healthy, add your PostgreSQL, MySQL, or other supported database connection in Configuration → Connections and choose the tunnel you registered. Validate and connect as usual.