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
| UI Field | Technical Implementation | Description | Required | Default Value |
|---|---|---|---|---|
| Enable SSH? | Controls separate ssh2 client usage | Checkbox to enable/disable SSH connection | Yes (if using tunnel) | false |
| SSH Host | SSH connection host | Remote SSH server hostname | Yes | None |
| SSH Port | SSH connection port | SSH server port number | No | 22 |
| SSH Username | SSH user | Username for SSH authentication | Yes | None |
| SSH Password | SSH password | Password for SSH authentication | No (if using key) | None |
| SSH Private Key | SSH key | Path to SSH private key for key-based auth | No (if using password) | None |
| SSH Passphrase | SSH key passphrase | Passphrase for encrypted private keys | No | None |
Authentication Options
SSH tunneling supports multiple authentication methods:
| Auth Type | UI Mapping | Description |
|---|---|---|
| Password | SSH Username/SSH Password fields | Standard username/password SSH authentication |
| Key-based | SSH Private Key field | SSH key-based authentication (more secure) |
| Key with Passphrase | SSH Private Key + SSH Passphrase fields | SSH key-based authentication with encrypted keys |
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.