SSH Tunnels

SSH tunnels provide secure access to MongoDB databases behind firewalls or in private networks by creating an encrypted connection through an SSH bastion server.

Overview

SSH tunneling wraps your MongoDB connection in an encrypted SSH channel, allowing you to:

• Connect to databases in private networks without exposing MongoDB ports
• Secure connections over untrusted networks
• Access databases behind corporate firewalls
• Avoid complex VPN configurations

How SSH Tunnels Work

1. MongoDash establishes an SSH connection to your bastion server
2. SSH creates an encrypted tunnel to the MongoDB server
3. MongoDB traffic flows through the secure SSH tunnel
4. The bastion server forwards traffic to your MongoDB instance

MongoDash → SSH Tunnel → Bastion Server → MongoDB Database

SSH Authentication Methods

MongoDash supports two SSH authentication methods:

Password Authentication

Simple username/password authentication.

SSH Host: bastion.example.com
SSH Port: 22
SSH Username: mongouser
SSH Password: ••••••••

SSH Key Authentication

Public/private key pair authentication (recommended for production).

SSH Host: bastion.example.com
SSH Port: 22
SSH Username: mongouser
SSH Private Key: [Paste private key content]
SSH Passphrase: [Optional passphrase]

Configuring SSH Tunnels

SSH Key Setup

Generating SSH Keys

Generate an SSH key pair on your local machine:

ssh-keygen -t rsa -b 4096 -C "mongodash-connection"

This creates:

• Private key: ~/.ssh/id_rsa (keep secure, paste into MongoDash)
• Public key: ~/.ssh/id_rsa.pub (add to bastion server)

Adding Public Key to Bastion Server

Copy your public key to the bastion server:

ssh-copy-id -i ~/.ssh/id_rsa.pub mongouser@bastion.example.com

Or manually append to authorized keys:

cat ~/.ssh/id_rsa.pub | ssh mongouser@bastion.example.com "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Using Private Key in MongoDash

Port Forwarding Configuration

SSH tunnels use local port forwarding to route MongoDB traffic.

Default Port Forwarding

By default, MongoDash automatically selects a random local port:

Local Port (random) → SSH Tunnel → MongoDB Host:Port

Custom Local Port

Specify a custom local port if needed:

SSH Tunnel Configuration:
- Local Bind Address: 127.0.0.1 (default)
- Local Port: 27018 (custom)
- Remote Host: mongodb-internal.example.com
- Remote Port: 27017

Multiple Database Tunnels

Connect to multiple databases through the same bastion:

Connection 1: localhost:27018 → bastion → db1.internal:27017
Connection 2: localhost:27019 → bastion → db2.internal:27017
Connection 3: localhost:27020 → bastion → db3.internal:27017

Common Configurations

MongoDB on Same Server as SSH

MongoDB running on the SSH bastion server:

SSH Host: bastion.example.com
SSH Port: 22
MongoDB Host: localhost
MongoDB Port: 27017

MongoDB on Private Network

MongoDB on a separate server in the private network:

SSH Host: bastion.example.com
SSH Port: 22
MongoDB Host: mongodb-internal.private
MongoDB Port: 27017

MongoDB Atlas via SSH

Connecting to Atlas through a bastion server:

SSH Host: bastion.example.com
SSH Port: 22
MongoDB Host: cluster0-shard-00-00.mongodb.net
MongoDB Port: 27017
MongoDB Connection String: mongodb://cluster0.mongodb.net/db

SSH Tunnel Options

Keep Alive Settings

Configure SSH keep-alive to prevent connection drops:

Server Alive Interval: 60
Server Alive Count Max: 3

These settings send keep-alive packets every 60 seconds and close the connection after 3 failed responses.

Compression

Enable SSH compression for better performance over slow networks:

Compression: Enabled

Strict Host Key Checking

Control SSH host key verification:

• Strict (Recommended): Verify host key against known hosts
• Accept New: Accept new hosts, verify known hosts
• Disabled: Skip host key verification (not recommended)

Security Best Practices

SSH Server Configuration

Harden your SSH bastion server:

1. Disable password authentication (force key-based auth)
2. Change default SSH port (reduce automated attacks)
3. Enable SSH key-only authentication
4. Restrict SSH access by IP (firewall rules)
5. Use fail2ban (block brute force attempts)
6. Keep SSH server updated (security patches)

Example /etc/ssh/sshd_config:

Port 22
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
AllowUsers mongouser

Network Isolation

Design secure network topology:

Internet → Bastion Server (Public) → MongoDB (Private Network)

• Bastion server has public IP and SSH access only
• MongoDB servers have private IPs, no direct internet access
• Firewall rules restrict bastion to MongoDB ports only

Key Management

Protect SSH private keys:

1. Use passphrases on private keys
2. Rotate keys regularly (every 90 days recommended)
3. Revoke compromised keys immediately
4. Use separate keys for each environment
5. Store keys securely (encrypted storage)

Audit Logging

Enable SSH connection logging on bastion server:

# View SSH connection logs
sudo tail -f /var/log/auth.log

Troubleshooting SSH Tunnels

Connection Refused

Symptom: "Connection refused" or "Cannot connect to SSH server"

Solutions:

• Verify SSH server hostname and port
• Check firewall allows SSH port (22)
• Confirm SSH service is running: sudo systemctl status sshd
• Test SSH connection manually: ssh username@bastion.example.com

Authentication Failed

Symptom: "Permission denied" or "Authentication failed"

Solutions:

• Verify SSH username is correct
• Check password or private key
• Ensure public key is in ~/.ssh/authorized_keys
• Verify file permissions: chmod 600 ~/.ssh/authorized_keys
• Check SSH logs: sudo tail /var/log/auth.log

Host Key Verification Failed

Symptom: "Host key verification failed"

Solutions:

• Remove old host key: ssh-keygen -R bastion.example.com
• Verify host key fingerprint with server administrator
• Update known_hosts file
• Check for man-in-the-middle attack (DNS spoofing)

MongoDB Connection Through Tunnel Failed

Symptom: SSH connects but MongoDB connection fails

Solutions:

• Verify MongoDB host/port from bastion server
• Test MongoDB connection from bastion: mongo mongodb-internal:27017
• Check MongoDB firewall rules
• Verify MongoDB is binding to correct interface
• Confirm network routing from bastion to MongoDB

Tunnel Timeout

Symptom: Connection drops after period of inactivity

Solutions:

• Enable SSH keep-alive settings
• Increase server timeout values
• Check network equipment timeout settings
• Configure MongoDB connection pool settings

What's Next?

• Connection Security
• Connection Troubleshooting
• Connection Types