SSH Tunnels

Some databases must be accessed through an SSH tunnel, where the SSH protocol is used to forward your connection into a private network. You connect your local computer first to an SSH server (sometimes known as a bastion host), and then connect Ultorg to your database through the SSH client on your own machine.

Connecting Through a Tunnel

To connect Ultorg to a database using an SSH tunnel:

  1. Open a terminal that has the ssh command available. On Linux or MacOS, this is the regular Terminal app. On Windows, you can open either the Command Prompt or WSL.
  2. Now figure out the ssh command that is needed to connect to and authenticate with the SSH server, and verify that it works.

    For example: 

      ssh myusername@my-ssh-server.com
  3. Now modify the ssh command to enable forwarding of network traffic.

    Two network port numbers are involved: the port number of your database on the database server (e.g. 5432 for PostgreSQL or 3306 for MySQL), and an arbitrary port number that we use internally on your local machine. For the latter, any number between 49152 to 65535 will work; we will use 55555 in this example.

    At the end of the SSH command, add the following: 

    -L <local-port-number>:<database-host-name-or-ip-address>:<database-port-number>

    So, for instance, if you are connecting to a PostgreSQL server on port 5432 with host name my-database-server on your internal network, via the SSH server my-ssh-server.com on the public Internet, the command might be as follows: 

    ssh myusername@my-ssh-server.com -L 55555:my-database-server:5432

    In many cases the database server will be specified as an IP address.

    If SSH logs in successfully while the -L parameter is specified as above, then port forwarding is working. Keep the SSH command running while proceeding to the next step.

  4. In Ultorg, click Add Data Source→Connect to Database.
  5. In the Driver dropdown, select the database type, and click Next.
  6. Now fill in your connection details per the usual instructions for your database (PostgreSQL, MySQL, Microsoft SQL Server). But:
    • For the Host field, enter localhost
    • For the Port field, enter 55555, or whichever local port number you picked for your SSH tunnel in step 3.
  7. Click Test Connection to verify your settings, and Finish to start using your database from Ultorg.
  8. To exit the SSH command, you may need to first right-click the data source (Data Source icon) in Ultorg and click Disconnect. Then you can press Ctrl+C in the Terminal to terminate SSH.

On Windows, the PuTTY tool can be used as a graphical alternative to the ssh command.

(In the future, Ultorg may incorporate SSH tunnel configuration directly in the connection wizard. This will eliminate the need for an external application.)