🚀   Portable does more than just ELT. Explore Our AI Orchestration Capabilities 

Troubleshooting SSH Tunnel Authentication Issues

Sergio
CTO

When using an SSH tunnel to connect to your database, Portable first authenticates with your bastion host (jump server). If this step fails, you'll see an "SSH Tunnel Auth" error in the diagnostic checks.

What This Means

Portable can reach your bastion host, but the SSH credentials you provided (username and password or private key) are being rejected.

Common Causes

1. Incorrect Username

The SSH username is case-sensitive and must match exactly what's configured on the server.

Common mistakes:

  • Using Root instead of root
  • Using your email instead of the system username
  • Using the database username instead of the SSH username

2. Private Key Format Issues

SSH private keys must be in PEM format. If your key starts with -----BEGIN OPENSSH PRIVATE KEY-----, it may need to be converted.

To convert from OpenSSH format to PEM:

ssh-keygen -p -m PEM -f your_key

Valid PEM format looks like:

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----

3. Wrong Private Key

You may have multiple SSH keys and are using the wrong one. Verify you're using the private key that corresponds to the public key installed on the server.

4. Public Key Not Installed on Server

Your public key must be added to the ~/.ssh/authorized_keys file on the bastion host for the correct user.

To add your public key:

# On the bastion host
echo "ssh-rsa AAAA...your-public-key... user@host" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

5. Password Authentication Disabled

If you're using password authentication, the SSH server may have it disabled (common security practice).

Check on server:

grep PasswordAuthentication /etc/ssh/sshd_config

If it shows PasswordAuthentication no, you must use key-based authentication.

6. Key Passphrase

If your private key is encrypted with a passphrase, Portable cannot use it directly. You'll need to provide an unencrypted key or remove the passphrase.

To remove passphrase from a key:

ssh-keygen -p -f your_key
# Enter old passphrase, then press Enter twice for no new passphrase

How to Diagnose

Test SSH connection locally

# With key-based auth
ssh -i /path/to/your/private_key username@bastion-host

# With password auth
ssh username@bastion-host

# Verbose mode for debugging
ssh -vvv -i /path/to/your/private_key username@bastion-host

If this works locally, the credentials are correct. The issue may be with how they're entered in Portable.

Verify key format

head -1 your_private_key
  • -----BEGIN RSA PRIVATE KEY----- → PEM format (good)
  • -----BEGIN OPENSSH PRIVATE KEY----- → OpenSSH format (needs conversion)
  • -----BEGIN ENCRYPTED PRIVATE KEY----- → Encrypted (needs passphrase removed)

Check authorized_keys on server

# On the bastion host
cat ~/.ssh/authorized_keys

Verify your public key is listed and the file has correct permissions:

ls -la ~/.ssh/
# Should show:
# drwx------ .ssh
# -rw------- authorized_keys

Check SSH server logs

On the bastion host:

sudo tail -f /var/log/auth.log        # Debian/Ubuntu
sudo tail -f /var/log/secure          # CentOS/RHEL

Then attempt a connection to see the specific error.

Cloud-Specific Instructions

AWS EC2

  • Default username varies by AMI: ec2-user (Amazon Linux), ubuntu (Ubuntu), admin (Debian)
  • Use the key pair you selected when launching the instance
  • Ensure the security group allows inbound SSH (port 22) from Portable's IPs (34.122.15.109)

Google Compute Engine

  • Use OS Login or manually add your public key via the console
  • Default username is typically your Google account username (before the @)

Azure VMs

  • Username is what you specified during VM creation
  • If using SSH key, ensure you're using the correct private key

Checklist

Before contacting support, verify:

  • Username is correct (case-sensitive)
  • Private key is in PEM format (starts with -----BEGIN RSA PRIVATE KEY-----)
  • Private key has no passphrase
  • Public key is in ~/.ssh/authorized_keys on the bastion
  • File permissions are correct (chmod 600 for key and authorized_keys)
  • You can SSH manually from your local machine with the same credentials

Still Stuck?

If you can SSH manually but Portable can't authenticate, contact support with:

  • The SSH username you're using
  • The format of your private key (first line)
  • Any errors from /var/log/auth.log on the bastion host
  • Your source/destination ID from Portable