Secure Connections to Pantheon Services via TLS or SSH Tunnels

This section provides information on how to use SSH tunnels to keep your sites secure.

Pantheon provides the ability to securely connect to your database and caching service over an encrypted connection using secure shell tunneling for additional security. This increases your remote connection security, especially in a public or untrusted environment.

This technique configures an SSH client to forward a local port to a port on Pantheon. You can connect to the local port to access the remote service using the encrypted connection after the SSH tunnel is established.

There are currently two services on Pantheon that support SSH tunneling:

• MySQL database (dbserver)

• Object Cache

You should consider Secure Runtime Access if you want to allow only SSH tunnels to access the dbserver.

Prerequisites

• Local installation of a MySQL client

• Redis command-line client

• Add an SSH key to your Pantheon Personal Settings.

Create Secure Connection to MySQL using TLS

Later versions of the MySQL client support the --ssl option. Using this command line option will encrypt your connection to the database server with TLS.

First, determine if your MySQL client supports TLS.

1. Run man mysql

2. Search for the --ssl option. If you add the --ssl option to your command there is no need to setup an SSH tunnel as described below.

Set up your SSH tunnel in Terminus:

1. Use the following Bash script to establish secure MySQL connections via TLS using the —ssl option and Terminus:

   sql-tls.sh

   terminus-sql-cli() {
     SITE=$1
     if [ x$SITE = x ]; then
       echo "USAGE:
   
   terminus-sql-cli site-shortname environment
   
   Open a mysql connection to a site.
   
     site-shortname: REQUIRED: If your site is dev-example.pantheon.io
                     this would be \"example\" .
   
     environment:    Defaults to \"dev\".
   "
       return
     fi
   
     ENV=$2
     if [ -z "$ENV" ]; then
       ENV="dev"
     fi
   
     if [ "$ENV" != "live" ]; then
       terminus env:wake $SITE.$ENV
     fi
   
     $(terminus connection:info $SITE.$ENV --fields=mysql_command --format=string) -A --ssl
   }
   alias tsqlc=terminus-sql-cli

Manually Create an SSH Tunnel to Connect to a MySQL Database

To manually create an SSH tunnel within your Pantheon Site Dashboard:

1. Go to the Site Dashboard and access the environment you want to connect with.

2. Click Connection Info. This will give you the required environment specific values for the command example below.

   

3. Use the required values from the Connection Info tab, the desired environment (Dev, Test, or Live), and the site uuid found in the Dashboard URL within the following command:

   ssh -f -N -L LOCAL_PORT:localhost:SERVER_PORT -p 2222 [email protected]_UUID.drush.in

   • Replace <LOCAL_PORT> with an available port on your device.

   • Replace <SERVER_PORT> with the designated port found on your Site Dashboard.

   • Often, the same input can be used for the <LOCAL_PORT> and <SERVER_PORT>.

   The command must include the port you are entering the tunnel from. You can replace <LOCAL_PORT> with the database port specified in the Connection Info tab. Do the same for <PASSWORD>

4. Run the following command:

   mysql -u pantheon -h 127.0.0.1 -P LOCAL_PORT pantheon -pPASSWORD

   Assuming the specified port is the <LOCAL_PORT>, you can determine if the port is listening by entering the following command:

   lsof -i :LOCAL_PORT

5. Run the following to test the connection to the database:

   echo 'SELECT 1' | mysql -u pantheon -pPASSWORD -h 127.0.0.1 -P LOCAL_PORT pantheon`

   • It should return the output 1.

   • A common output error if you use the wrong port resembles the following:

   ssh: Could not resolve hostname dbserver.<ENV>.<SITE_ID>: nodename nor servname provided, or not known
   zsh: command not found: 5Drush.in

You can destroy the tunnel by using the port value found within the Connection Info tab and your computer's <USERNAME> to run the following command:

ps -fU USERNAME | grep "ssh -f" | grep "PORT:" | awk '{print $2}' | xargs kill

Use Sequel Ace to SSH Tunnel to a MySQL Database

Sequel Ace (formerly Sequel Pro) is an open-source MySQL database client that supports SSH tunneling on Mac. You can configure other MySQL clients in a similar manner.

Manually Create an SSH Tunnel to a Redis Cache Server

1. Go to the Site Dashboard and select the environment you want to connect with.

2. Get the one-line connection string. It will be in the following format:

   redis-cli -h HOSTNAME -p PORT -a PASSWORD

3. Use the port value from the above one-line connection string, the desired environment (Dev, Test, or Live), and the site UUID found in the Dashboard URL within the following command:

   ssh -f -N -L PORT:localhost:PORT -p 2222 [email protected]_UUID.drush.in

4. Use the password and port found in the one-line connection string to run the command below. PORT is the database port specified in the Connection Info tab.

   redis-cli -h 127.0.0.1 -p PORT -a PASSWORD

You can destroy the tunnel by using the port value found within the Connection Info tab and your computer's username to run the following command:

ps -fU USERNAME | grep "ssh -f" | grep "PORT:" | awk '{print $2}' | xargs kill

Troubleshooting

To find solutions for MySQL connection errors, see Accessing MySQL Databases.

If port 2222 is blocked on your network you will see an error similar to the following:

SSH: connect to host codeserver.dev..drush.in port 2222: No route to host
Fatal: Could not read from remote repository.

Review Port 2222 Blocked Workaround for more information.

More Resources

• MySQL database (dbserver)

• Object Cache

• Secure Runtime Access