This page describes how to enable interactive access to an instance'sserial console to debug boot and networking issues, troubleshoot malfunctioninginstances, interact with the GRand Unified Bootloader (GRUB), and perform othertroubleshooting tasks.

If you only need to view serial port output without issuing any commands tothe serial console, you can call thegetSerialPortOutputmethod or use Cloud Logging to read information that your instance haswritten toits serial port; seeViewing serial port logs.However, if you run into problems accessing your instance through SSH or need totroubleshoot an instance that is not fully booted, you can enable interactiveaccess to the serial console, which lets you connect to and interact with any ofyour instance's serial ports. For example, you can directly run commandsand respond to prompts in the serial port.

When you enable or disable the serial port, you can use any Boolean value thatis accepted by the metadata server. For more information, seeBoolean values.

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Enabling interactive access on the serial console

Enable interactive serial console access for individual VM instances or foran entire project.

Enabling access for a project

Enabling interactive serial console access on a project enables access for allVM instances that are part of that project.

By default, interactive serial port access is disabled. You can also explicitlydisable it by setting theserial-port-enable key toFALSE. Ineither case, any per-instance setting overrides the project-level setting orthe default setting.

gcloud compute project-info add-metadata \    --metadata serial-port-enable=TRUE

{ "fingerprint": "FikclA7UBC0=", "items": [  {   "key": "serial-port-enable",   "value": "TRUE"  } ]}

Enabling access for a VM instance

Enable interactive serial console access for a specific instance. A per-instancesetting, if it exists, overrides any project-level setting. You can alsodisable access for a specific instance, even if access is enabled on the projectlevel, by settingserial-port-enable toFALSE, instead ofTRUE. Similarly,you can enable access for one or more instances even if it is disabled for theproject, explicitly or by default.

gcloud compute instances add-metadatainstance-name \    --metadata serial-port-enable=TRUE

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata{ "fingerprint": "zhma6O1w2l8=", "items": [  {   "key": "serial-port-enable",   "value": "TRUE"  } ]}

Configure serial console for a bare metal instance

For bare metal instances, increase the bit rate, also known as baud rate, forthe serial console to 115,200 bps (~11.5kB/sec). Using a slower speed resultsin garbled or missing console output.

Bootloader configuration varies between operating systems and OS versions. Referto the OS distributor's documentation for instructions.

If modifying the bit rate on the command line for the current session, use acommand similar to the following:

console=ttyS0,115200

If modifying the GRUB configuration, use a command similar to the following:

serial --speed=115200

Make sure that you update the actual bootloader configuration. This can be donewithupdate-grub,grub2-mkconfig, or a similar command.

Connecting to a serial console

Compute Engine offers regional serial console gateways for each Google Cloudregion. After enabling interactive access for a VM's serial console, youcan connect to a regional serial console.

The serial console authenticates users withSSH keys. Specifically, you must add yourpublic SSH key to the project or instance metadata and store your private keyon the local machine from which you want to connect. The gcloud CLIand the Google Cloud console automatically add SSH keys to the project for you.If you are using a third-party client, you might need to add SSH keys manually.

If you are using a third-party client, you can additionallyvalidate the connection using the serial console's host keys.When you use the Google Cloud CLI to connect, host key authentication is doneautomatically on your behalf.

gcloud compute connect-to-serial-portVM_NAME \    --port=PORT_NUMBER

Validate third-party SSH client connections

When you use a third-party SSH client that isn't the Google Cloud CLI, werecommend that you verify that you're protected against impersonation orman-in-the-middle attacks by checking Google's Serial Port SSH host key. To setup your system to check the SSH host key, complete the following steps:

1. Download the SSH host key for the serial console you will be using:

   • For regional connections, the SSH host key for a region can be found athttps://www.gstatic.com/vm_serial_port_public_keys/REGION/REGION.pub

     Caution: As of March 31, 2025, the previous endpoint ofhttps://www.gstatic.com/vm_serial_port/REGION/REGION.pubis deprecated. For more information, seeSerial console SSH key endpoint deprecation.

   • For global connections, downloadGoogle's Serial Port SSH host key

2. Open your known hosts file, generally located at~/.ssh/known_hosts.

3. Add the contents of the SSH host key, with the server's hostnameprepended to the key. For example, if the us-central1 server key contains the linessh-rsa AAAAB3NzaC1yc..., then~/.ssh/known_hosts should have a linelike this:

   [us-central1-ssh-serialport.googleapis.com]:9600 ssh-rsa AAAAB3NzaC1yc...

For security reasons, Google might occasionally change the Google Serial PortSSH host key. If your client fails to authenticate the server key, immediatelyend the connection attempt and complete the earlier steps to download a newGoogle Serial Port SSH host key.

If, after updating the host key, you continue to receive a host authenticationerror from your client, stop attempts to connect to the serial port and contactGoogle support. Don't provide any credentials over a connection wherehost authenticationhas failed.

Disconnecting from the serial console

To disconnect from the serial console, follow the instructions for the methodyou used to connect.

In the Google Cloud CLI, or using SSH, you can discover other commands bytyping~?. You can also examine the man page for SSH with the followingcommand:

man ssh

Don't try to disconnect using any of the following methods:

• TheCTRL+ALT+DELETE key combination or other similar combinations. Thisdoesn't work because the serial console does not recognize PC keyboardcombinations.

• Theexit orlogout command doesn't work because the guest is not awareof any network or modem connections. Using this command causes the consoleto close and then reopen again, and you remain connected to the session. Ifyou would like to enableexit andlogout commands for your session,you can enable it by setting theon-dtr-low option.

Connecting to a serial console with a login prompt

If you are trying to troubleshoot an issue with a VM that has bootedcompletely or trying to troubleshoot an issue that occurs after VMhas booted past single user mode, you might be prompted for login informationwhen trying to access the serial console.

By default, Google-supplied Linux system images are not configured to allowpassword-based logins for local users. However, Google-supplied Windows imagesare configured to allow password-based logins for local users.

If your VM is running an image that is preconfigured with serial port logins,you need to set up a local password on the VM so that you can sign in to theserial console, if prompted. You can set up a local password after connecting tothe VM or by using a start-up script.

After the user has been created, replace the startup script with the startupscript that you stored in this section.

Setting up a local password usingpasswd on the VM

The following instructions describe how to set up a local password for auser on a VM so that the user can log on to theserial console of that VM using the specified password.

1. Connect to the VM. Replaceinstance-namewith the name of your instance.

   gcloud compute sshinstance-name

2. On the VM, create a local password with the following command. This actionsets a password for the user that you are logged in as.

   sudo passwd $(whoami)

3. Follow the prompts to create a password.

4. Next, log out of the instance andconnect to the serial console.

5. Enter your login information when prompted.

Setting up a login on other serial ports

Login prompts are enabled on port 1 by default on all Linux public images that usesystemd service management. For Windows images, Login prompts are enabled onport 2 by default and managed by Device Manager. However, port 1 can often beoverwhelmed by logging data and other information being printed to the port.As an alternative, you can choose to enable a login prompt on another port, such as port 2(ttyS1), by executing the following command on your VM:

Understanding serial port numbering

Each virtual machine instance has four serial ports. For consistency with thegetSerialPortOutputAPI, each port is numbered 1 through 4. Linux and other similar systems numbertheir serial ports 0 through 3. For example, on many operating system images,thecorresponding devices are/dev/ttyS0 through/dev/ttyS3. Windows refers toserial ports asCOM1 throughCOM4. To connect to what Windows considersCOM3 and Linux considersttyS2, you would specify port 3. Usethe following table to help you figure out which port you want to connect to.

Note that many Linux images use port 1 (/dev/ttyS0) for logging messages fromthe kernel and system programs.

Sending a serial break

TheMagic SysRq key feature lets you perform low-level tasks regardless of the system'sstate. For example, you can sync file systems, reboot the instance,end processes, andunmount file systems using the Magic SysRq key feature.

To send a Magic SysRq command using a simulated serial break:

1. Press theENTER key.
2. Type~B (tilde, followed by uppercaseB).
3. Type the Magic SysRq command.

Compute Engine provides audit logs to track who has connected anddisconnected from an instance's serial console. To view logs, you must havepermissions for the Logs Vieweror be a project viewer or editor.

1. In the Google Cloud console, go to theLogs Explorer page.

   Go to Logs Explorer

2. Expand the drop-down menu and selectGCE VM Instance.
3. In the search bar, typessh-serialport.googleapis.com and pressEnter.
4. A list of audit logs appears. The logs describe connections anddisconnections from aserial console. Expand any of the entries to get more information.

For any of the audit logs, you can:

1. Expand theprotoPayload property.
2. Look formethodName to see activity this log applies to (either aconnection or disconnection request). For example, if this log tracks adisconnection from the serial console, the method name would say"google.ssh-serialport.v1.disconnect". Similarly, a connection log wouldsay"google.ssh-serialport.v1.connect". An audit log entry is recorded atthe beginning and end of each session on the serial console.

There are different audit log properties for different log types. For example,audit logs relating to connections have properties that arespecific to connection logs, while audit logs for disconnections havetheir own set of properties. There are certain audit log properties thatare also shared between both log types.

All serial console logs

The following table provides audit log properties and their values for allserial console logs:

Connection logs

The following table provides audit log properties and their values specific forconnection logs:

Disconnection logs

The following table provides audit log properties and their values specific fordisconnection logs:

Failed connection logs

When a connection fails, Compute Engine creates an audit log entry. Afailed connection log looks very similar to a successful connection entry, buthas the following properties to indicate a failed connection.

Disabling interactive serial console access

You can disable interactive serial console access by changing metadata on thespecific instance or project, or by setting anOrganization Policy thatdisables interactive serial console access to all VM instances for one or moreprojects that are part of the organization.

Disabling interactive serial console on a particular instance or project

Project owners and editors, as well as users who have been granted thecompute.instanceAdmin.v1 role, can disable access to the serial console bychanging the metadata on the particular instance or project. Similar toenabling serial console access,set theserial-port-enable metadata toFALSE:

serial-port-enable=FALSE

For example, using the Google Cloud CLI, you can apply this metadatato a specific instance like so:

gcloud compute instances add-metadatainstance-name \    --metadata=serial-port-enable=FALSE

To apply the metadata to the project:

gcloud compute project-info add-metadata \    --metadata=serial-port-enable=FALSE

Disabling interactive serial console access through Organization Policy

If you have been granted theorgpolicy.policyAdmin role on the organization,you can set anorganization policythat prevents interactive access to the serial console, regardless of whetherinteractive serial console access is enabled on the metadata server. After theorganization policy is set, the policy effectively overrides theserial-port-enable metadata key,and no users of the organization or project can enable interactive serialconsole access. By default, this constraint is set toFALSE.

The constraint for disabling interactive serial console access is as follows:

compute.disableSerialPortAccess

Complete the following instructions to set this policy on the organization.After setting up a policy, you can grant exemptions on a per-project basis.

gcloud resource-manager org-policies enable-enforce \    --organizationorganization-id compute.disableSerialPortAccess

 POST https://cloudresourcemanager.googleapis.com/v1/organization-name:setOrgPolicy

"constraint": "constraints/compute.disableSerialPortAccess"

 {   "policy":   {     "booleanPolicy":     {       "enforced": TRUE     },     "constraint": "constraints/compute.disableSerialPortAccess"   } }

The policy is immediately effective, so any projects under the organizationimmediately stop allowing interactive access to the serial console.

To temporarily disable the policy, use thedisable-enforce command:

gcloud resource-manager org-policies disable-enforce \    --organizationorganization-id compute.disableSerialPortAccess

Alternatively, you can make an API request where the request body sets theenforced parameter toFALSE:

{  "policy":  {    "booleanPolicy":    {      "enforced": FALSE    },    "constraint": "constraints/compute.disableSerialPortAccess"  }}

Setting the organization policy at the project level

You can set the same organizational policy on a per-project basis. Thisoverrides the setting at the organization level.

gcloud resource-manager org-policies disable-enforce \    --projectproject-id compute.disableSerialPortAccess

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setOrgPolicy

"constraint": "constraints/compute.disableSerialPortAccess"

{  "policy":  {    "booleanPolicy":    {      "enforced": FALSE    },    "constraint": "constraints/compute.disableSerialPortAccess"  }}

Tips and tricks

• If you are having trouble connecting using a standard SSH client, butgcloud compute connect-to-serial-port connects successfully, it might behelpful to rungcloud compute connect-to-serial-port with the--dry-runcommand-line option to see the SSH command that it would have run on yourbehalf, and compare the options with the command you are using.

• If you're using a Windows VM with OS Login enabled and encounter anUNAUTHENTICATED error, verify that your public SSH keys have been posted to your project or instance metadata. To learn more, seeManaging SSH keys in metadata.

• Setting the bit rate, also known as baud rate, you can set any bit rate youlike, such asstty 9600, but the feature normally forces the effective rate to115,200 bps (~11.5kB/sec). This is because many public images default toslow bitrates, such as 9,600 on the serial console, and would boot slowly.

• Some OS images have inconvenient defaults on the serial port. For example,on CentOS 7, thestty icrnl default for the Enter key on the console is tosend aCR, also known as^M. The bash shell might maskthis until you try to set a password, at which point you might wonder why itseems stuck at thepassword: prompt.

• Some public images have job control keys that are disabled by default if youattach a shell to a port in certain ways. Some examples of these keys include^Z and^C. Thesetsid command might fix this. Otherwise, if you see ajob control is disabled in this shell message, be careful not to runcommands that you will need to interrupt.

• You might find it helpful to tell the system the size of the window you'reusing, so that bash and editors can manage it properly. Otherwise, you mightexperience odd display behavior because bash or editors attempt to manipulatethedisplay based on incorrect assumptions about the number of rows and columnsavailable. Use thestty rows Y cols X command andstty -a flag to seewhat the setting is. For example:stty rows 60 cols 120(if your window is 120 chars by 60 lines).

• If, for example, you connect using SSH from machine A to machine B, and thento machine C, creating a nested SSH session, and you want to usetilde (~) commands to disconnect or send a serial break signal, you will needto addenough extra tilde characters to the command to get to the right SSH client. Acommand following a single tilde is interpreted by the SSH client onmachine A; a command following two consecutive tildes (Enter~~) isinterpreted by the client on machine B, and so forth. You only need to pressEnter one time because thatis passed all the way through to the innermost SSH destination. This is truefor any use of SSH clients that provide the tilde escape feature.

  If you lose track of how many tilde characters you need, press the Enterkey and then type tilde characters one at a time until the instance echoesthe tilde back. This echo indicates that you have reached the end of thechain and younow know that to send a tilde command to the most nested SSH client, youneed one less tilde than however many tildes you typed.

Advanced options

You can also use the following advanced options with the serial port.

Controlling max connections

You can set themax-connections property to control how many concurrentconnections can be made to this serial port at a time. The default andmaximum number of connections is 5. For example:

gcloud compute connect-to-serial-portinstance-name \    --portport-number \    --extra-args max-connections=3

ssh -iprivate-ssh-key-file -p 9600project-id.zone.instance-name.username.max-connections=3@ssh-serialport.googleapis.com

Setting replay options

By default, each time you connect to the serial console, you will receivea replay of the last 10 lines of data, regardless of whether the last 10 lineshave been seen by another SSH client. You can change this setting and controlhow many and which lines are returned by setting the following options:

• replay-lines=N: SetN to the number of lines you want replayed. Forexample, ifN is 50, then the last 50 lines of the console output isincluded.
• replay-bytes=N: Replays the most recentN bytes. You can also setN tonew which replays all output that has not yet been sent to any client.
• replay-from=N: Replays output starting from an absolute byte indexthat you provide. You can get the current byte indexof serial console output by making agetSerialPortOutputrequest. If you setreplay-from, all other replay options are ignored.

With the Google Cloud CLI, append the following to yourconnect-to-serial-port command, whereN is the specified number of lines(or bytes or absolute byte index, depending on which replay option you areselecting):

--extra-args replay-lines=N

If you are using a third-party SSH client, provide this option in your SSHcommand:

ssh -iprivate-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.replay-lines=N@ssh-serialport.googleapis.com

You can also use a combination of these options as well. For example:

replay-lines=N andreplay-bytes=new

Replay the specified number of lines OR replay all output not previouslysent to any client, whichever is larger. The first client to connect with thisflag combination will see all the output that has been sent to the serialport, and clients that connect subsquently will only see the lastN lines. Examples:

gcloud compute connect-to-serial-portinstance-name--portport-number --extra-args replay-lines=N,replay-bytes=new

ssh -iprivate-ssh-key-file -p 9600project-id.zone.instance-name.username.replay-lines=N.replay-bytes=new@ssh-serialport.googleapis.com

replay-lines=N andreplay-bytes=M

Replay lines up to, but not more than, the number of lines or bytesdescribed by these flags, whichever is less. This option won't replay morethanN orM bytes.

gcloud compute connect-to-serial-portinstance-name--portport-number --extra-args replay-lines=N,replay-bytes=M

ssh -iprivate-ssh-key-file -p 9600project-id.zone.instance-name.username.replay-lines=N.replay-bytes=M@ssh-serialport.googleapis.com

Handling dropped output

The most recent 1 MiB of output for each serial port is always available andgenerally, your SSH client shouldn't miss any output from the serial port.If, for some reason, your SSH client stops accepting output for a period oftime but does not disconnect, and more than 1 MiB of new data is produced,your SSH client might miss some output. When your SSHclient is not accepting data fast enough to keep up with the output on theserial console port, you can set theon-dropped-output property to determinehow the console behaves.

Set any of the following applicable options with this property:

• insert-stderr-note: Insert a note on the SSH client'sstderr indicatingthat output was dropped. This is the default option.
• ignore: Silently drops output and does nothing.
• disconnect: Stop the connection.

For example:

gcloud compute connect-to-serial-portinstance-name \    --portport-number \    --extra-args on-dropped-output=ignore

ssh -iprivate-ssh-key-file -p 9600project-id.zone.instance-name.username.on-dropped-output=ignore@ssh-serialport.googleapis.com

Enabling disconnect using exit or logout commands

You can enable disconnecting on exit or logout commands by setting theon-dtr-low property todisconnect when you connect to the serial console.

On the Google Cloud CLI, append the following flag to yourconnect-to-serial-port command:

--extra-args on-dtr-low=disconnect

If you are using a third-party SSH client, provide this option in your SSHcommand:

ssh -iprivate-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.on-dtr-low=disconnect@ssh-serialport.googleapis.com

Enabling thedisconnect option might cause your instance to disconnect one ormore times when you are rebooting the instance because the operating systemresets the serial ports while booting up.

• Learn more about thegetSerialPortOutput API.
• Learn how to retain and viewserial port outputeven after a VM instance is deleted.
• Read moretroubleshooting tips.
• Learn more about applyingmetadata.
• Learn aboutSSH keys.