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:
- Install or update to the latest version of the gcloud command-line tool.
- 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:
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.
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.
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:
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.
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.
Download
putty.exe
, if you have not done so already.Open PuTTY by launching
putty.exe
. A connection configuration window opens.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:
In the Category menu, navigate to Connection > SSH > Auth.
In the Private key file for authentication field, browse to the location of your private key file.
For example, see the following screenshot:
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:
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.
Install Secure Shell on your Chromebook or the Chrome browser if you have not done so already.
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.
Open the Secure Shell app in a Chrome browser tab. You can access Chrome apps by typing
chrome://apps
in the address bar.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.
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.
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.
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.
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.
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 toZONE
: the name of the zone in which the instance is located
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:
Provide your public SSH key to an instance using one of the available options. You cannot proceed without this.
On your local machine, start the
ssh-agent
to manage your SSH keys for you:eval ssh-agent $SHELL
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. ReplacePRIVATE_KEY
with the filename of your private key file.ssh-add ~/.ssh/PRIVATE_KEY
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.
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:
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.
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.
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.
See the following examples for complete steps:
gcloud
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.
To use the gcloud
command-line tool to connect to an instance that
does not have an external IP address:
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.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):
Project metadata:
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.
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
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:
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.
On your local machine, start the
ssh-agent
to manage your SSH keys for you:eval ssh-agent $SHELL
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.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.
Connect to the Linux bastion host instance using either
ssh
orgcloud 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 thegcloud
command-line tool, and then use regularssh
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.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:
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.
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.
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:
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.
Grant the
roles/iap.tunnelResourceAccessor
role to the user that wants to connect to the VM.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 instanceZONE
: the name of the zone in which the instance is locatedINSTANCE_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.
- Your account has the
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:
Connect to Instance A as the user with the
roles/iam.serviceAccountUser
role. For example, you can use thegcloud
command-line tool to establish this first SSH connection:gcloud compute ssh instance-a --project=PROJECT_ID --zone=ZONE
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 thegcloud
tool on Instance A to create a chain-SSH connection to Instance B. Thegcloud
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 ⋮
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.