home User Guide Getting Started Help Center Documentation Community Training Certification
menu
close
settings
Looker keyboard_arrow_down
language keyboard_arrow_down
English
Français
Deutsch
日本語
search
print
Using an SSH Tunnel

For the strongest encryption between Looker and your database, you can create a SSH tunnel to either a tunnel server, or the database server itself.

Step 1: Choose a Host on Which to Terminate the Tunnel

The first step to set up SSH tunnel access for your database is to choose the host that will be used to terminate the tunnel. The tunnel can be terminated on either the database host itself, or on a separate host (the tunnel server).

Using the Database Server

Terminating on the database has the advantage of simplicity. There is one less host involved, so there are no additonal machines and their associated costs. The disadvantage is that your database server may be on a protected network which does not have direct access from the Internet.

Using a Tunnel Server

Terminating the tunnel on a separate server has the advantage of keeping your database server inaccessible from the Internet. If the tunnel server is compromised it is one step removed from the database server. We recommend that you remove all non-essential software and users from the tunnel server and closely monitor it with tools such as an IDS.

The tunnel server can be any Unix/Linux host that:

  1. Can be accessed from the Internet via SSH
  2. Can access the database

Step 2: Create IP Whitelist

The second step is to allow network traffic to reach the tunnel server or database host via SSH, which is generally on TCP port 22.

Please allow network traffic from each of the IP addresses listed below for the region where your Looker instance is hosted. By default this will be the United States.

Legacy Hosting

Use these IP addresses for all instances hosted on AWS that were created before 07/07/2020.

Whitelist the IP addresses that match your region:

United States (AWS default)

Canada

Asia

Ireland

Germany

Australia

South America

Next Generation Hosting

Use these IP addresses for all instances hosted on Google Cloud Platform (GCP) and all instances hosted on Amazon Elastic Kubernetes Service (Amazon EKS) that were created on or after 07/07/2020.

Whitelist the IP addresses that match your region:

Instances Hosted on Google Cloud Platform (GCP)

Looker-hosted instances are hosted on GCP by default. For instances hosted on GCP, whitelist the IP addresses that match your region:

Moncks Corner, South Carolina, USA (us-east1)

Ashburn, Northern Virginia, USA (us-east4)

Council Bluffs, Iowa, USA (us-central1)

The Dalles, Oregon, USA (us-west1)

Montréal, Québec, Canada (northamerica-northeast1)

London, England, UK (europe-west2)

Frankfurt, Germany (europe-west3)

Tokyo, Japan (asia-northeast1)

Jurong West, Singapore (asia-southeast1)

Sydney, Australia (australia-southeast1)

Osasco (São Paulo), Brazil (southamerica-east1)

Instances Hosted on Amazon Elastic Kubernetes Service (Amazon EKS)

For instances hosted on Amazon EKS, whitelist the IP addresses that match your region:

US East (N. Virginia) (us-east-1)

Canada (Central) (ca-central-1)

Europe (Ireland) (eu-west-1)

Europe (Frankfurt) (eu-central-1)

Asia Pacific (Tokyo) (ap-northeast-1)

Asia Pacific (Sydney) (ap-southeast-2)

South America (São Paulo) (sa-east-1)

Step 3: SSH Tunneling

If you’re connecting Looker to your database without using an SSH tunnel, please proceed on to Database Configuration.

If you’re connecting with a tunnel server, which is the same as your database host, you should provide the following information to your Looker analyst:

If you’re connecting with a tunnel server, which is separate from your database host, you should provide the following information to your Looker analyst:

Step 4: Prepare the Tunnel Host

Your Looker analyst will provide you with a unique public key, which will be used to authenticate the SSH tunnel session (we do not support logins via password). You will need to prepare your host (either the database server or tunnel server) by creating a looker user and adding the Looker public key to the Looker .ssh/authorized_keys file. Here’s how:

  1. Create group looker:

    sudo groupadd looker

  2. Create user looker and its home directory:

    sudo useradd -m  -g looker  looker

  3. Switch to the looker user:

    sudo su - looker

  4. Create the .ssh directory:

    mkdir ~/.ssh

  5. Set permissions:

    chmod 700 ~/.ssh

  6. Change to the .ssh directory:

    cd ~/.ssh

  7. Create the authorized_keys file

    touch authorized_keys

  8. Set permissions:

    chmod 600 authorized_keys

Using your favorite text editor, add the SSH key provided by your Looker analyst to the authorized_keys file. The key must be all on one line. In some cases, when you retrieve the key from your email, line breaks will be inserted by your email client. If you do not remove them it will be impossible to establish the SSH tunnel.

Tunnel Security Notes

When an SSH tunnel is terminated on the database server, the connection from Looker appears to be a local connection on the database server. Therefore, it defeats the connection-based security mechanisms built into database platforms such as MySQL. For example, it is very common for local access to be granted to the root user with no password!

By default, opening SSH access also allows forwarding of any ports, circumventing any firewalls between Looker and the database host that is terminating the SSH tunnel. This security risk may well be deemed unacceptable. This port forwarding, and the ability to log in to your tunnel server, can be controlled by properly configuring the .ssh/authorized_keys entry for the Looker public key.

For example, the following text could be prepended to the Looker SSH key in your authorized_keys file. Please note that this text MUST be customized for your environment.

no-pty,no-X11-forwarding,permitopen="localhost:3306",permitopen="localhost:3307",
command="/bin/echo Login Not Permitted"

See the man ssh and man authorized_keys Linux documentation for examples and full details.

Next Steps

At this point, please notify your Looker analyst that you are ready to test the SSH tunnel. Once they confirm that the tunnel is established, they will provide you with the port number for the Looker side of the SSH tunnel.

On your database Connections page:

  1. Enter localhost in the Host field.
  2. In the Port field, enter the port number for the Looker side of the SSH tunnel that was provided by your Looker analyst.

  3. Toggle off Verify SSL Cert on your database Connections page.

    SSL Certificates are not supported when setting up an SSH tunnel to your database from Looker. Instead, the SSH key that you added in step 4 provides the handshake security between Looker and your database.

Top