Connecting to Linux Instances

This guide shows you how to connect to Linux instances using common SSH tools on Linux, OSX, and Windows workstations. If you need to connect to a Windows instance, connect using RDP instead.

The easiest way to connect to a Linux instance on Compute Engine is to connect from your browser or connect using the gcloud tool.

Alternatively, you can generate a new key-pair and apply it to your project, which allows you to connect using third-party tools. For example, you can connect using SSH on Linux or OSX workstations or connect using PuTTY on Windows workstations

If you are an advanced user who needs to automate SSH key management or set public SSH keys only on specific instances, see Automating SSH Key Management.

Before you begin

Connecting to an instance from your browser

To SSH directly from your web browser in the Google Cloud Platform Console:

  1. In the Cloud Platform Console, go to the VM Instances page.

    Go to the VM Instances page

  2. In the list of virtual machine instances, click the SSH button in the row of the instance to which you want to connect.

Connecting to instances through the browser has some caveats. For more information, see SSH from the Browser.

Connecting to an instance through gcloud

You can use the gcloud command-line tool to easily connect to your Linux instances. The gcloud tool manages your SSH keys for you by generating and applying new project-wide SSH keys when you need them.

To connect to your instance, use the gcloud compute ssh command:

gcloud compute ssh [INSTANCE_NAME]

where [INSTANCE_NAME] is the name of the instance.

You can now use the terminal to run commands on your Linux instance. When you are done, use the exit command to disconnect from the instance.

Generating a new SSH key-pair

Before you can access your instances using SSH or SCP, you must generate a new SSH key-pair and apply the public key to your project. If you have already connected to an instance through the gcloud tool, your keys are already applied to your project and available in the following locations:

  • Linux and OSX
    • Public key: $HOME/.ssh/google_compute_engine.pub
    • Private key: $HOME/.ssh/google_compute_engine
  • Windows:
    • Public key: C:\Users\[USER_NAME]\.ssh\google_compute_engine.pub
    • Private key: C:\Users\[USER_NAME]\.ssh\google_compute_engine

where: [USER_NAME] is your user name on your local workstation.

Alternatively, you can generate your own key-pairs manually:

Linux and OSX


To generate a new SSH key-pair on Linux or OSX workstations:

  1. Open a terminal on your workstation and use the ssh-keygen command to generate a new key-pair. Specify the -C flag to add a comment with your Google username. The example creates a private key named my-ssh-key, and a public key file named my-ssh-key.pub.

    ssh-keygen -t rsa -f ~/.ssh/my-ssh-key -C [USERNAME]
    

    where [USERNAME] is the user on the instance for whom you will apply the key. If the user does not exist on the instance, Compute Engine automatically creates it using the username that you specify in this command.

  2. Restrict access to your my-ssh-key private key so that only you can read it and nobody can write to it.

    chmod 400 ~/.ssh/my-ssh-key
    
  3. Go to the metadata page for your project.

    Go to the Metadata page

  4. Click SSH Keys to show a list of project-wide public SSH keys.

  5. Click the Edit button so that you can modify the public SSH keys in your project.

  6. Obtain the contents of the ~/.ssh/my-ssh-key.pub public key file with the cat command.

    cat ~/.ssh/my-ssh-key.pub
    

    The terminal shows your public key in the following form:

    ssh-rsa [KEY_VALUE] [USERNAME]
    

    where:

    • [KEY_VALUE] is the generated public key value.
    • [USERNAME] is your username.
  7. Copy the output from the cat command and paste it as a new item in the list of SSH keys.

  8. At the bottom of the SSH Keys page, click Save to save your new project-wide SSH key.

The public key is now set to work across all of the instances in your project. Use the ssh command to connect to your instances.

Windows


To generate a new SSH key-pair on Windows workstations:

  1. Download puttygen.exe.

  2. Run PuTTYgen. For this example, simply run the puttygen.exe file that you downloaded. A window opens where you can configure your key generation settings.

  3. Click the Generate button to generate a new key-pair. For most cases, the default parameters are fine. When you are done generating the key-pair, the tool displays your public key value.

  4. In the Key comment section, enter your Google username. The key should have the following structure:

    ssh-rsa [KEY_VALUE] [USERNAME]
    

    where:

    • [KEY_VALUE] is the key value that you generated.
    • [USERNAME] is your Google username.
  5. Optionally, enter a Key passphrase to protect your key.

  6. Click Save private key to save the private key to a file. For this example, save the key as my-ssh-key.ppk.

  7. Click Save public key to write your public key to a file for use later. Keep the PuTTYgen window open for now.

  8. Go to the metadata page for your project.

    Go to the Metadata page

  9. Click SSH Keys to show a list of project-wide public SSH keys.

  10. Click the Edit button so that you can modify the public SSH keys in your project.

  11. Copy the entire public key value from the PuTTYgen tool and paste that value as a new item in the list of SSH keys on the Metadata page. The public key value is available at the top of the PuTTYgen screen:

    Screenshot of PuTTYgen public key

  12. At the bottom of the SSH Keys page, click Save to save your new project-wide SSH key.

The public key is now set to work across all of the instances in your project. Use PuTTY to connect to your instances.

Connecting using SSH on Linux or OSX workstations

To connect to your instances using SSH:

  1. If you have not yet applied a public key to your Cloud Platform Console project, generate a new key-pair and apply it to your project.

  2. In the console, find the external IP for the instance that you want to connect to. Go to the list of your instances.

    Go to the Instances page

  3. Use the ssh command to connect to your instance. Specify your username and the external IP address for the instance that you want to connect to. Your username is the Google username that you use to access your project. For this example, the private key is at ~/.ssh/my-ssh-key.

    ssh -i ~/.ssh/my-ssh-key [USERNAME]@[IP_ADDRESS]
    

    where:

    • [USERNAME] is your username
    • [IP_ADDRESS] is the IP for your instance.

If the connection is successful, you can use the terminal to run commands on your instance. When you are done, use the exit command to disconnect from the instance.

Connecting using PuTTY on Windows workstations

On Windows workstations, you can use the PuTTY tool to connect to your instances. To connect to your instance using PuTTY:

  1. If you have not yet applied a public key to your Cloud Platform Console project, generate a new key-pair and apply it to your project.

  2. Download putty.exe.

  3. Run the PuTTY tool. For this example, simply run the putty.exe file that you downloaded. A window opens where you can configure your connection settings.

  4. In the Google Cloud Platform Console, find the external IP for the instance that you want to connect to. Go to the list of your instances.

    Go to the Instances page

  5. In the PuTTY tool, specify your Google username and the external IP address for the instance that you want to connect to in the Host Name field. Your username is the Google username that you use to access your project. For this example, the user is example-user and the external IP address is 104.196.31.103.

    Setting the Host Name field with example-user@104.196.31.103

  6. On the left side of the PuTTY window, navigate to Connection > SSH > Auth.

  7. Set the Private key file for authentication field with the path to your private key file. For this example, specify the path to the my-ssh-key.ppk file.

    Setting the path to the my-ssh-key.ppk file in the private key file field.

  8. Click Open to open a terminal with a connection to your instance.

If the connection is successful, you can use the terminal to run commands on your instance. When you are done, use the exit command to disconnect from the instance.

Connecting to instances that do not have external IP addresses

If you connect to an instance that has an external IP address, you can chain-connect from that instance to any instance on the same network using the internal IP address. You can connect to an instance even if it does not have an external IP address.

This process has the following requirements:

  • Two instances on the same network. One instance with an external IP and another instance without an external IP address.
  • A firewall rule that allows SSH connections on port 22. The firewall rule is a default rule on the default network. Both instances must be part of this network.

To connect to an instance without an external IP address:

  1. If you have not yet applied a public key to your Cloud Platform Console project, generate a new key-pair and apply it to your project.

  2. On your local machine, start the ssh-agent to manage your keys for you:

    eval `ssh-agent`
    
  3. Use the ssh-add command to load your public keys from your local computer into the agent, and use them for all SSH commands for authentication.

    ssh-add ~/.ssh/[PRIVATE_KEY]
    

    where [PRIVATE_KEY] is the file name of your private key file.

  4. Connect an instance with an external IP address and include the -A argument to enable authentication agent forwarding.

    gcloud compute ssh --ssh-flag="-A" [EXTERNAL_INSTANCE_NAME]
    

    where [EXTERNAL_INSTANCE_NAME] is the name of the instance that has an external IP address.

  5. After you connect to the externally-addressable instance, use ssh to connect to any other instance on the same network.

    $ ssh [INTERNAL_INSTANCE_NAME]
    

    where: [INTERNAL_INSTANCE_NAME] is the name of the second instance that you need to connect to.

  6. When you are done, use the exit command to disconnect from each instance one at a time.

    $ exit
    

Connecting to instances as the root user

By default, public images and most common operating systems do not allow root login over SSH. As a best practice, the /etc/ssh/sshd_config SSH configuration file has the PermitRootLogin parameter set to no.

Because of this parameter, you cannot connect to instances as the root user even if you specify an SSH key for root in your project or instance metadata. If a user requires root permissions, they can get those permissions by running commands through sudo.

What's next

Send feedback about...

Compute Engine Documentation