Como solucionar problemas usando o console serial

Linux Windows

---

Nesta página, você verá como ativar o acesso interativo ao console serial de uma instância para depurar problemas de inicialização e rede, resolver problemas em instâncias com mau funcionamento, interagir com o GRand Unified Bootloader (GRUB) e realizar outras tarefas de solução de problemas.

Observação: não é possível ativar o acesso interativo ao console serial para instâncias bare metal porque o console serial é somente leitura para elas. Para executar comandos de maneira interativa, conecte-se à instância usando SSH depois que ela for iniciada.

Uma instância de máquina virtual (VM) tem quatro portas seriais virtuais. A interação com uma porta serial é similar ao uso de uma janela de terminal, no sentido de que a entrada e a saída ocorrem inteiramente no modo de texto e não há suporte para interface gráfica ou mouse. O sistema operacional da instância, o BIOS, e outras entidades em nível de sistema, frequentemente gravam a saída nas portas seriais e podem aceitar como entradas comandos ou respostas a prompts. Normalmente, essas entidades no nível do sistema usam a primeira porta serial (porta 1), que costuma ser chamada de console serial.

Se você precisa apenas ver a saída da porta serial sem emitir comandos ao console, chame o método getSerialPortOutput ou use o Cloud Logging para ler informações gravadas por sua instância na porta serial. Consulte as informações sobre como visualizar registros de portas seriais. Contudo, se você tiver problemas para acessar a instância por meio do SSH ou precisar solucionar problemas em uma instância que não está totalmente inicializada, será possível ativar o acesso interativo ao console serial, o que permite a conexão e a interação com qualquer uma das portas seriais da instância. Por exemplo, é possível executar comandos e responder a prompts diretamente na porta serial.

Ao ativar ou desativar a porta serial, é possível usar qualquer valor booleano que seja aceito pelo servidor de metadados. Para mais informações, consulte Valores booleanos.

Antes de começar

• Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:
  

  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, then initialize it by running the following command:

     gcloud init

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

  REST

  Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Permissões exigidas para a tarefa

Para executar esta tarefa, é necessário ter as permissões a seguir:

• compute.instances.setMetadata na VM, se ativar o acesso interativo em uma VM específica
• compute.projects.setCommonInstanceMetadata no projeto, se ativar o acesso interativo para todas as VMs no projeto
• Papel iam.serviceAccountUser na conta de serviço da instância

Ativação do acesso interativo no console serial

Ative o acesso ao console serial interativo para instâncias de VM individuais ou para um projeto inteiro.

Cuidado: o console serial interativo não oferece suporte a restrições de acesso baseadas em IP, como listas de permissões de IP, a menos que você use VPC Service Controls. Se você ativar o console serial interativo em uma instância, os clientes poderão tentar se conectar a essa instância de qualquer endereço IP. Qualquer pessoa poderá se conectar a essa instância se souber a chave SSH, o nome de usuário, o código do projeto, a zona e o nome da instância corretos.

Como ativar acesso de um projeto

A ativação do acesso ao console serial interativo em um projeto permite acesso a todas as instâncias de VM que fazem parte desse projeto.

Por padrão, o acesso à porta serial interativa está desativado. Também é possível desativá-lo explicitamente definindo a tecla serial-port-enable como FALSE. Em ambos os casos, qualquer configuração por instância modifica a configuração para envolvidos no projeto ou a configuração padrão.

Console

1. No Console do Google Cloud, acesse a página Metadados.

   Acessar a página "Metadados"

2. Clique em Editar para editar entradas de metadados.
3. Adicione uma nova entrada que use a chave serial-port-enable e o valor TRUE.
4. Salve as alterações.

gcloud

Usando a Google Cloud CLI, digite o comando project-info add-metadata da seguinte maneira:

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

REST

Na API, faça uma solicitação para o método projects().setCommonInstanceMetadata, fornecendo à chave serial-port-enable um valor de TRUE:

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

Como ativar o acesso para uma instância de VM

Ative o acesso ao console serial interativo para uma instância específica. Uma configuração por instância modificará qualquer configuração para envolvidos no projeto. Também é possível desativar o acesso para uma instância específica, mesmo se ele estiver ativado para envolvidos no projeto. Para isso, defina serial-port-enable como FALSE em vez de TRUE. Da mesma maneira, é possível ativar o acesso para uma ou mais instâncias, mesmo se ele estiver desativado para o projeto, explicitamente ou por padrão.

Console

1. No console do Google Cloud, acesse a página Instâncias de VMs.

   Acessar a página "Instâncias de VMs"

2. Clique na instância para que você quer ativar acesso.
3. Clique em Editar.
4. Na seção Acesso remoto, marque a caixa de seleção Ativar conexão com portas seriais.
5. Salve as alterações.

gcloud

Usando a Google Cloud CLI, digite o comando instances add-metadata, substituindo instance-name pelo nome da instância.

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

REST

Na API, faça uma solicitação para o método instances().setMetadata com a chave serial-port-enable e um valor de 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"
  }
 ]
}

Configurar o console serial para uma instância bare metal

No caso das instâncias bare metal, aumente a taxa de bits, também conhecida como taxa de Baud, do console serial para 115.200 bps (cerca de 11,5 kB/s). Usar uma velocidade mais lenta resulta em saídas do console distorcidas ou ausentes.

A configuração do carregador de inicialização varia entre os sistemas operacionais e as versões de SO. Consulte a documentação do distribuidor do SO para mais instruções.

Para modificar a taxa de bits na linha de comando para a sessão atual, use um comando semelhante ao seguinte:

console=ttyS0,115200

Para modificar a configuração do GRUB, use um comando semelhante ao seguinte:

serial --speed=115200

Atualize a configuração real do carregador de inicialização. Isso pode ser feito com update-grub, grub2-mkconfig ou um comando semelhante.

Conexão com um console serial

O Compute Engine oferece gateways regionais de console serial para cada região do Google Cloud. Depois de ativar o acesso interativo para o console serial de uma VM, é possível se conectar a um console serial regional.

O console serial autentica usuários com chaves SSH. Especificamente, é necessário adicionar sua chave SSH pública aos metadados do projeto ou da instância e armazenar sua chave privada na máquina local da qual quer se conectar. A CLI gcloud e o Console do Google Cloud adicionam automaticamente chaves SSH ao projeto para você. Se estiver usando um cliente de terceiros, talvez seja necessário adicionar as chaves SSH manualmente.

Cuidado: não é recomendado se conectar diretamente ao console serial usando o endereço IP dele em vez do nome do host. Os endereços IP do console serial podem ser alterados sem aviso prévio.

Console

Para se conectar ao console serial regional de uma VM, faça o seguinte:

1. No console do Google Cloud, acesse a página Instâncias de VMs.

   Acessar a página "Instâncias de VMs"

2. Clique na instância à qual você quer se conectar.
3. Em Acesso remoto, clique em Conectar ao console serial para se conectar à porta padrão (porta 1).
4. Se você quiser se conectar a outra porta serial, clique na seta para baixo ao lado do botão Conectar ao console serial e altere o número da porta de acordo.
5. Para instâncias do Windows, abra o menu suspenso ao lado do botão e conecte-se à Porta 2 para acessar o console serial.

gcloud

Para se conectar ao console serial regional de uma VM, use o comando gcloud compute connect-to-serial-port:

  gcloud compute connect-to-serial-port VM_NAME 

      --port=PORT_NUMBER
  

Substitua:

• VM_NAME: o nome da VM com o console serial ao qual você quer se conectar.

• PORT_NUMBER: o número da porta que você quer conectar. Para VMs do Linux, use 1. Para VMs do Windows, use 2. Para saber mais sobre números de portas, consulte Noções básicas sobre a numeração de portas seriais.

  Observação: o número da porta padrão é 1.

Outros clientes SSH

Observação: é necessário adicionar a chave pública aos metadados do projeto ou da instância para usar um cliente SSH de terceiros. Se você já tiver usado a gcloud CLI para estabelecer conexão com outras instâncias no mesmo projeto, o PUBLIC_KEY_FILE provavelmente estará em $HOME/.ssh/google_compute_engine.pub. Se você nunca se conectou a uma instância neste projeto antes, nunca precisou adicionar chaves públicas. Assim, será necessário adicionar chaves SSH aos metadados do projeto ou da instância antes de se conectar usando um cliente SSH de terceiros. Consulte Como gerenciar chaves SSH nos metadados para mais informações.

É possível se conectar ao console serial de uma instância usando outros clientes SSH de terceiros, contanto que o cliente permita que você se conecte à porta TCP 9600.

Para se conectar ao console serial regional de uma VM, execute um dos seguintes comandos, dependendo do SO da VM:

• Para se conectar a uma VM do Linux:

  ssh -i PRIVATE_SSH_KEY_FILE -p 9600 [e-mail]
  

• Para se conectar a uma VM do Windows:

  ssh -i PRIVATE_SSH_KEY_FILE -p 9600 PROJECT_ID.ZONE.VM_NAME.USERNAME.OPTIONS.port=[e-mail]
  

Substitua:

• PRIVATE_SSH_KEY_FILE: a chave SSH privada da instância.
• PROJECT_ID: o ID do projeto da instância de VM.
• ZONE: a zona da instância de VM.
• REGION: a região da instância de VM.
• VM_NAME: o nome da instância de VM.
• USERNAME: o nome de usuário que você está usando para se conectar à instância. Normalmente, é o nome de usuário na sua máquina local.
• OPTIONS: opções extras que você especifica para essa conexão. Por exemplo, é possível especificar uma determinada porta serial e especificar qualquer opção avançada. O número da porta pode variar de 1 a 4. Para saber mais sobre números de portas, consulte Noções básicas sobre a numeração de portas seriais. Se o número for omitido, a conexão será estabelecida com a porta serial 1.

Cuidado: o gateway global do console serial foi descontinuado em 30 de abril de 2024 e não está mais disponível para uso em novos projetos ou projetos em que ele não foi usado anteriormente. Se você usa o gateway global do console serial, deve passar a usar como alternativa os gateways regionais. Para mais informações, consulte Descontinuação do gateway global do console serial.

Para se conectar ao gateway global do console serial, substitua REGION-ssh-serialport.googleapis.com por ssh-serialport.googleapis.com como o nome do host.

Se você estiver com problemas para se conectar usando um cliente SSH de terceiros, execute o comando gcloud compute connect-to-serial-port com a opção de linha de comando --dry-run para ver o comando SSH que seria executado em seu nome. Em seguida, compare as opções com o comando que está usando.

Como configurar uma conexão segura

Ao usar um cliente SSH de terceiros que não seja a Google Cloud CLI, é possível garantir a proteção contra falsificação de identidade ou ataques intermediários usando a verificação da chave SSH do servidor de portas seriais do Google. Para configurar seu sistema para verificar a chave SSH do servidor, conclua as seguintes etapas:

1. Faça o download da chave SSH do servidor referente ao console serial que você usará:
   • No caso das conexões regionais, a chave SSH do servidor para uma região pode ser encontrada em https://www.gstatic.com/vm_serial_port/region/region.pub.
   • No caso das conexões globais, faça o download da chave SSH do servidor de portas seriais do Google.
2. Abra seu arquivo de hosts conhecido, normalmente localizado em ~/.ssh/known_hosts.

3. Adicione o conteúdo da chave SSH do servidor, com o nome do host do servidor anexado à chave. Por exemplo, se a chave do servidor us-central1 tiver a linha ssh-rsa AAAAB3NzaC1yc..., ~/.ssh/known_hosts precisará ter uma linha semelhante ao seguinte:

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

De vez em quando, por motivos de segurança, o Google pode alterar a chave SSH do servidor de porta serial do Google. Se seu cliente não autenticar a chave do servidor, encerre imediatamente a tentativa de conexão e conclua as etapas anteriores para fazer o download de uma nova chave SSH do servidor de porta serial do Google.

Depois de atualizar a chave de host, se você continuar a receber um erro de autenticação de host de seu cliente, encerre as tentativas de conexão com a porta serial e entre em contato com o suporte do Google. Não forneça nenhuma credencial em uma conexão com falha na autenticação do host.

Como se desconectar do console serial

Para se desconectar do console serial, siga as etapas abaixo:

1. Pressione a tecla ENTER.
2. Digite ~. (til seguido de um ponto).

É possível descobrir outros comandos digitando ~? ou examinando a página principal do SSH:

man ssh

Não use nenhum destes métodos para tentar se desconectar:

• A combinação de teclas CTRL+ALT+DELETE ou outras combinações semelhantes. Isso não funciona porque o console serial não reconhece combinações de teclado do PC.

• Os comandos exit ou logout não funcionam porque o convidado não está ciente de nenhuma conexão de rede ou de modem. Usar esse comando causa o fechamento e a reabertura do console, e a conexão com a sessão permanece ativa. Para ativar os comandos exit e logout na sessão, configure a opção on-dtr-low.

Conexão com um console serial por prompt de login

Se você estiver tentando resolver um problema com uma VM que inicializou completamente ou resolver um problema que ocorre após a inicialização no modo de usuário único, talvez receba uma solicitação para inserir informações de login ao tentar acessar o console serial.

Por padrão, as imagens de sistema fornecidas pelo Google não são configuradas para permitir logins baseados em senha para usuários locais. No entanto, as imagens do Windows fornecidas pelo Google são configuradas para permitir logins baseados em senha para usuários locais.

Se a VM estiver executando uma imagem predefinida com logins de portas seriais, será necessário configurar uma senha local nela para que seja possível fazer login no console serial, se solicitado. É possível configurar uma senha local depois de se conectar à VM ou usando um script de inicialização.

Observação: essa etapa não será necessária se você interagir com o sistema durante ou antes da inicialização ou com algum serviço baseado em portas seriais que não exige uma senha. Essa etapa também não é necessária se você já configurou getty para fazer login automaticamente sem uma senha usando a flag "-a root".

Como configurar uma senha local usando um script de inicialização

É possível usar um script de inicialização para configurar uma senha local que permita a conexão com o console serial durante ou após a criação da VM.

Para configurar uma senha local em uma VM, selecione uma das seguintes opções:

Linux

1. No console do Google Cloud, acesse a página Instâncias de VMs.

   Acessar instâncias de VM

2. Na coluna Nome, clique no nome da VM em que você quer adicionar uma senha local.

   A página de detalhes da VM é aberta.

3. Clique em Editar.

   A página para editar os detalhes da VM é aberta.

4. Na seção Metadados > Automação, faça o seguinte:

   1. Se a VM tiver um script de inicialização, remova-o e armazene-o em um local seguro.

   2. Adicione o seguinte script de inicialização:

      #!/bin/bash
      useradd USERNAME
      echo USERNAME:PASSWORD | chpasswd
      usermod -aG google-sudoers USERNAME
      

      Substitua:

      • USERNAME: o nome de usuário que você quer adicionar.

      • PASSWORD: a senha do nome de usuário Como alguns sistemas operacionais exigem o comprimento mínimo e a complexidade da senha, especifique uma senha da seguinte maneira:

        • Use pelo menos 12 caracteres.

        • Use uma combinação de letras maiúsculas e minúsculas, números e símbolos.

5. Clique em Salvar.

   A página de detalhes da VM é aberta.

6. Clique em Redefinir.

7. Conecte-se ao console serial.

8. Quando solicitado, insira suas informações de login.

Windows

1. No console do Google Cloud, acesse a página Instâncias de VMs.

   Acessar instâncias de VM

2. Na coluna Nome, clique no nome da VM em que você quer adicionar uma senha local.

   A página de detalhes da VM é aberta.

3. Clique em Editar.

   A página para editar os detalhes da VM é aberta.

4. Na seção Metadados, faça o seguinte:

   1. Se a VM tiver um script de inicialização, armazene-o em um local seguro e, para excluí-lo, clique em Excluir item.

   2. Clique em Adicionar item.

   3. No campo Chave, digite windows-startup-script-cmd.

   4. No campo Valor, insira este script:

      net user USERNAME PASSWORD /ADD /Y
      net localgroup administrators USERNAME /ADD
      

      Substitua:

      • USERNAME: o nome de usuário que você quer adicionar.

      • PASSWORD: a senha do nome de usuário Como alguns sistemas operacionais exigem o comprimento mínimo e a complexidade da senha, especifique uma senha da seguinte maneira:

        • Use pelo menos 12 caracteres.

        • Use uma combinação de letras maiúsculas e minúsculas, números e símbolos.

5. Clique em Salvar.

   A página de detalhes da VM é aberta.

6. Clique em Redefinir.

7. Conecte-se ao console serial.

8. Quando solicitado, insira suas informações de login.

Depois que o usuário for criado, substitua o script de inicialização pelo script armazenado nesta seção.

Como configurar uma senha local usando passwd na VM

As instruções a seguir descrevem como configurar uma senha local para um usuário em uma VM para que o usuário possa fazer login no console serial dessa VM usando a senha especificada.

1. Conecte-se à VM. Substitua instance-name pelo nome da instância.

   gcloud compute ssh instance-name

2. Na instância, crie uma senha local com o comando a seguir. Isso define uma senha para o usuário utilizado para a conexão atual.

   sudo passwd $(whoami)

3. Siga os prompts para criar uma senha.

4. Em seguida, saia da instância e estabeleça conexão com o console serial.

5. Insira suas informações de login quando solicitado.

Como configurar um login em outras portas seriais

Por padrão, os prompts de login estão ativados na porta 1 na maioria dos sistemas operacionais Linux. Contudo, a porta 1 pode ficar sobrecarregada registrando dados e outras informações enviadas para ela. Em vez disso, opte por ativar um prompt de login em outra porta, como a porta 2 (ttyS1), executando um dos seguintes comandos na VM. É possível ver uma lista das portas disponíveis para uma VM em Noções básicas sobre a numeração de portas seriais.

A tabela a seguir relaciona as imagens pré-configuradas com um login do console serial e as portas padrão.

Sistema operacional	Portas com um prompt de login por padrão	Gerenciamento de serviços
CentOS 6	1	upstart
CentOS 7	1	systemd
CoreOS	1	systemd
COS	1	systemd
Debian 8	1	systemd
Debian 9	1	systemd
OpenSUSE 13	1	systemd
OpenSUSE Leap	1	systemd
RHEL 6	1	upstart
RHEL 7	1	systemd
SLES 11	1	sysvinit
SLES 12	1	systemd
Ubuntu 14.04	1	upstart
Ubuntu 16.04	1	systemd
Ubuntu 17.04	1	systemd
Ubuntu 17.10	1	systemd
Windows	COM2	N/A

Para ativar solicitações de login em mais portas seriais, siga as instruções abaixo.

Observação: as instruções a seguir são divididas entre sistemas operacionais que executam systemd, upstart ou sysvinit. Para todos os conjuntos de instruções, é possível substituir ttyS1 por outra porta serial se quiser.

systemd

Para sistemas operacionais Linux que usam systemd, siga estas instruções:

• Ative o serviço temporariamente até a próxima reinicialização:

  sudo systemctl start [e-mail]

• Ative o serviço permanentemente, a partir da próxima reinicialização:

  sudo systemctl enable [e-mail]

upstart

Para sistemas operacionais Linux que usam upstart, siga estas instruções:

1. Crie um novo arquivo /etc/init/ttyS1.conf para refletir ttyS1 copiando e modificando um arquivo ttyS0.conf. Exemplo:

   • No Ubuntu 14.04:

     sudo sh -c "sed -e s/ttyS0/ttyS1/g < /etc/init/ttyS0.conf > /etc/init/ttyS1.conf"

     Observação: o Ubuntu 12.04 não tem um ttyS0.conf, portanto o Google recomenda copiar o arquivo ttysS0.conf do Ubuntu 14.04 e usá-lo na instância em que o Ubuntu 12.04 é executado.

   • No RHEL 6.8 e no CentOS 6.8:

     sudo sh -c "sed -ne '/^# # ttyS0/,/^# exec/p'  < /etc/init/serial.conf  | sed -e 's/ttyS0/ttyS1/g' -e 's/^# *//' > /etc/init/ttyS1.conf"

2. Inicie uma solicitação de login em ttyS1 sem reiniciar:

   sudo start ttyS1

sysvinit

Para sistemas operacionais Linux que usam sysvinit, execute o seguinte comando:

 sudo sed -i~ -e 's/^#T([01])/T\1/' /etc/inittab
 sudo telinit q

Como entender a numeração de portas seriais

Cada instância de máquina virtual tem quatro portas seriais. Para manter a consistência com a API getSerialPortOutput, cada porta é numerada de 1 a 4. O Linux e outros sistemas parecidos numeram as portas seriais de 0 a 3. Por exemplo, em muitas imagens de sistema operacional, os dispositivos correspondentes vão de /dev/ttyS0 a /dev/ttyS3. O Windows faz referência às portas seriais de COM1 a COM4. Para estabelecer conexão com o que o Windows considera como COM3 e o Linux considera como ttyS2, você especificaria a porta 3. Use a tabela a seguir para descobrir a qual porta você deve se conectar.

Portas seriais da instância de máquina virtual	Portas seriais padrão do Linux	Portas COM do Windows
1	/dev/ttyS0	COM1
2	/dev/ttyS1	COM2
3	/dev/ttyS2	COM3
4	/dev/ttyS3	COM4

Note que muitas imagens do Linux usam a porta 1 (/dev/ttyS0) para gerar registros de mensagens provenientes do kernel e dos programas do sistema.

Como enviar uma interrupção serial

O recurso chave Magic SysRq permite realizar tarefas simples, independentemente do estado do sistema. Por exemplo, é possível sincronizar sistemas de arquivos, reinicializar a instância, encerrar processos e desativar sistemas de arquivos usando o recurso de chave Magic SysRq.

Para enviar um comando Magic SysRq usando uma interrupção serial simulada, siga as etapas abaixo:

1. Pressione a tecla ENTER.
2. Digite ~B (til seguido de B maiúsculo).
3. Digite o comando Magic SysRq.

Observação: a chave Magic SysRq normalmente é implementada usando os códigos de verificação do teclado do computador, mas não há equivalente direto em uma porta serial. Esse é o método recomendado de acesso ao recurso Magic SysRq.

Como visualizar registros de auditoria do console serial

O Compute Engine fornece registros de auditoria para rastrear quem estabeleceu e encerrou uma conexão com o console serial de uma instância. Para ver os registros, é preciso ter permissões para o Logs Viewer ou ser um visualizador ou editor do projeto.

1. No Console do Google Cloud, acesse a página do Explorador de registros.

   Acessar a ferramenta Análise de registros

2. Expanda o menu suspenso e selecione GCE VM Instance.
3. Na barra de pesquisa, digite ssh-serialport.googleapis.com e pressione Enter.

4. Uma lista de registros de auditoria é exibida. Os registros descrevem conexões e desconexões de um console serial. Expanda qualquer uma das entradas para mais informações:

   

Em qualquer um dos registros de auditoria, é possível realizar estas ações:

1. Expandir a propriedade protoPayload.
2. Procurar por methodName para ver a atividade à qual esse registro se aplica. Pode ser uma solicitação de conexão ou desconexão. Por exemplo, se o registro rastrear uma desconexão do console serial, o nome do método será "google.ssh-serialport.v1.disconnect". Da mesma forma, um registro de conexão seria "google.ssh-serialport.v1.connect". Uma entrada no registro de auditoria é registrada no início e no fim de cada sessão no console serial.

Há diferentes propriedades de registros de auditoria para tipos de registro distintos. Por exemplo, os registros de auditoria relacionados às conexões têm propriedades específicas dos registros de conexão, enquanto os registros de auditoria para desconexões têm seu próprio conjunto de propriedades. Há algumas propriedades que também são compartilhadas entre ambos os tipos de registro.

Todos os registros do console serial

A tabela a seguir fornece propriedades do registro de auditoria e os respectivos valores para todos os registros do console serial:

Propriedade	Valor
requestMetadata.callerIp	O endereço IP e o número da porta de origem da conexão.
serviceName	ssh-serialport.googleapis.com
resourceName	Uma string que contém o ID do projeto, a zona, o nome da instância e o número da porta serial para indicar a que console serial pertence. Por exemplo, projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2 é a porta número 2, também conhecida como COM2 ou /dev/ttyS1, para a instância example-instance.
resource.labels	Propriedades que identificam o ID da instância, a zona e o ID do projeto.
timestamp	Carimbo de data e hora que indica quando a sessão começou ou terminou.
severity	NOTICE
operation.id	Uma string de ID que identifica exclusivamente a sessão. Use-a para associar uma entrada de desconexão à entrada de conexão correspondente.
operation.producer	ssh-serialport.googleapis.com

Registros de conexão

A tabela a seguir fornece propriedades de registro de auditoria e os respectivos valores específicos para registros de conexão:

Propriedade	Valor
methodName	google.ssh-serialport.v1.connect
status.message	Connection succeeded.
request.serialConsoleOptions	Quaisquer opções especificadas com a solicitação, incluindo o número da porta serial.
request.@type	type.googleapis.com/google.compute.SerialConsoleSessionBegin
request.username	O nome de usuário especificado para essa solicitação. Ele é usado para selecionar a chave pública correspondente.
operation.first	TRUE
status.code	Para solicitações de conexão bem-sucedidas, o valor status.code de google.rpc.Code.OK indica a conclusão da operação sem nenhum erro. Como o valor da enum desta propriedade é 0, a propriedade status.code não é exibida. No entanto, qualquer código que confirmar um valor status.code de google.rpc.Code.OK funcionará conforme o esperado.

Registros de desconexão

A tabela a seguir fornece propriedades do registro de auditoria e os respectivos valores específicos para registros de desconexão:

Propriedade	Valor
methodName	google.ssh-serialport.v1.disconnect
response.duration	O tempo, em segundos, que a sessão durou.
response.@type	type.googleapis.com/google.compute.SerialConsoleSessionEnd
operation.last	TRUE

Registros de falhas na conexão

Quando ocorre falha na conexão, o Compute Engine cria uma entrada no registro de auditoria. O registro de uma falha na conexão é bem parecido com a entrada de uma conexão bem-sucedida, mas tem as propriedades a seguir para indicar a falha na conexão.

Propriedade	Valor
severity	ERROR
status.code	O código de erro canônico da Google API que melhor descreve o erro. Os itens a seguir são possíveis códigos de erro que podem ser exibidos: google.rpc.Code.INVALID_ARGUMENT: a conexão falhou porque o cliente forneceu um número de porta inválido ou tentou alcançar um canal desconhecido. Consulte a lista de números de porta válidos. google.rpc.Code.PERMISSION_DENIED: você não ativou o console serial interativo no servidor de metadados. Para mais informações, consulte Como ativar o acesso interativo no console serial. google.rpcCode.UNAUTHENTICATED: nenhuma chave SSH foi encontrada ou não há chave SSH correspondente para essa instância. Verifique se você está autenticado na instância de VM. google.rpc.Code.UNKNOWN: ocorreu um erro desconhecido na sua solicitação. Informe ao Google no grupo gce-discussion ou envie um relatório do bug.
status.message	A mensagem legível referente a essa entrada.

Como desativar o acesso ao console serial interativo

Você pode desativar o acesso ao console serial interativo alterando metadados na instância ou no projeto específico ou definindo uma política da organização que desativa o acesso ao console serial interativo para todas as instâncias de VM de um ou mais projetos que fazem parte da organização.

Como desativar o console serial interativo em uma instância ou projeto específico

Proprietários e editores do projeto, bem como usuários que receberam o papel compute.instanceAdmin.v1, podem desativar o acesso ao console serial alterando os metadados na instância ou projeto específico. De maneira semelhante à ativação do acesso ao console serial, defina os metadados serial-port-enable como FALSE:

serial-port-enable=FALSE

Por exemplo, usando a Google Cloud CLI, é possível aplicar esses metadados a uma instância específica, como:

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

Para aplicar os metadados ao projeto:

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

Como desativar o acesso ao console serial interativo por meio da política da organização

Se você tiver recebido o papel orgpolicy.policyAdmin na organização, defina uma política da organização que impeça o acesso interativo ao console serial, independentemente do acesso ao console serial interativo estar ativado no servidor de metadados. Depois que a política da organização for definida, ela modificará efetivamente a chave de metadados serial-port-enable, e nenhum usuário da organização ou projeto poderá ativar o acesso ao console serial interativo. Por padrão, essa restrição é definida como FALSE.

A restrição para desativar o acesso ao console serial interativo é a seguinte:

compute.disableSerialPortAccess

Conclua as instruções a seguir para definir essa política na organização. Depois de configurar uma política, é possível conceder isenções por projeto.

gcloud

Para definir a política usando a Google Cloud CLI, execute o comando resource-manager enable-enforce. Substitua organization-id pelo ID da organização. Por exemplo, 1759840282.

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

REST

Para definir uma política na API, faça uma solicitação POST ao seguinte URL: Substitua organization-name pelo nome da organização. Por exemplo, organizations/1759840282.

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

O corpo da solicitação precisa conter um objeto policy com a seguinte restrição:

"constraint": "constraints/compute.disableSerialPortAccess"

Exemplo:

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

A política entra em vigor imediatamente. Por isso, os projetos sob a organização deixam de permitir o acesso interativo ao console serial.

Para desativar temporariamente a política, use o comando disable-enforce:

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

Como alternativa, faça uma solicitação de API em que o corpo da solicitação define o parâmetro enforced como FALSE:

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

Como definir a política da organização para envolvidos no projeto

Você pode definir a mesma política organizacional por projeto. Isso substitui a definição no nível da organização.

gcloud

Para desativar a aplicação dessa política para um projeto específico, use o comando a seguir. Substitua project-id pelo ID do projeto.

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

É possível ativar a aplicação dessa política usando o comando enable-enforce com os mesmos valores.

REST

Na API, faça uma solicitação POST para seguinte URL a fim de ativar o acesso ao console serial interativo para projeto, substituindo project-id pelo ID do projeto:

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

O corpo da solicitação precisa conter um objeto policy com a seguinte restrição:

"constraint": "constraints/compute.disableSerialPortAccess"

Exemplo:

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

Dicas e sugestões

• Se estiver com dificuldade para se conectar usando um cliente SSH padrão, mas o comando gcloud compute connect-to-serial-port fizer isso com sucesso, pode ser útil executar gcloud compute connect-to-serial-port com a opção de linha de comando --dry-run para ver o comando SSH que teria sido executado em seu nome e comparar as opções dele às do comando que você está usando.

• Configuração da taxa de bits, também conhecida como "baud rate": é possível definir a taxa de bits que quiser, como stty 9600, mas o recurso normalmente força a taxa efetiva para 115.200 bps (aproximadamente 11,5 kB/s). Isso ocorre porque muitas imagens públicas usam taxas de bits baixas por padrão no console serial, como 9.600, o que causa uma inicialização lenta.

• Algumas imagens de SO têm padrões inadequados na porta serial. Por exemplo, no CentOS 7, o padrão de stty icrnl para a tecla Enter no console é enviar um CR, também conhecido como ^M. O shell de Bash pode mascarar isso até você tentar definir uma senha. Nesse momento, você se perguntará por que ele aparenta estar parado no prompt password:.

• Algumas imagens públicas têm chaves de controle de job que serão desativadas por padrão se você anexar um shell a uma porta usando determinadas maneiras. Alguns exemplos dessas chaves incluem ^Z e ^C. O comando setsid pode corrigir isso. Caso contrário, se você receber uma mensagem job control is disabled in this shell, tome cuidado para não executar comandos que precisará interromper.

• Pode ser útil informar ao sistema o tamanho da janela que você está usando, assim o Bash e os editores podem gerenciá-la corretamente. Caso contrário, é possível notar um comportamento de exibição estranho porque o Bash ou os editores tentam manipular a exibição com base em suposições incorretas sobre o número de linhas e colunas disponíveis. Use o comando stty rows Y cols X e a sinalização stty -a para ver qual é a configuração. Por exemplo: stty rows 60 cols 120, se sua janela tiver 120 caracteres por 60 linhas.

• Se, por exemplo, você se conectar usando SSH da máquina A à máquina B e, depois, à máquina C criando uma sessão SSH aninhada e quiser usar comandos til (~) para se desconectar ou enviar um sinal de interrupção serial, será preciso adicionar caracteres til extras o suficiente ao comando para acessar o cliente SSH correto. Um comando após um único til é interpretado pelo cliente SSH na máquina A, um comando após dois tis consecutivos (Enter~~) é interpretado pelo cliente na máquina B e assim por diante. Você só precisa pressionar Enter uma vez, porque ele é totalmente transmitido para o destino SSH mais interno. Isso é válido para qualquer uso de clientes SSH que forneçam o recurso til de escape.

  Se você perder a conta do número de caracteres til necessários, pressione a tecla Enter e digite os caracteres til, um de cada vez, até que a instância retorne o til novamente. Esse eco indica que você chegou ao fim da cadeia e agora sabe que para enviar um comando til ao cliente SSH mais aninhado, você precisa de um til a menos do que o número de tis digitado.

Opções avançadas

Também é possível usar as opções avançadas a seguir com a porta serial.

Controle do máximo de conexões

É possível definir a propriedade max-connections para controlar quantas conexões simultâneas podem ser estabelecidas nessa porta serial em um período. O número padrão e máximo de conexões é 5. Exemplo:

gcloud compute connect-to-serial-port instance-name \
    --port port-number \
    --extra-args max-connections=3

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.max-connections=[e-mail]

Configuração de opções de nova reprodução

Por padrão, sempre que você se conectar ao console serial, receberá uma nova reprodução das últimas 10 linhas de dados, independentemente de terem sido vistas por outro cliente SSH. É possível alterar essa configuração e controlar quantas e quais linhas são retornadas configurando as seguintes opções:

• replay-lines=N: defina N como o número de linhas que você quer reproduzir novamente. Por exemplo, se N for 50, as últimas 50 linhas da saída do console serão incluídas.
• replay-bytes=N: reproduz os bytes N mais recentes. Também é possível definir N como new, o que reproduz novamente toda a saída que não foi enviada ainda a nenhum cliente.
• replay-from=N: reproduz a saída a partir de um índice de byte absoluto fornecido. Para receber o índice de byte atual da saída do console serial, faça uma solicitação getSerialPortOutput. Se você definir replay-from, todas as outras opções de reprodução serão ignoradas.

Com a Google Cloud CLI, anexe a opção a seguir ao comando connect-to-serial-port, em que N é o número especificado de linhas, ou bytes ou índice de byte absoluto, dependendo da opção de nova reprodução selecionada:

--extra-args replay-lines=N

Se estiver usando um cliente SSH de terceiros, forneça esta opção em seu comando SSH:

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.replay-lines=[e-mail]

Também é possível usar uma combinação dessas opções. Exemplo:

replay-lines=N e replay-bytes=new

Reproduzem o número especificado de linhas ou reproduzem novamente toda a saída não enviada anteriormente a nenhum cliente, o que for maior. O primeiro cliente a estabelecer conexão com essa combinação de sinalizações verá que toda a saída foi enviada para a porta serial, e os clientes que estabelecerem conexão posteriormente verão somente as últimas N linhas. Exemplos:

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

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.replay-lines=N.replay-bytes=[e-mail]

replay-lines=N e replay-bytes=M

Reproduzem novamente o número de linhas ou bytes descritos por essas sinalizações, o que for menor. Essa opção não vai reproduzir mais do que N ou M bytes.

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

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.replay-lines=N.replay-bytes=[e-mail]

Como processar a saída eliminada

O 1 MiB de saída mais recente de cada porta serial sempre está disponível e, em geral, o cliente SSH não perde nenhuma saída da porta serial. Se, por algum motivo, seu cliente SSH deixar de aceitar a saída por um período, mas não encerrar a conexão, e mais de 1 MiB de novos dados for produzido, ele poderá perder esses dados. Quando seu cliente SSH não estiver aceitando dados com rapidez o suficiente para acompanhar a saída na porta serial do console, defina a propriedade on-dropped-output para determinar o comportamento do console.

Defina qualquer uma das seguintes opções aplicáveis com esta propriedade:

• insert-stderr-note: insira uma observação no stderr do cliente SSH, indicando que a saída foi eliminada. Essa é a opção padrão.
• ignore: elimina a saída silenciosamente e não executa nenhuma ação.
• disconnect: interrompe a conexão.

Exemplo:

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

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.on-dropped-output=[e-mail]

Como ativar a desconexão usando os comandos exit ou logout

É possível ativar a desconexão nos comandos exit ou logout configurando a propriedade on-dtr-low como disconnect ao estabelecer conexão com o console serial.

Na Google Cloud CLI, anexe a seguinte sinalização ao seu comando connect-to-serial-port:

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

Se estiver usando um cliente SSH de terceiros, forneça esta opção em seu comando SSH:

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.on-dtr-low=[e-mail]

Ativar a opção disconnect pode fazer com que sua instância se desconecte uma ou mais vezes quando você reinicia a instância porque o sistema operacional redefine as portas seriais durante a inicialização.

Observação: em alguns sistemas operacionais, essa configuração não tem efeito na porta serial 1. No entanto, ele precisaria funcionar nas portas 2 a 4 para a maioria dos sistemas operacionais e na porta 1 para alguns sistemas.

A configuração padrão da opção on-dtr-low é none. Se você usar a configuração padrão none, poderá reinicializar a instância sem que ela seja desconectada do console serial, mas o console não se desconectará por meios normais, como os comandos exit ou logout, ou combinações de teclas normais, como Ctrl + D.

A seguir

• Saiba mais sobre a API getSerialPortOutput.
• Saiba como reter e visualizar a saída da porta serial mesmo após uma instância de VM ter sido excluída.
• Leia mais sobre dicas para solução de problemas.
• Saiba mais sobre a aplicação de metadados.
• Saiba mais sobre chaves SSH.