Skip to main content

SSH Tunneling

Connect to databases on private networks using SSH tunneling through a bastion/jump host.

Overview​

SSH tunneling allows Beyond to securely connect to databases that are not publicly accessible. Instead of exposing your database to the internet, Beyond connects through an SSH bastion host that forwards the connection to your private database.

Supported databases:

  • PostgreSQL
  • MySQL

How It Works​

Beyond Cloud → SSH Bastion (public) → Your Database (private)

Beyond authenticates with your bastion host using SSH key authentication, then establishes a tunnel to forward database traffic securely.

Setup Steps​

1. Download Beyond's Public Key​

Download Beyond's SSH public key to add to your bastion host:

curl https://app.beyondscreen.ai/api/ssh-public-key -o beyond-ssh-key.pub

Or download it from the Beyond UI when configuring your data source.

2. Configure Your Bastion Host​

Create a dedicated user for Beyond and add the public key:

# SSH into your bastion host
ssh your-user@bastion.company.com

# Create a beyond user (optional but recommended)
sudo useradd -m -s /bin/bash beyond

# Add Beyond's public key
sudo mkdir -p /home/beyond/.ssh
sudo cat beyond-ssh-key.pub >> /home/beyond/.ssh/authorized_keys
sudo chmod 700 /home/beyond/.ssh
sudo chmod 600 /home/beyond/.ssh/authorized_keys
sudo chown -R beyond:beyond /home/beyond/.ssh

3. Verify Network Access​

Ensure your bastion host can reach the database:

# From the bastion, test database connectivity
nc -zv your-db-host.internal 5432  # PostgreSQL
nc -zv your-db-host.internal 3306  # MySQL

4. Configure Data Source in Beyond​

In Beyond's data source configuration:

  1. Enable SSH Tunnel - Check the "Enable SSH Tunnel" checkbox
  2. Bastion Host - Your bastion's public hostname (e.g., bastion.company.com)
  3. Bastion Port - SSH port (usually 22)
  4. SSH Username - Username on bastion (e.g., beyond)
  5. Database Host - Use the private IP or hostname (e.g., 10.0.1.50 or db.internal)
  6. Database Port - Database port (e.g., 5432 for Postgres, 3306 for MySQL)
  7. Test Connection - Verify the tunnel works

Security Best Practices​

Dedicated SSH User​

Create a dedicated user with minimal permissions:

sudo useradd -m -s /bin/bash beyond
# Don't grant sudo access

Restrict SSH Key​

Add restrictions to authorized_keys:

restrict,command="/bin/false" ssh-ed25519 AAAAC3... beyond@beyondscreen.ai

This prevents the key from being used for interactive sessions or command execution.

Network Segmentation​

Configure bastion firewall to only allow connections to specific database ports:

# Allow only database ports
sudo ufw allow from any to 10.0.1.50 port 5432
sudo ufw deny out to any

Monitor Access​

Enable SSH logging and monitor connections:

# Monitor SSH logs
sudo tail -f /var/log/auth.log | grep beyond

Key Rotation​

Plan to rotate SSH keys periodically. Beyond will announce key rotations in advance via email.

Troubleshooting​

Connection Refused​

Symptom: "Connection refused" error when testing connection

Solutions:

  • Verify bastion can reach database: nc -zv db-host 5432
  • Check database is running and accepting connections
  • Verify firewall rules allow bastion → database traffic
  • Ensure you're using the private IP for the database host

SSH Authentication Failed​

Symptom: "SSH authentication failed" or "Permission denied"

Solutions:

  • Verify Beyond's public key is in ~/.ssh/authorized_keys
  • Check file permissions: chmod 600 ~/.ssh/authorized_keys
  • Ensure SSH username matches the user you created
  • Check SSH logs: sudo tail -f /var/log/auth.log

Timeout​

Symptom: Connection times out

Solutions:

  • Verify bastion host is reachable from the internet
  • Check security groups/firewall allow SSH (port 22) from Beyond's IPs
  • Verify bastion hostname resolves correctly: nslookup bastion.company.com

Wrong Database Credentials​

Symptom: Authentication successful but database login fails

Solutions:

  • Double-check database username and password
  • Verify database user has access from bastion's IP
  • Check database logs for authentication errors

Advanced Configuration​

Custom SSH Port​

If your bastion uses a non-standard SSH port:

# Edit sshd config
sudo vi /etc/ssh/sshd_config
# Set: Port 2222
sudo systemctl restart sshd

Then in Beyond, set Bastion Port to 2222.

Jump Host Chain​

For multi-hop scenarios, configure your primary bastion to forward to a secondary:

# On primary bastion
ssh -L 5432:secondary-bastion:22 user@secondary-bastion

Then configure Beyond to connect to the primary bastion.

Testing Locally​

Test the SSH tunnel manually before configuring in Beyond:

# From your local machine
ssh -L 5433:private-db:5432 beyond@bastion.company.com

# In another terminal, test connection
psql -h localhost -p 5433 -U dbuser -d mydb

If this works, the Beyond configuration should also work.

Need Help?​

  • Check bastion SSH logs: sudo tail -f /var/log/auth.log
  • Check Beyond connection logs in the UI
  • Contact support: support@beyondscreen.ai