SSH Tunnel Connections

Qaze can connect to private NATS servers through an SSH tunnel.

This is useful when your NATS servers are only reachable from a bastion host (sometimes also called a jump host).

How It Works

Qaze uses a single SSH connection (single hop) to one bastion host and then forwards traffic to your NATS server(s).

• One Qaze connection = one SSH tunnel configuration
• The same SSH tunnel settings are used for both the work connection and the optional system account connection
• If your NATS URL contains multiple servers, Qaze creates one local forward per server internally

You still enter your normal NATS server URLs in Qaze (for example private/internal hostnames). Qaze handles the local forwarding automatically.

Supported SSH Authentication

• Password
• Private key (file path)
• Private key with passphrase

Configure an SSH Tunnel in Qaze

Open your connection in Qaze and configure two tabs:

1. General Tab (NATS connection)

Configure your NATS connection as usual:

• Connection Type: Standard or NATS CLI Context
• Enter/select your NATS server URL(s) or context

Examples:

• Single server: nats://nats-1.internal:4222
• Multiple servers: nats://n1.internal:4222,nats://n2.internal:4222

Important:

• These are the NATS hosts as seen from the SSH bastion host, not from your laptop.
• Do not replace them with local forwarded ports. Qaze creates those automatically.

2. SSH Tunnel Tab

Enable and configure the SSH tunnel:

• Use SSH Tunnel: enabled
• SSH Host: your bastion host (for example bastion.company.net)
• SSH Port: usually 22
• SSH Username: SSH user on the bastion host
• Authentication Method: Password or Private Key
• Disable strict host verification: optional (recommended only for local testing)

Password Authentication Example

• Authentication Method: Password
• Password: your SSH password

Private Key Authentication Example

• Authentication Method: Private Key
• Private Key Path: path to your private key file (for example ~/.ssh/id_ed25519)
• Private Key Passphrase: only if your key is protected

Standard vs Context Connections

SSH tunnels work with both connection modes:

• Standard (URL-based)
• NATS CLI Context (context name or context file)

For context connections, keep using your normal context. Qaze applies the SSH tunnel to the context's server URL(s) automatically.

Multi-Server URLs (Clusters / Failover)

Qaze supports NATS URLs with multiple servers while SSH tunneling is enabled.

Example:

nats://n1.internal:4222,nats://n2.internal:4222,nats://n3.internal:4222

Qaze will:

1. Open one SSH connection to the bastion host
2. Create local forwards for each listed NATS server
3. Rewrite the URLs internally
4. Connect the NATS client through those local forwarded ports

This means all listed servers must be reachable from the same bastion host using the same SSH credentials.

Host Verification

By default, Qaze uses strict SSH host verification.

If the SSH server is not in your known_hosts, connection attempts may fail with an error like:

knownhosts: key is unknown

You have two options:

1. Add the host key to your known_hosts (recommended)
2. Enable Disable strict host verification (useful for local testing)

Example to add a host key:

ssh-keyscan -p 22 bastion.company.net >> ~/.ssh/known_hosts

Troubleshooting

connection refused when connecting to SSH

Check:

• SSH host and port are correct
• SSH server is running
• You can connect manually with ssh

knownhosts: key is unknown

Strict host verification is enabled and the host key is not trusted yet.

• Add the host to known_hosts, or
• Temporarily disable strict host verification for testing

EOF after enabling SSH tunnel

This often means the SSH connection worked, but the bastion host could not reach the target NATS server.

Check:

• NATS hostname/port is correct from the bastion host's perspective

Current Limitations

• Qaze currently supports a single SSH bastion host (single hop)
• Multi-hop SSH jump chains are not supported yet
• All servers in a multi-server NATS URL list must be reachable through the same SSH tunnel configuration