SSH Tunnelling
SSH tunneling is a secure method to access databases that are not directly accessible from your Gigantic instance. This documentation explains how SSH tunnels work and how to configure them properly.
What is SSH Tunnelling?
SSH (Secure Shell) tunneling is a network technique that creates a secure encrypted connection between your Gigantic instance and a remote database server through an intermediate SSH server. It's essentially a "tunnel" that allows you to bypass network restrictions and securely access databases.
When to Use SSH Tunnelling
Use SSH tunneling when your target database:
- Is not directly accessible - The database server is behind a firewall or in a private network that doesn't allow direct connections from your Gigantic instance
- Only listens on localhost - The database server is configured to only accept connections from localhost (127.0.0.1) for security reasons
- Requires network encryption - You need to ensure all data transmitted between your Gigantic instance and the database is encrypted
- Is in a remote/private network - The database is hosted in a remote data center, cloud private network, or corporate network
How SSH Tunneling Works
When you enable SSH tunneling, the connection flow becomes:
- Gigantic connects to the SSH server (using SSH credentials)
- SSH server forwards the connection to the target database server
- Database operations are performed through this secure tunnel
This creates a secure encrypted channel for database communications, protecting sensitive data and credentials in transit.
SSH Tunnel Connection Diagram
Below is a diagram showing how SSH tunneling works to securely connect to a database:
SSH Tunnel Configuration Parameters
The tunnel is set in the Advanced section of the tap or sink form. Check Enable SSH? to show its fields:
| UI Field | Description | Required | Default Value |
|---|---|---|---|
| Enable SSH? | Checkbox to connect to the database through an SSH tunnel | No | Unchecked |
| Host/IP | Hostname or IP address of the SSH server | Yes | None |
| Port | Port of the SSH server | Yes | None (usually 22) |
| User | Username for the SSH authentication | Yes | None |
| Auth method | How to authenticate on the SSH server: Password or Private key | No | Password |
Authentication Options
The fields shown below Auth method depend on the option selected:
| Auth method | UI Fields | Description |
|---|---|---|
| Password | Password (required) | Standard username/password SSH authentication |
| Private key | Set key path + Private key path + Passphrase | Key-based authentication with a key file on the Gigantics server. If the path is empty, the ~/.ssh/id_rsa key of the user running Gigantics is used |
| Private key | Enter key + Private key (required) + Passphrase | Key-based authentication with the key pasted in the form |
Passphrase is optional: fill it only when the private key is encrypted.
Best Practices
- Use key-based authentication when possible instead of passwords for better security
- Restrict SSH user permissions to only what's needed for database access
- Use non-standard SSH ports if security by obscurity is desired
- Regularly rotate SSH keys and update them in your Gigantic configuration
- Monitor SSH access logs to detect unauthorized access attempts
Troubleshooting SSH Tunnels
Common issues and solutions:
- Connection timeouts - Verify SSH server is reachable and port is correct
- Authentication failures - Check username, password/key, and passphrase
- Permission denied - Ensure SSH user has proper access to database server
- Key format issues - Ensure private key is in the correct format (usually PEM)
Related Documentation
Each database driver that supports SSH tunneling will link to this documentation for detailed configuration information. The individual driver documentation pages focus on their specific database connection parameters, while this page covers the common SSH tunnel configuration that can be applied across drivers.