Reverse SSH tunnel

Introduction

Use a reverse SSH tunnel when your database is in a private network and Holistics cannot connect to it directly. Instead of opening inbound access to your database or bastion server, a machine inside your network starts an outbound SSH connection to Holistics.

Holistics then connects to your database through that active tunnel. This keeps your database private while still allowing Holistics to query it.

When to use a reverse SSH tunnel

Reverse tunnels are useful when direct connection is not acceptable for your network or security model.

Use this approach when:

• Your database is behind a firewall, virtual private cloud, VPN, or closed network.
• Your security team does not allow exposing the database to the public internet.
• You cannot whitelist Holistics IP addresses on the database firewall.
• You want all database traffic to go through a dedicated encrypted SSH connection.
• You need the tunnel process to run from a controlled proxy or bastion server inside your network.

If your database can safely accept inbound connections from Holistics IP addresses, direct connection is usually simpler to operate.

How it works

With a direct connection, Holistics initiates the network connection to your database. That means your database, firewall, or bastion host must allow inbound access from Holistics.

With a reverse SSH tunnel, the connection direction is reversed. A proxy or bastion server inside your network initiates an outbound SSH connection to the Holistics tunnel server on port 50022.

The proxy server must be able to reach both sides:

• Outbound to the Holistics tunnel server on port 50022.
• Inbound or local network access to your database host and port.

Holistics does not need direct inbound access to your database, database subnet, or proxy server.

Security model

A reverse SSH tunnel reduces the public attack surface because your private network does not need to expose a database port to the internet. The only network connection that must be allowed from your environment is an outbound SSH connection from the proxy server to the Holistics tunnel server.

In practice, this means:

• No public database endpoint is required. The database can stay on a private IP address.
• No inbound firewall rule is required for Holistics. The tunnel is initiated from your network.
• Traffic is encrypted in transit. The tunnel uses SSH encryption between your proxy server and Holistics.
• Access is tied to SSH keys and assigned tunnel ports. Holistics authorizes the public key and maps your data source to a specific tunnel port.
• Tunnel ports are restricted. Tunnel ports are intended for Holistics servers, so you should not expect to connect to tunnel.holistics.io:[tunnel_port] directly from your own machine for testing.

The tunnel does not replace database-level security. You should still use a dedicated database user with only the permissions Holistics needs. See Create database user for more guidance.

Choose automatic or manual setup

Holistics supports two ways to set up reverse SSH tunnels. Choose one approach for a data source; you do not need to set up both.

Approach	Recommended for	What Holistics manages	What you manage
Automatic reverse SSH tunnel	Most Linux-based proxy or bastion servers	Script generation, SSH key registration, assigned tunnel port, and the h_autossh service	Running the generated command on your proxy server and maintaining that server
Manual reverse SSH tunnel	Unsupported operating systems, Windows, custom SSH operations, or strict change-control environments	Public key authorization and assigned tunnel ports	SSH key generation, tunnel command/profile, process supervision, startup behavior, and data source host/port entry

Unless you have a special requirement, use the automatic setup. It is less error-prone because Holistics generates the command, registers the public key, assigns the tunnel port, and creates a service to keep the tunnel running.

Use the manual setup when the automatic script does not fit your environment, for example Windows, non-Debian/non-RHEL Linux distributions, custom service managers, or internal policies that require manually reviewed SSH commands.

Tunnel servers

Holistics provides tunnel servers according to your region:

• For APAC: tunnel.holistics.io or apac-tunnel.holistics.io
• For EU: eu-tunnel.holistics.io
• For US: us-tunnel.holistics.io

When setting up a tunnel manually, make sure you connect to the tunnel server for your Holistics region.

FAQs

How about forward SSH tunnels?

Reverse tunnels already cover the main use case of forward tunnels: securely connecting to a firewall-protected database.

Reverse tunnels also avoid requiring a public IP address for your database or bastion server. For example, with a reverse tunnel, the proxy server can connect to a database on localhost or on a private network address.

If your use case specifically needs a forward tunnel, contact [email protected].

Can I test the tunnel by connecting directly to tunnel.holistics.io:[my_tunnel_port]?

No. Tunnel ports are restricted to Holistics servers, so you cannot use your own machine to connect directly to tunnel.holistics.io:[my_tunnel_port].

Instead, test the full connection from the Holistics data source form. You can also check whether the tunnel process is running and whether your proxy server can connect to the database.

For automatic tunnels, see Troubleshooting automatic reverse SSH tunnels. For manual tunnels, see Troubleshooting manual reverse SSH tunnels.