How to set up an SSH tunnel on Mac and Linux

This article describes how to create an SSH Tunnel from your development machine to a server, on a Mac or Linux system. If you are using Windows, please use PuTTY.

Use the official OpenSSH `ssh` client to follow these instructions. Other tools may also work, but we can't guarantee they will work the same way.

For the Postgres example, the database could be listening on the private ip instead of localhost. You will need to replace localhost with the private ip in all the steps and examples.

Why use an SSH tunnel?

You may want to access your database remotely from your development machine. MedStack's security policy specifies that only a small set of ports may be open to the public internet. Normally this is HTTP (port 80), HTTPS (port 443) and SSH (port 22). Despite this restriction,  A good way to do this is to use an  SSH tunnel.

An SSH tunnel uses your existing ability to SSH into the server and adds a "tunnel" that forwards a port on your dev machine to a port on the remote server. You specify a port on your dev machine, and then for the remote server, you specify a host (usually localhost) and a port. For example, if you wanted to access PostgreSQL on the server, you could forward 5432 on you dev machine to localhost:5432 on the server.

Configure your SSH

You can configure SSH two ways: with a config file, or with command-line options. We prefer using the config file because it is simpler to set up.

SSH config with the config file

You should already have an  SSH config file that we provided you. If you haven't, follow the instruction in Connecting via SSH and then continue with these instructions. This file allows you to configure SSH connections using a simple syntax. (All of the options we will use are also available on the SSH command line if you prefer.)

Inside the `Host` block, you will already have something like this:

     User deploy
     IdentityFile ~/.ssh/

You will now add an additional LocalForward statement:

    User deploy
    IdentityFile ~/.ssh/
    LocalForward 5432 localhost:5432

The last line in this example with forward port 5432 (PosgreSQL) on your dev machine to port 5432 on the remote server ( localhost refers to the remote server, not your dev machine). To keep things simple, use the same port number on both sides.

Example of SSH config with the command line

This tutorial will use the config file. But, just for your information the same example as above can be done with the command line like this:

ssh -i ~/.ssh/ \
    -L 5432:localhost:5432 \

Some common ports:

You can substitute these ports to connect to various services:

  • PostgreSQL: 5432
  • MySQL: 3306
  • MongoDB: 27017
  • Redis: 6379

Connect and create the tunnel

Now that you have configured SSH, you can connect:

$ ssh

You will now have a command line on the server, and in addition, the tunnel is open.

Use the tunnel

You can now connect to the database on your server using your favourite client.

  • NOTE: You must connect to localhost, and never to If you connect to you will not be using the tunnel. Use the port number (e.g. 5432) you have forwarded above.

Postgres example

For example you could open psql as follows:

user@system:~$ psql -U example_admin postgres -h localhost -p 5432
Password for user example_admin: 
psql (9.6.3, server 9.5.8)
Type "help" for help.


You can also use GUI clients. For example, if you are using a pgAdmin:

Web clients

You can forward any port. For example, if you need to access an administrative web interface that your app provides on port 8080, you can open  http://localhost:8080 in your browser.

Multiple forwards

OpenSSH supports any number of forwards simultaneously. Simply include several LocalForward lines in your SSH configuration file.

Security notes

  • Encryption is provided by SSH, so additional encryption is not required.
  • Forwarding HTTPS will result in a certificate error, since `localhost` will not match the certificate's server name.
  • Ensure that you are running a firewall on your local PC so that the port is not accessible to others on your LAN.
  • For additional security, comment out the LocalForward line in your SSH config except when you need to use it.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Submit a request for support Submit a request for support