Using SSH Tunnels
Using an SSH tunnel, DbVisualizer connects to the database through an encrypted connection to an SSH server. The tunnel is set up when you connect to the database.
You define the SSH servers as SSH configurations in Tool Properties, and select one for each database connection that uses a tunnel. Several connections can use the same SSH configuration.
For more about security for specific databases, see our support portal and the database and driver specific articles.
Managing SSH configurations
To manage the SSH configurations, do one of these:
- Open Tools → Tool Properties and select the Database Connection / SSH Configurations category under the General tab.
- In the Connection tab of a database connection, select Use SSH Tunnel, and select Create/Edit SSH configurations in the SSH Configuration drop-down list.
- In the Connection tab, right-click the SSH Configuration field and select Open SSH Configurator.

The grid lists the SSH configurations. Authentication shows the authentication type, Type the SSH implementation, and Used By the number of database connections that use the configuration; click the number to see them. To create a configuration, click the + button. When you select a configuration, its details and Advanced Options are shown below the grid.
Creating an SSH configuration
For every SSH configuration, enter:
- Name: A unique name for the configuration. To change it, click the button next to the field.
- Host: The name or IP address of the SSH server. If you use an SSH config file, enter the name of the Host entry in the file instead. The SSH server is often the same server as the database server.
- Port: The port of the SSH server. The default is 22.
- Userid: The user name on the SSH server. If you leave it empty, the user name is read from the SSH config file, if you use one. Otherwise, you are asked for it when you connect.
- Authentication Type: How you authenticate with the SSH server, see Authentication types.
Then click Test Connection to check the configuration, see Testing an SSH configuration.
Authentication types
Password
You authenticate using the password of the SSH user.

Enter the Password. If you leave it empty, you are asked for it when you connect. To keep the password after you close DbVisualizer, select Save Between Sessions. To protect saved passwords, set a master password.
Public key
You authenticate using a key pair. Enter the Private Key File. On the SSH server, add the public key, typically the file with the .pub extension, to the ~/.ssh/authorized_keys file of your user.

If the private key has a passphrase, enter it in Passphrase. If you leave it empty and select Ask if Empty, you are asked for the passphrase when you connect. To keep the passphrase after you close DbVisualizer, select Save Between Sessions. To protect saved passphrases, set a master password.
SSH agent
You authenticate using ssh-agent, so you don't enter a private key or password in DbVisualizer. This is supported on macOS and Linux. To add your key to the agent, run ssh-add in a terminal. See Adding your SSH key to the ssh-agent in the GitHub documentation.

Advanced options
The Advanced Options are the same for all authentication types:

- Description: An optional description of the SSH configuration.
- SSH Implementation: SSHJ (default and recommended) or JSch. They support different algorithms, so if you can't connect using one, try the other.
- Connect Timeout: How many seconds to wait for the SSH server to respond. The default is 30.
- Keep Alive Interval: How often, in seconds, to send a keep-alive request, so that the tunnel isn't closed when it is idle. The default is 0, which turns it off.
- Max Authentication Tries: The number of authentication attempts. The default is 6. Only used with JSch.
- Config File: An optional SSH config file. Only supported with JSch.
- Known Hosts File: The known hosts file, by default
~/.ssh/known_hosts. - Jump Server: See Jump server.
SSH config file
An SSH config file, typically ~/.ssh/config, holds SSH settings for each host. See OpenSSH/Client Configuration Files. To use one:
- Set SSH Implementation to JSch.
- Select Use Config File, and enter the file in Config File.
- In Host, enter the name of the Host entry in the file.
For example, for this file, enter arc in Host:
Host arc
Port 2022
HostName arc.example.org
User fred
IdentityFile ~/.ssh/id_rsa_arc
If an option is set both in the file and in DbVisualizer, the file is used, except for the user name: a Userid entered in DbVisualizer overrides User in the file. To see which options are used, click Test Connection.
Most OpenSSH options are supported, but some aren't, for example ProxyCommand. For the supported options, see OpenSSHConfig and Configuration Options in the JSch documentation.
Jump server
A jump server, also called a jump host or bastion host, is an SSH server that gives access to servers in a private network. With a jump server, DbVisualizer first connects to the jump server, and then through it to the SSH server. The two servers can use different authentication types. Both are connected using the SSH Implementation of the SSH configuration that uses the jump server.
A jump server is just another SSH configuration. Create and test it, and then select it as the Jump Server in the details of another SSH configuration. You can only use one jump server, so a configuration that is used as a jump server can't have a jump server itself.
Testing an SSH configuration
If you can't connect to a database through an SSH tunnel, the problem can be in the tunnel or in the database connection. To check the tunnel alone, click Test Connection in the SSH configuration. If the test succeeds, DbVisualizer can log in to the SSH server, so look for the problem in the database connection, or in whether the SSH server can reach the database.

Enabling SSH for a database connection
To use an SSH tunnel for a database connection, select Use SSH Tunnel in the Connection tab, and select an SSH configuration:

Use SSH Tunnel is only shown when Settings Format is Server Info, and only for databases that have a Database Server and a Database Port. For example, it isn't shown for embedded databases or for Oracle TNS connections.
To edit the SSH configuration, right-click the SSH Configuration field and select Open SSH Configurator:

To stop using an SSH tunnel, select the empty entry in the SSH Configuration list.
You can also see and set the SSH configuration of all connections in the list of connections. To open it, right-click in the Databases tab and select Show All Connections.

When you connect, you may be asked for the SSH password or passphrase, depending on the SSH configuration.
The database driver connects to a local port of the tunnel, which forwards the traffic to the database server. So the JDBC URL uses 127.0.0.1 and the local port instead of the database server and port, for example for Oracle:
jdbc:oracle:thin:@127.0.0.1:50538/XE
When you are connected, the URL is shown at the top of the Object View tab of the database connection, with a shield icon if the connection uses an SSH tunnel.

Common problems
"The authenticity of host 'x.x.x.x' can't be established"
This question is shown when you connect to an SSH server that isn't in the known hosts file.

If you recognize the host, click OK to add it to the Known Hosts File of the SSH configuration. You won't be asked again for that host. The text of the dialog depends on the SSH implementation.
"Algorithm negotiation fail"
This error means that DbVisualizer and the SSH server have no common algorithm for key exchange, host keys, ciphers or MACs, for example because the server only allows newer or older algorithms. Select the other SSH Implementation for the SSH configuration, since the two support different algorithms. Using JSch, you can also set the algorithms in an SSH config file, with the KexAlgorithms, HostKeyAlgorithms, Ciphers and MACs keywords.
"invalid privatekey: [B@........"
This error means that the private key file isn't in a format that is supported. A common cause is a key in the new OpenSSH format. To fix it, create the key in the PEM format, or convert the key, using the -m PEM option of ssh-keygen:
# Create a new key in the PEM format
ssh-keygen -t rsa -m PEM
# Convert an existing key to the PEM format
ssh-keygen -p -f ~/.ssh/id_rsa -m PEM
If the key was created in PuTTY (a .ppk file), convert it to an OpenSSH key in PuTTYgen:
- Make a backup of the private key file.
- In PuTTYgen, click Load, and open the
.ppkfile. - Select Conversions → Export OpenSSH key.
- Select a location and file name for the new key, and click Save.