You're browsing the documentation of a version that is still under development, the features described here may change or even be removed.

8.2.3. Secure connection via SSH tunnel

An SSH tunnel is a technique widely used to encrypt a connection between a client and a server via SSH application providing a security layer for the connection even in the absence of an SSL certificate. The SSH tunnel plug-in comes as a facility to configure and start SSH tunnels quickly.

Currently, SSH tunnels can only be used with the official OpenSSH client. On Linux, the SSH client is available by default or, at least, on your preferred distro's software repository. On macOS, the secure shell command is available by default. Finally, on Windows, OpenSSH client is offered as an optional software and can be installed by following these instructions.

The fields in the form above are described as follows:

  • SSH executable path: the path to the SSH application used to initialize tunnels.

  • Auto startup: indicates if the SSH tunnels must be started during pgModeler's startup.

  • Tunnel alias: a unique identifier for the SSH tunnel.

  • Local port: the local host port number in which the configured tunnel will be started.

  • Remote host: the endpoint IP address or domain name for the SSH tunnel. This is the machine that is ready for SSH connections.

  • SSH port: the listening port in the remote host for SSH connections.

  • Database host: the PostgreSQL server IP or domain name to connect when the SSH tunnel is established. It can be the remote host itself or another machine address that is accessible from the remote host.

  • DB port: the database server listening port.

  • Username: the SSH username of the remote machine.

  • Password: the SSH password of the remote machine. If an identity file is used to connect to the remote host then this will be used as the identity file's security passphrase. Be aware that this field is only a convenience to avoid repeatedly typing the password during the tunnel initialization, use it with extreme care since it is saved as plain text in the settings. Also, ensure that only your user has access to the pgModeler's configuration files since they store sensitive data that can be exploited.

  • Identity file: the file from which the identity (private key) for public key authentication is read. Refer to SSH documentation for more details.

  • Extra arguments: extra arguments that are passed to the SSH executable during tunnel startup. Refer to SSH documentation for more details.

After configuring an SSH tunnel, you have to configure a database connection in such a way to use the tunnel's database host combined with the local port so the encrypted connection can be established correctly.

Finally, to start the configured SSH tunnels (if they aren't in auto-start mode) just hit on main window's top toolbar and wait for the tunnels initialization before connecting to a database. It's worth mentioning that despite the extra security that SSH tunnels offer, they can degrade the data transmission speed due to all the overhead that encryption/decryption operation of the data have, so connecting to a database and running commands may take longer via a secure tunnel than performing the same operations directly on an ordinary database connection.

WARNING: Connections' passwords are stored in plain text format in the settings. To avoid security issues, make sure to protect the access to the directory where pgModeler settings are saved in the local user's storage (OS-dependent) from other users than the one running the tool. There are plans to use cryptography over stored passwords in future releases.

Oct 31, 2024 at 09:12