Connecting to VMs using advanced methods

Linux VMs

---

In general, the best SSH connection methods are described in the Connecting to instances document. However, when you need to manage your own credentials, use third-party tools, or connect using alternative connection paths, the following advanced methods might fit your needs better than the standard methods.

There are several advanced methods that you can use to connect to Linux VMs:

• Connect to instances using third-party tools
• Connect to instances that do not have external IP addresses
• Connect to instances as the root user
• SSH with security keys

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• For information about how SSH connections work in Compute Engine, including SSH key configuration and storage, see SSH connections to Linux VMs.

Providing public SSH keys to instances

Normally, Compute Engine creates and manages SSH keys for you whenever you connect using the methods described in Connecting to instances.

However, if you need to use your own SSH keys (for example, when using third-party tools to connect), you must generate your own SSH key pair and provide your public SSH key file to the instance before you can connect.

If you are not familiar with how to generate your own SSH key and how to locate your public SSH key file, see Creating a new SSH key and Locating an SSH key.

To provide your SSH key to the instance, use one of the following methods:

• (Recommended) Enable OS Login. OS Login uses IAM roles to provide your public SSH key to the instance through your Google Account or a managed user account. For instructions, see Setting up OS Login.

  When setting up OS Login, ensure that you complete the step to add SSH keys to a user account. In this step you can add your public key to the user account that you want to use to connect to your VM.

  To learn more about the benefits of using this feature, see OS Login.

• (Not recommended) Manually add and remove SSH keys by editing project or instance metadata. See Managing SSH keys in metadata. This method adds unnecessary risks and complexity and is not recommended unless the OS Login method above does not work for you. See Risks of manual key management.

• If your instance is managed by someone else who already has access (such as a Systems Administrator in your organization), you can also provide your public SSH key file to them and ask them to manually configure it for you. Usually this involves them connecting to your instance, copying your public key file into your home directory on your instance, and changing the permissions on the file, but this depends on how your organization manages your instances.

Connecting using third-party tools

To connect, follow the steps for the operating system on your local workstation:

Linux and macOS

To connect using SSH from a Linux or macOS machine, use the built-in ssh command in a local terminal:

1. If you have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. In the Google Cloud Console, go to the VM Instances page and find the external IP address for the instance that you want to connect to.

   Go to VM Instances

3. In a local terminal, use the ssh command along with your private SSH key file, the username, and the external IP address of the instance to connect. For example:

   ssh -i PATH_TO_PRIVATE_KEY USERNAME@EXTERNAL_IP

   Replace the following:

   • PATH_TO_PRIVATE_KEY: the path to your private SSH key file.
   • USERNAME: the username of the user connecting to the instance. If you manage your SSH keys in metadata, the username is what you specified when you created the SSH key. For OS Login accounts, the username is defined in your Google profile.
   • EXTERNAL_IP: The external IP address for your instance.

   After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Windows (PuTTY)

Windows does not include a built-in SSH client, which means you must download and install a third-party client. The following instructions show how to connect using PuTTY.

To connect to an instance from Windows using PuTTY, do the following:

1. If you have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. In the Google Cloud Console, go to the VM Instances page and find the external IP address for the instance that you want to connect to. Keep the external IP address available for later steps.

   Go to VM Instances

3. Download putty.exe, if you have not done so already.

4. Open PuTTY by launching putty.exe. A connection configuration window opens.

5. In the Host Name field, enter the username associated with the SSH key, and the external IP address of the instance that you want to connect to. Use the following format:

   USERNAME@EXTERNAL_IP

   Replace the following:

   • USERNAME: the username of the user connecting to the instance. This must be the username you specified when you created the SSH key.
   • EXTERNAL_IP: the external IP address of the instance that you want to connect to.

   For example, see the following screenshot:

   

6. In the Category menu, navigate to Connection > SSH > Auth.

7. In the Private key file for authentication field, browse to the location of your private key file.

   For example, see the following screenshot:

   

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

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Chrome OS (SSH app)

Chromebooks or operating systems with Chrome installed support Secure Shell as an SSH client. To connect to instances from the Secure Shell app, do the following:

1. If you have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. Install Secure Shell on your Chromebook or the Chrome browser if you have not done so already.

3. In the Google Cloud Console, go to the VM Instances page and find the external IP address for the instance that you want to connect to. Keep the external IP address available for later steps.

   Go to VM Instances

4. Open the Secure Shell app in a Chrome browser tab. You can access Chrome apps by typing chrome://apps in the address bar.

5. Enter the username associated with the SSH key pair and the external IP address for the instance that you want to connect to. Use the following format:

    USERNAME@EXTERNAL_IP
    

   Replace the following:

   • USERNAME: the username of the user who is connecting to the instance. This must be the username you specified when you created the SSH key.
   • EXTERNAL_IP: the external IP address of the instance that you want to connect to.

6. In the Identity field, select the private SSH key file that you want to use to connect to the instance. If necessary, click Import to select a private key file from your local workstation.

7. Click Connect to connect to the instance.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Other SSH options

In addition to the options detailed above, other options for connecting to an instance using SSH include:

• SSH from the browser.
• gcloud compute ssh command. See the gcloud compute ssh reference documentation.

Connecting to instances that do not have external IP addresses

If you have isolated instances that do not have an external IP address, you can still connect to those instances by using their internal IP addresses on a Google Cloud VPC network. For example, you can still connect to VMs that you intentionally isolate from external networks by using the following methods:

• Connect to instances over a VPN connection that has access to the internal IP addresses of instances on your Google Cloud VPC.
• Connect through a bastion host instance to gain access to the internal IP address on your Google Cloud VPC. Then, connect from the bastion host to other instances on the same internal VPC network or instances on a peered VPC network.
• Connect using Identity-Aware Proxy for TCP forwarding to forward an SSH connection to a remote instance.

Important: For these methods to work, your VPC network must have one or more firewall rules that allow SSH connections on port 22. The firewall rules must allow SSH connections for the IP ranges or specific IP addresses from which you want to connect.

Connecting over a VPN connection

To use a Virtual Private Network (VPN) to connect to an instance without an external IP address:

• You must use a computer that can reach the VM instance over a Cloud VPN tunnel.

  For example, you might have a VPN that your local on-premises network shares with your Google Cloud VPC. In that situation, connect to the instance using the gcloud command-line tool, SSH on Linux or macOS, or third-party SSH clients such as PuTTY on Windows.

See the following tabs for details:

gcloud

To connect to an instance without an external IP address, use the gcloud compute ssh command with the --internal-ip flag.

1. In the Google Cloud Console, go to the VM Instances page and find the internal IP address for the instance that you want to connect to.

   Go to VM Instances

2. Connect to the instance.

   gcloud compute ssh INTERNAL_INSTANCE_NAME \
       --zone=ZONE \
       --internal-ip
   

   Replace the following:

   • INTERNAL_INSTANCE_NAME: the name of the instance that you want to connect to
   • ZONE: the name of the zone in which the instance is located

3. After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Linux and macOS

To connect to an instance without an external IP address from Linux or macOS workstations, do the following:

1. Provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

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

   eval ssh-agent $SHELL
   

3. Use the ssh-add command to load your private SSH key from your local computer into the agent and use your private SSH key for authentication of all SSH commands. Replace PRIVATE_KEY with the filename of your private key file.

   ssh-add ~/.ssh/PRIVATE_KEY
   

4. In the Google Cloud Console, go to the VM Instances page and find the internal IP address for the instance that you want to connect to.

   Go to VM Instances

5. In a local terminal, use the ssh command along with the username associated with your private SSH key and the internal IP address of the instance to connect to. For example:

   ssh USERNAME@INTERNAL_INSTANCE_IP_ADDRESS

   Replace the following:

   • USERNAME: the username of the user who is connecting to the instance. This must be the username you specified when you created the SSH key.
   • INTERNAL_INSTANCE_IP_ADDRESS: the internal IP address of the instance that you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Windows (PuTTY)

To connect to an instance without an external IP address from Windows workstations:

1. If you have not done so already, provide your public SSH key to an instance using one of the available options. You cannot proceed without this.

2. In the Google Cloud Console, go to the VM Instances page and find the internal IP address for the instance that you want to connect to.

   Go to VM Instances

3. Follow the preceding steps to connect to an instance using PuTTY from Windows, but make the following change:

   • Where the steps instruct you to specify an external IP address, instead specify the internal address of the instance you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Connecting through a bastion host

Another method of connecting to an instance that does not have an external IP address is to connect through a bastion host. Using a bastion host also lets you connect to instances on other peered VPC networks.

To connect to an instance through a bastion host from Linux and macOS, use either the gcloud command-line tool or SSH. To connect from Windows, use a third-party SSH client such as PuTTY.

Connecting to other instances from a bastion host requires a private SSH key. There are several ways to manage this:

• Install the gcloud command-line tool and configure it to manage your private keys for you.
• Forward your private key to the bastion host instance by enabling agent forwarding in your ssh client.

Note: The following are examples of a bastion host on a Linux operating system. If you want to follow along, confirm that the bastion host you are using is running Linux.

See the following examples for complete steps:

gcloud

Beta — SSH to internal IP addresses using the gcloud command-line tool

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

The gcloud command-line tool lets you connect to instances that don't have external IP addresses without forwarding your private SSH keys to the bastion host. To do this, install gcloud on both your local workstation and the bastion host instance, if you have not done so already.

Note: If you have circumstances that require forwarding your private keys instead of allowing the gcloud tool to manage them for you, see the Linux or macOS and Windows tabs and look for the steps about using ssh-agent to forward your key. After you use ssh-agent to forward your key, return to this procedure and use gcloud compute ssh to connect.

To use the gcloud command-line tool to connect to an instance that does not have an external IP address:

1. Set a read/write Compute Engine API access scope for the service account on your bastion host instance by including --scopes compute-rw in your command. For more information, see Changing the service account and access scopes for an instance.

2. Grant the necessary IAM permissions to allow your bastion host to access your public SSH key by either using OS Login (recommended) or project metadata. Use one of the following procedures:

   • OS Login (recommended):

     1. Enable OS Login.

     2. Grant the necessary IAM permissions to access your instances with OS Login.

   • Project metadata:

     1. Grant the necessary IAM permissions for your instances to edit metadata.

        (Tip: you can add the Compute Engine Instance Admin role to your service account.)

   The service account on your bastion host can now apply your public SSH key.

3. Connect to the Linux bastion host instance. Replace EXTERNAL_INSTANCE_NAME with the name of the bastion host instance that you're using to gain access to the internal network.

   gcloud compute ssh EXTERNAL_INSTANCE_NAME
   

4. From the Linux bastion host instance, use the gcloud compute ssh command with the --internal-ip flag to connect to instances using their internal IP addresses.

   gcloud compute ssh INTERNAL_INSTANCE_NAME --internal-ip
   

   Replace INTERNAL_INSTANCE_NAME with the name of the instance that you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Linux and macOS

If you need to forward private keys to the bastion host instance, you must add your keys to the ssh-agent. Then, use either the gcloud compute ssh command or the ssh command to establish the initial connection to the bastion host and forward the keys in the SSH agent. This process works only on Linux and macOS workstations. If you need to forward private keys to a bastion host from a Windows workstation, follow the PuTTY instructions instead.

To connect to an instance without an external IP address from Linux or macOS workstations:

1. Provide your public SSH key using one of the available options. Make sure you provide this public SSH key to both the Linux bastion host instance and the instance without an external IP address.

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

   eval ssh-agent $SHELL
   

3. Use the ssh-add command to load your private SSH key from your local computer into the agent. Once added, SSH commands automatically use the private SSH key file for authentication.

   $ ssh-add ~/.ssh/PRIVATE_KEY
   

   Replace PRIVATE_KEY with the name of your private key file.

4. In the Google Cloud Console, go to the VM Instances page. In the External IP column, find the external IP address of the Linux bastion host instance. And in the Internal IP column, find the internal IP address of the internal instance that you want to connect to.

   Go to VM Instances

5. Connect to the Linux bastion host instance using either ssh or gcloud compute ssh. For either option, include the -A argument to enable authentication agent forwarding.

   Connect to the Linux bastion host instance and forward your private keys with ssh:

   ssh -A USERNAME@BASTION_HOST_EXTERNAL_IP

   Replace the following:

   • USERNAME: the name attached to your SSH key.
   • BASTION_HOST_EXTERNAL_IP: the external IP address of the bastion host instance that you're using to gain access to the internal network.

   Alternatively, you can connect to the bastion host instance and forward your private keys using the gcloud compute ssh command. This option lets you connect to the bastion host instance using the gcloud command-line tool, and then use regular ssh with the forwarded credentials when you connect to internal IP addresses.

   gcloud compute ssh --ssh-flag="-A" BASTION_HOST_INSTANCE_NAME
   

   Replace BASTION_HOST_INSTANCE_NAME with the name of the bastion host instance that you're using to gain access to your internal network.

6. From the Linux bastion host instance, use SSH to connect to the instance that doesn't have an external IP address:

   ssh USERNAME@INTERNAL_INSTANCE_IP_ADDRESS

   Replace the following:

   • USERNAME: the name attached to your SSH key.
   • INTERNAL_INSTANCE_IP_ADDRESS: the internal IP address of the instance that you want to connect to.

After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Windows

To connect to an instance without an external IP address from Windows workstations:

1. Provide your public SSH key using one of the available options. Make sure you provide this public SSH key to both the Linux bastion host instance and the instance without an external IP address.

2. In the Google Cloud Console, go to the VM Instances page. In the External IP column, find the external IP address of the Linux bastion host instance. And in the Internal IP column, find the internal IP address of the internal instance that you want to connect to.

   Go to VM Instances

3. Connect to the Linux bastion host instance by using PuTTY. To pass your private SSH key to the bastion host, enable the Allow agent forwarding setting, as shown in the following screenshot:

   

4. From the Linux bastion host instance, use SSH to connect to the instance that doesn't have an external IP address:

   ssh USERNAME@INTERNAL_IP_ADDRESS
   

   Replace the following:

   • USERNAME: the username of the user connecting to the instance. This must be the username you specified when you created the SSH key.
   • INTERNAL_IP_ADDRESS: the internal IP address of the instance that you want to connect to.

   After you connect, run commands on your instance using this terminal. When you finish, disconnect from the instance by running the exit command.

Connecting through IAP

Using SSH with IAP's TCP forwarding feature wraps an SSH connection inside HTTPS. IAP's TCP forwarding feature then sends the URL to the remote instance.

1. Grant the roles/iap.tunnelResourceAccessor role to the user that wants to connect to the VM.

2. Connect to the VM.

   gcloud compute ssh INSTANCE_NAME --zone ZONE
   

   Replace the following:

   • INSTANCE_NAME: the name of the instance that you want to connect to.
   • ZONE: the name of the zone in which the instance is located.

For more information, including how to configure context-aware rules and access other TCP ports on the VM, see Using TCP forwarding.

Connecting to instances as the root user

By default, public images and most common operating systems do not allow root login using SSH. Instances let you connect as root using SSH only if you configure them to operate that way yourself.

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 an instance 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.

If you configured an instance to allow SSH as the root user and configure an SSH key for the root user on that instance, you can connect as root using the gcloud compute ssh command with root@ specified before the instance name:

gcloud compute ssh \
    --project=PROJECT_ID \
    --zone=ZONE \
    root@INSTANCE_NAME

Replace the following:

• PROJECT_ID: the ID of the project that contains the instance
• ZONE: the name of the zone in which the instance is located
• INSTANCE_NAME: the name of the instance

Manually connecting between instances as a service account

In some situations, you might want to connect to instances and run commands as if you were the service account associated with that instance. The gcloud compute ssh command lets you use the SSH credentials of a service account to connect from one instance to another, letting you run commands on the second instance as the service account.

The gcloud command-line tool automatically generates an SSH key pair and associates it with the service account on your instance. After you connect to another instance as the service account, you can run additional gcloud commands using the service account's IAM permissions.

For this example, assume that you have the following environment:

• Instance A:
  • Instance A has a service account associated with it.
  • The service account associated with Instance A has the necessary OS Login roles configured either at the project level or specifically for the Instance B resource.
  • The service account has the https://www.googleapis.com/auth/cloud-platform platform-wide scope on Instance A.
• Instance B:
  • Instance B runs either on the same internal network as Instance A or on a network with firewall rules that allow SSH connections from Instance A.
  • The OS Login feature is enabled on your project or specifically on Instance B.
• Your personal user account:
  • Your account has the roles/iam.serviceAccountUser role for the service account associated with Instance A.
  • Your account has SSH access specifically to Instance A.
  • Your account has no access to Instance B. The service account is the only account with OS Login roles necessary to connect to Instance B.

Connect to Instance A and execute commands as that service account. This step requires that you have the roles/iam.serviceAccountUser role for that service account:

1. Connect to Instance A as the user with the roles/iam.serviceAccountUser role. For example, you can use the gcloud command-line tool to establish this first SSH connection:

   gcloud compute ssh instance-a --project=PROJECT_ID --zone=ZONE

2. As long as you have the roles/iam.serviceAccountUser role, after you use SSH to connect to Instance A, you can execute commands as if you were the service account. In this example, run the gcloud tool on Instance A to create a chain-SSH connection to Instance B. The gcloud tool identifies that Instance B is enabled to use OS Login and also identifies that the service account has the necessary IAM roles for using SSH to connect to Instance B.

   gcloud compute ssh instance-b --project=PROJECT_ID --zone=ZONE

   The output is similar to the following:

   WARNING: Using OS Login user [sa_113491385848438711199] instead of default user [my-username]
   Linux instance-b 4.9.0-8-amd64 #1 SMP Debian 4.9.110-3+deb9u6 (2018-10-08) x86_64
   ⋮
   

3. You are now connected to Instance B as the service account, and can execute commands as that service account—for example:

   sa_113491385848438711199@instance-b:~$ uname -a
   
   Linux instance-b 4.9.0-8-amd64 #1 SMP Debian 4.9.110-3+deb9u6 (2018-10-08) x86_64 GNU/Linux
   

What's next

• Learn how SSH connections to Linux VMs work on Compute Engine.
• Learn how to manage access to instances for multiple users across a project or organization.
• Securely connect to VM instances.
• Transfer files to your Linux instances.
• Learn how to troubleshoot SSH issues.
• Review the Setting up Chrome Remote Desktop for Linux on Compute Engine tutorial.