Using SSH

This section documents how to define, configure, and test SSH configurations. Starting with DbVisualizer 14.0, managing SSH configurations is done in Tool Properties. A single SSH configuration can be shared with multiple database connections making the administration a lot easier than (as previously) having multiple replicas of the same SSH configuration associated with different database connections.

When SSH tunneling is enabled, a tunnel is established when you connect to the database and the connection is then made through the secure tunnel.

Configuring SSH

To manage a SSH configuration, any of the following options many be used:

• Open Tools → Tool Properties and select General / SSH Configurations
• In the database Connection tab, select Use SSH Tunnel, click in the SSH Configuration drop-down and select Create/Edit SSH Configurations
• For a defined SSH configuration in the Connection tab, right-click it, and select Open SSH Configurator

The upper grid shows the SSH configurations where the Name column is either auto generated or manually set. Type is one of Password, Public Key or SSH Agent, and the last Used By column shows when clicked what database connections are using an SSH configuration.

Selecting an SSH configuration in the grid shows its details and the additional Options section that can be made visible or hidden. The following sections explains the different Authentication Types.

Authentication types

There are three different authentication types when establishing an SSH tunnel.

Password

Uses a userid/password combination to authenticate with the SSH server.

The Host is the name or IP address for the SSH host, or if using a SSH config file, the name of the host entry in the file. The target SSH host server is typically the same as the Database Server. Enter the port for SSH connections in the Port field. The default value is 22. If Password is not specified, you will be prompted for it when connecting to the server. To keep the password between sessions, select Save Between Sessions. You should also look into enabling a Master Password for strong security.

Public Key

Uses a public/private key pair (using either RSA or DSA algorithms) to authenticate with the server. Enter the Private Key File for the SSH configuration and upload the public key, typically the file with extension .pub in the <User home>/.ssh/authorized_keys file in the server account.

An optional passphrase may be set for the key. If passphrase is not set you can set that it should be prompted at connect with the Ask if Empty setting. To keep the passphrase between sessions, select Save Between Sessions. You should also look into enabling a Master Password for strong security.

SSH Agent

On macOS, Linux and other Unix based operating systems the SSH Agent authentication type is available. When this option is selected ssh-agent will be used for authentication, removing the need to provide a private key or password. In order to use ssh-agent for authentication, the identity used for authentication needs to be added to ssh-agent by running ssh-add in a terminal. Read more about setting up SSH Agent.

SSH Options

These are the generic SSH options independent of authentication type:

• Description use this to optionally describe the SSH configuration
• SSH Implementation chose from two different client-side toolkits; SSHJ or JSch. The most obvious difference is that SSHJ is faster and due to this it is also the recommended SSH Implementation. There might be differences in supported SSH algorithms and if any problems connecting with one of them, try the other one.
• Connect Timeout number of seconds to prevent endlessly waiting for an SSH host to respond
• Keep Alive Interval to minimize the risk that the tunnel is disconnected due to inactivity, specify number of seconds how often a keep-alive request should be made
• Max Authentication Tries the number of allowed connection attempts
• SSH Config File containing optional SSH configuration. Using config file is not supported with authentication type = SSH Agent
• SSH Known Hosts File identifies the known hosts file. The location of this file is typically <User home>/.ssh/config.
• Jump Server read more in the Jump Server section

SSH Config File

OpenSSH supports defining some parts of the SSH configuration in an SSH config file. This file is typically named <User home>/.ssh/config. To use a config file identify the file in the SSH Config File** field for the SSH configuration. Read more about OpenSSH/Client Configuration Files.

Here is a sample of the config file:

Host arc
        Port 2022
        HostName arc.example.org
        User fred
        IdentityFile ~/.ssh/id_rsa_arc

When using a config file, the Host field in DbVisualizer should refer the Host <host> defined in the config file. Having options in the config file that are already in the SSH configuration setup in DbVisualizer, then the config file options will be used except for Userid which when set in DbVisualizer will override any User option set in the config file. To see what actual options are used, run Test Connection.

Jump Server

Jump Server (also known as Jump Host, Remote Host or Bastion Host) is a gateway server that gives access to instances within a private network using the SSH protocol. You can log into the instances of your private network via a single, centralized, entry point. The following image illustrates that with a Jump Server set it is invoked as the first server from DbVisualizer and then a connection with the target SSH Server is established. The jump server and the target SSH server may use different authentication types and implementation types.

A jump server is just another SSH server configuration in DbVisualizer. Create, test it, and then use it as a jump server for one of the other defined SSH servers.

Testing an SSH configuration

Using an SSH configuration when connecting to a data source and there are connection issues, it might be difficult to distinguish if the problem is related to establishing the SSH tunnel or if it is a problem getting connected with the target database. Testing just the SSH tunnel is really useful and the Test Connection is handy. Once you get the tunnel working and later experience connection problems with the target database, those kinds of connection problems are related with the database only.

Click the Test Connection button to verify that you are able to connect and to detect any problems.

Enabling SSH for a database connection

To use a SSH tunnel for a database connection, click Use SSH Tunnel and select a SSH configuration in the dropdown:

To edit an SSH configuration that is associated with a database connection, right-click the SSH configuration field and select Open SSH Configurator:

Another option to browse and set the SSH configuration is to open the Connections Tab from the right-click menu in the Databases tab to list all database connections.

To clear out the use of an SSH configuration, just choose the first empty entry in the drop-down listing all SSH configurations.

When connecting to the database, you might be prompted for SSH password or passphrase depending on the settings for the SSH configuration.

The JDBC URL is constructed using 127.0.0.1 as the Database Server portion and <LocalPort> as the Database Port portion, e.g. like this for the Oracle Thin driver when <LocalPort> is 50538:

jdbc:oracle:thin@127.0.0.1:50538/XE

In other words, the JDBC driver connects to the SSH tunnel's local port, which then forwards all communication to the database server.

The URL that is used for the connection is shown at the top of the Object View tab for the database connection when a connection is established, along with a certificate icon if the connection is made through an SSH tunnel.

Common problems

Establishing an SSH tunnel may result in various errors and problems due to algorithms, key lengths, and much more. Here we list a few of them and possible solutions.

The authenticity of host 'x.x.x.x' can't be established

This question is displayed when connecting to notify that the host is not currently a known host.

If you recognize the host as a "good" host - click Yes to add it to the Known Hosts File for the SSH configuration. Accepting (i.e. click Yes) not known hosts will then be collected in the file and there will be no future prompts for the host. Note: The dialog text may differ slightly depending on SSH Implementation.

"invalid privatekey: [B@........"

This error is reported when using a private key file that is not in a valid format. If you are sure it is a valid private key this error may also occur when using keys that are in the "new OpenSSH" format rather than classic. One potential fix on the OpenSSH problem is to ensure you generate the keys with the -t PEM option to ssh-keygen. The following example shows the command used to create new keys and the other how to convert existing keys.

# Create new keys with the -m PEM option
ssh-keygen -t rsa -m PEM

# Converting existing keys with -m PEM option
ssh-keygen -p -f /home/me/.ssh/id_rsa -m PEM

Another possible solution if your private key is generated by PuTTY (file extension .ppk) is to convert the key from a PuTTY private key to an ssh private key. This can be done in PuTTYGen as follows:

1. Create a backup of your private key file.
2. In PuTTYGen's main interface, click the Load button.
3. Select your private key (.ppk) file and click Open.
4. Go to Conversions->Export OpenSSH key.
5. Select location and file name for your new key and click Save.