SSH from the Browser

SSH from the Browser allows you to use SSH to connect to a Google Compute Engine virtual machine instance from within the Google Cloud Platform Console. You do not need to install web browser extensions or additional software to use this feature. SSH from the Browser is an alternative to other methods of connecting to an instance.

Connecting to a Linux virtual machine instance

Compute Engine will manage your SSH keys for you whenever you connect to a Linux instance from your browser, creating and applying SSH key pairs when needed. You cannot manage the SSH keys that are used to connect from the browser. Instead, user access to connect from the browser is controlled by Identity and Access Management (IAM) roles. The members and IAM roles for a project can be viewed from the IAM page in the Google Cloud Platform Console:

Go to the IAM page

To connect through the browser, you must be a project member who is a compute instance admin. If your instance can run as a service account, you must also be a service account user. If you do not have access to connect through the browser, ask a project owner to add you to the project and grant you access.

Once you have been granted access, connect to a Linux instance directly from your web browser in the GCP Console:

1. In the GCP Console, go to the VM Instances page.

   Go to the VM Instances page

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

   

Alternatively, you can open an SSH connection to an instance by clicking its name and clicking SSH from the instance details page.

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.

Supported environments

SSH from the Browser supports the following:

• Web browsers: Latest version of Google Chrome, Firefox, Microsoft Edge, Microsoft Internet Explorer 11+ and Safari 8+. Note that Safari in private browser mode is not supported.
• Virtual machine configurations: All Linux virtual machine images natively available in Google Cloud Platform.

Known issues

• Startup latency: Current connection time using SSH from the Browser is 5 to 30 seconds. Current versions of the guest environment support quicker connections.

• New virtual machine instances not immediately available: New instances take some time to boot up before SSH can be established. If you fail to connect to a new instance, retry after a few minutes.

• Intermittent disconnects: At this time, we do not offer a specific SLA for connection lifetimes. Use terminal multiplexers like tmux or screen if you plan to keep the terminal window open for an extended period of time.

• Connecting to instances with no external IP address: At this time, you cannot use SSH from the Browser to connect to instances that do not have an external IP address. As a workaround, you can use this feature to SSH into another instance in your project that does have an external IP address, such as an instance that runs your frontend. Then, use the ssh -A INTERNAL_IP command to log into the desired instance by its internal IP address. You need to run this command within approximately two minutes after logging into the first instance, before the SSH key expires and your login credentials are no longer valid for forwarded connections.

• Ctrl+W closes the window: Ctrl+W, Ctrl+F4, Ctrl+Tab, and other key combinations that work as browser keyboard shortcuts are not passed by the SSH client to the target system. To send these or other shortcuts, click the keyboard icon in the top right of the window. If you use the Google Chrome browser, you can install the "SSH for Google Cloud Platform" extension. The extension improves the console experience for SSH from the Browser and Google Cloud Shell by giving you direct access to keyboard shortcuts normally reserved by the browser, such as CTRL-W.

Handling "Unable to connect on port 22" error message

You may see this error under the following conditions:

• The instance is booting up and sshd is not yet running. Verify that the instance has finished booting up before trying again.

• The instance is not running sshd. sshd runs by default on instances created from standard Compute Engine images. If you have manually disabled sshd or you have configured a custom image that is not running this service, SSH from the Browser will not work.

• sshd is listening on a port other than the one you are connecting to. By default, SSH from the Browser connects to the instance on port 22. If you are running sshd on a custom port, you can connect to that port using "Open in browser window on custom port" item in the SSH button drop-down menu.

• There is no firewall rule allowing SSH access on the port. SSH access on port 22 is enabled on all Compute Engine instances by default. If you have disabled access, SSH from the Browser will not work. If you run sshd on a port other than 22, you need to enable the access to that port with a custom firewall rule.

• The firewall rule allowing SSH access is enabled, but is not configured to allow connections from GCP Console services. Source IP addresses for browser-based SSH sessions are dynamically allocated by GCP Console and can vary from session to session. For the feature to work, you must allow connections either from any IP address or from Google's IP address range which you can retrieve using public SPF records.

• The instance is shut down. Verify that the instance is up and running. See this guide for information on how you can troubleshoot an unhealthy instance.

Handling "Could not connect, retrying..." error

• The instance might not be running the guest environment. Verify that the guest environment is installed and running.

• The boot disk of the instance has run out of free space. When the connection is established, the guest environment updates the ~/.ssh/authorized_keys file with the public SSH key used for the current session. If the disk runs out of free space, the update fails. To identify issues with disk space, check the serial console output of the instance and look for "No space left" errors. Here are some methods that you can use to resolve disk space issues:

  • Resize the boot persistent disk of the instance to increase its size. If the operating system image used by the instance supports automatic resizing, this is the easiest option because the operating system will automatically resize the root partition to match the new size after the instance is restarted.
  • If you know which files are consuming the disk space, create a startup script that deletes the unnecessary files and frees up space for the instance to start. Restart the instance so that the script executes and cleans the files. Be careful to use the correct command and delete the correct files. After your instance starts and you are able to connect to the instance through SSH, set the startup-script metadata item back so it does not continue to delete the files.
  • See the troubleshooting guide for information about how to access the instance's disk.

• Permissions or ownership on $HOME, $HOME/.ssh, or $HOME/.ssh/authorized_keys are wrong. The guest environment needs to be able to store the public SSH key in the $HOME/.ssh/authorized_keys file for the connecting user. The $HOME directory should have Unix permissions of either 0755 or 0700, the $HOME/.ssh directory should have Unix permissions of 0700, and the authorized_keys file should have Unix permissions of 0600. The owner of the $HOME directory, the $HOME/.ssh directory, and the authorized_keys file should be the same as the connecting user. Try connecting as a different user by changing the username and fix any permission issues for the user who cannot connect.

Copy/Paste

You can copy and paste text using the keyboard shortcuts supported by your browser and platform (Ctrl+C/Ctrl+V on Windows and Linux, Cmd+C/Cmd+V on macOS, and Ctrl+Shift+V on Chrome OS). In general, these commands work for most configurations, but your configuration may render different results.

Transfer files

If you can establish an SSH connection to an instance using the SSH from the Browser window, you can use that connection to transfer files to the instance.

Read Transferring files using SSH in the browser to learn more.

Scrolling

You can scroll the terminal using your mouse wheel or trackpad. Alternatively, the Ctrl-Shift-PageUp / Ctrl-Shift-PageDn hotkeys scroll the terminal on Windows and Linux, and Fn-Shift-Up / Fn-Shift-Down scroll the terminal on macOS.

Login username

Default username

By default, a username for SSH sessions is generated from the email address logged into the account, omitting the domain information. For example, if an email is user@gmail.com, the corresponding username would be user.

Default username with OS Login enabled

If you have OS Login enabled, and a username is not set by a G Suite administrator, then a longer version of a username is set by default. This username includes the domain information. For example, if an email is user@gmail.com, the corresponding username would be user_gmail_com. For more details about OS Login behaviors, see Expected login behaviors.

Changing the default username

You can change the username from within an SSH window, following these instructions:

1. Connect to a virtual machine instance.
2. In the top right-hand corner of the SSH window, click the Settings icon .
3. Select Change Linux Username. There is a 32 character limit on the maximum length of the login name on Linux systems, so both default and configured usernames are truncated to not exceed that limit.

4. (Optional) Copy data to the new home directory. Each new username is a different Unix user so if you used your home directory to store any data, you can copy the data to the new directory using the cp command. For example, if you change your username from user_gmail_com to user, run the following commands:

   # This will overwrite files in the target directory, so be careful.
   $ sudo cp -r /home/user_gmail_com/. /home/user
   

   $ sudo chown -R user:user /home/user