Resolução de problemas através da consola de série

Esta página descreve como ativar o acesso interativo à consola em série de uma instância para depurar problemas de arranque e de rede, resolver problemas de instâncias com mau funcionamento, interagir com o GRand Unified Bootloader (GRUB) e realizar outras tarefas de resolução de problemas.

Uma instância de máquina virtual (VM) tem quatro portas de série virtuais. A interação com uma porta série é semelhante à utilização de uma janela de terminal, uma vez que a entrada e a saída são totalmente no modo de texto e não existe uma interface gráfica nem suporte do rato. O sistema operativo, o BIOS e outras entidades ao nível do sistema da instância escrevem frequentemente resultados nas portas série e podem aceitar entradas, como comandos ou respostas a comandos. Normalmente, estas entidades ao nível do sistema usam a primeira porta de série (porta 1) e a porta de série 1 é frequentemente referida como a consola de série.

Se só precisar de ver a saída da porta de série sem emitir comandos para a consola de série, pode chamar o método getSerialPortOutput ou usar o Cloud Logging para ler informações que a sua instância escreveu na respetiva porta de série. Consulte o artigo Ver registos da porta de série. No entanto, se tiver problemas ao aceder à sua instância através do SSH ou precisar de resolver problemas de uma instância que não foi totalmente iniciada, pode ativar o acesso interativo à consola série, que lhe permite ligar-se e interagir com qualquer uma das portas série da sua instância. Por exemplo, pode executar comandos diretamente e responder a comandos na porta série.

Quando ativa ou desativa a porta de série, pode usar qualquer valor booleano que seja aceite pelo servidor de metadados. Para mais informações, consulte Valores booleanos.

Antes de começar

  • Se ainda não o tiver feito, configure a autenticação. A autenticação valida a sua identidade para aceder a Google Cloud serviços e APIs. Para executar código ou exemplos a partir de um ambiente de desenvolvimento local, pode autenticar-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. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    2. Set a default region and zone.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

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

Ativar o acesso interativo na consola de série

Ative o acesso interativo à consola de série para instâncias de VM individuais ou para um projeto inteiro.

Ativar o acesso para um projeto

A ativação do acesso interativo à consola de série num projeto permite o acesso a todas as instâncias de VM que fazem parte desse projeto.

Por predefinição, o acesso interativo à porta de série está desativado. Também pode desativá-lo explicitamente definindo a chave serial-port-enable como FALSE. Em qualquer dos casos, qualquer definição por instância substitui a definição ao nível do projeto ou a predefinição.

Consola

  1. Na Google Cloud consola, aceda à página Metadados.

    Aceda aos metadados

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

gcloud

Usando a CLI do Google Cloud, introduza o comando project-info add-metadata da seguinte forma:

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

REST

Na API, faça um pedido ao método projects().setCommonInstanceMetadata fornecendo a chave serial-port-enable com um valor de TRUE:

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

Ativar o acesso para uma instância de VM

Ative o acesso interativo à consola de série para uma instância específica. Uma definição por instância, se existir, substitui qualquer definição ao nível do projeto. Também pode desativar o acesso para uma instância específica, mesmo que o acesso esteja ativado ao nível do projeto, definindo serial-port-enable como FALSE, em vez de TRUE. Da mesma forma, pode ativar o acesso para uma ou mais instâncias, mesmo que esteja desativado para o projeto, explícita ou predefinição.

Consola

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceda à página de instâncias de VM

  2. Clique na instância para a qual quer ativar o acesso.
  3. Clique em Edit.
  4. Na secção Acesso remoto, ative/desative a caixa de verificação Permitir a ligação a portas série.
  5. Guarde as alterações.

gcloud

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

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

REST

Na API, faça um pedido ao 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"
  }
 ]
}

Configure a consola de série para uma instância bare metal

Para instâncias bare metal, aumente a taxa de bits, também conhecida como taxa de transmissão, para a consola série para 115 200 bps (~11,5 kB/seg). A utilização de uma velocidade mais lenta resulta numa saída da consola confusa ou em falta.

A configuração do carregador de arranque varia entre sistemas operativos e versões do SO. Consulte a documentação do distribuidor do SO para ver instruções.

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

console=ttyS0,115200

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

serial --speed=115200

Certifique-se de que atualiza a configuração real do carregador de arranque. Isto pode ser feito com update-grub, grub2-mkconfig ou um comando semelhante.

Estabelecer ligação a uma consola de série

O Compute Engine oferece gateways de consola de série regionais para cada Google Cloud região. Depois de ativar o acesso interativo para a consola de série de uma VM, pode estabelecer ligação a uma consola de série regional.

A consola série autentica os utilizadores com chaves SSH. Em concreto, tem de adicionar a sua chave SSH pública aos metadados do projeto ou da instância e armazenar a chave privada na máquina local a partir da qual quer estabelecer ligação. A CLI gcloud e a Google Cloud consola adicionam automaticamente chaves SSH ao projeto. Se estiver a usar um cliente de terceiros, pode ter de adicionar chaves SSH manualmente.

Se estiver a usar um cliente de terceiros, também pode validar a ligação através das chaves do anfitrião da consola série. Quando usa a CLI do Google Cloud para estabelecer ligação, a autenticação de chaves de anfitrião é feita automaticamente em seu nome.

Consola

Para se ligar à consola série regional de uma VM, faça o seguinte:

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceda à página de instâncias de VM

  2. Clique na instância à qual quer estabelecer ligação.
  3. Em Detalhes, clique em Ligar à consola de série para se ligar à porta predefinida (porta 1).
  4. Se quiser estabelecer ligação a outra porta de série, clique na seta para baixo junto ao botão Ligar à consola de série e altere o número da porta em conformidade.
  5. Para instâncias do Windows, abra o menu pendente junto ao botão e ligue-se à porta 2 para aceder à consola série.

gcloud

Para estabelecer ligação à consola série 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 o seguinte:

  • VM_NAME: o nome da VM à qual quer estabelecer ligação à consola de série.

  • PORT_NUMBER: o número da porta à qual quer estabelecer ligação. Para VMs do Linux, use 1. Para VMs do Windows, use 2. Para saber mais sobre os números de porta, consulte o artigo Compreender a numeração de portas de série.

Outros clientes SSH

Pode ligar-se à consola série de uma instância através de outros clientes SSH de terceiros, desde que o cliente lhe permita ligar-se à porta TCP 9600. Antes de se ligar, pode, opcionalmente, validar a ligação através das chaves do anfitrião da consola série.

Para se ligar à consola série regional de uma VM, execute um dos seguintes comandos, consoante o SO da VM:

  • Para estabelecer ligação a uma VM do Linux:

    ssh -i PRIVATE_SSH_KEY_FILE -p 9600 PROJECT_ID.ZONE.VM_NAME.USERNAME.OPTIONS@REGION-ssh-serialport.googleapis.com

  • Para estabelecer ligação a uma VM do Windows:

    ssh -i PRIVATE_SSH_KEY_FILE -p 9600 PROJECT_ID.ZONE.VM_NAME.USERNAME.OPTIONS.port=2@REGION-ssh-serialport.googleapis.com

Substitua o seguinte:

  • PRIVATE_SSH_KEY_FILE: a chave SSH privada da instância.
  • PROJECT_ID: o ID do projeto desta 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 utilizador que está a usar para se ligar à sua instância. Normalmente, este é o nome de utilizador na sua máquina local.
  • OPTIONS: opções adicionais que pode especificar para esta associação. Por exemplo, pode especificar uma determinada porta série e especificar qualquer opção avançada. O número da porta pode ser de 1 a 4, inclusive. Para saber mais sobre os números de porta, consulte o artigo Compreender a numeração de portas série. Se for omitido, estabelece ligação à porta de série 1.

Se tiver problemas ao estabelecer ligação através de um cliente SSH de terceiros, pode executar o comando gcloud compute connect-to-serial-port com a opção de linha de comandos --dry-run para ver o comando SSH que teria sido executado em seu nome. Em seguida, pode comparar as opções com o comando que está a usar.

Valide as ligações de clientes SSH de terceiros

Quando usa um cliente SSH de terceiros que não seja a CLI Google Cloud, recomendamos que verifique se está protegido contra roubo de identidade ou ataques man-in-the-middle, verificando a chave de anfitrião SSH da porta série da Google. Para configurar o seu sistema para verificar a chave do anfitrião SSH, conclua os seguintes passos:

  1. Transfira a chave de anfitrião SSH para a consola de série que vai usar:

  2. Abra o ficheiro de anfitriões conhecidos, geralmente localizado em ~/.ssh/known_hosts.

  3. Adicione o conteúdo da chave do anfitrião SSH, com o nome do anfitrião do servidor adicionado à chave. Por exemplo, se a chave do servidor us-central1 contiver a linha ssh-rsa AAAAB3NzaC1yc..., ~/.ssh/known_hosts deve ter uma linha semelhante a esta:

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

Por motivos de segurança, a Google pode alterar ocasionalmente a chave do anfitrião SSH da porta série da Google. Se o seu cliente não conseguir autenticar a chave do servidor, termine imediatamente a tentativa de ligação e conclua os passos anteriores para transferir uma nova chave de anfitrião SSH da porta série da Google.

Se, após atualizar a chave do anfitrião, continuar a receber um erro de autenticação do anfitrião do cliente, pare as tentativas de ligação à porta série e contacte o apoio técnico da Google. Não faculte credenciais através de uma ligação em que a autenticação do anfitrião tenha falhado.

Desligar-se da consola de série

Para desligar da consola série, siga as instruções do método que usou para estabelecer ligação.

Consola

Na Google Cloud consola, desassocie-se da consola de série fazendo o seguinte:

  1. Feche o separador ou a janela do navegador que contém a ligação à consola série.

gcloud

Na CLI do Google Cloud, desassocie-se da consola série fazendo o seguinte:

  1. Prima a tecla ENTER.
  2. Escreva ~. (til, seguido de um ponto).

Outros clientes SSH

Noutros clientes SSH, desligue-se da consola série da seguinte forma:

  1. Prima a tecla ENTER.
  2. Escreva ~. (til, seguido de um ponto).

Na CLI do Google Cloud ou através de SSH, pode descobrir outros comandos escrevendo ~?. Também pode examinar a página de manual do SSH com o seguinte comando:

man ssh

Não tente desassociar a conta através de nenhum dos seguintes métodos:

  • A combinação de teclas CTRL+ALT+DELETE ou outras combinações semelhantes. Isto não funciona porque a consola série não reconhece combinações de teclas do teclado do PC.

  • O comando exit ou logout não funciona porque o convidado não tem conhecimento de nenhuma ligação de rede ou modem. A utilização deste comando faz com que a consola seja fechada e, em seguida, reaberta, e permanece com ligação à sessão. Se quiser ativar os comandos exit e logout para a sua sessão, pode ativá-los definindo a opção on-dtr-low.

Estabelecer ligação a uma consola de série com um pedido de início de sessão

Se estiver a tentar resolver um problema com uma VM que tenha sido iniciada completamente ou a resolver um problema que ocorra depois de a VM ter sido iniciada no modo de utilizador único, pode ser-lhe pedido que introduza informações de início de sessão quando tentar aceder à consola série.

Por predefinição, as imagens do sistema Linux fornecidas pela Google não estão configuradas para permitir inícios de sessão baseados em palavras-passe para utilizadores locais. No entanto, as imagens do Windows fornecidas pela Google estão configuradas para permitir inícios de sessão baseados em palavras-passe para utilizadores locais.

Se a sua VM estiver a executar uma imagem pré-configurada com inícios de sessão na porta série, tem de configurar uma palavra-passe local na VM para poder iniciar sessão na consola série, se lhe for pedido. Pode configurar uma palavra-passe local depois de estabelecer ligação à VM ou através de um script de arranque.

Configurar uma palavra-passe local através de um script de arranque

Pode usar um script de arranque para configurar uma palavra-passe local que lhe permita estabelecer ligação à consola série durante ou após a criação da VM.

Para configurar uma palavra-passe local numa VM existente, selecione uma das seguintes opções:

Linux

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceder às instâncias de VM

  2. Na coluna Nome, clique no nome da MV à qual quer adicionar uma palavra-passe local.

    É apresentada a página de detalhes da VM.

  3. Clique em Editar.

    É aberta a página para editar os detalhes da VM.

  4. Na secção Metadados > Automatização, faça o seguinte:

    1. Se a VM tiver um script de arranque existente, remova-o e armazene-o num local seguro.

    2. Adicione o seguinte script de arranque:

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

      Substitua o seguinte:

      • USERNAME: o nome de utilizador que quer adicionar.

      • PASSWORD: a palavra-passe do nome de utilizador. Como alguns sistemas operativos requerem um comprimento e uma complexidade mínimos da palavra-passe, especifique uma palavra-passe da seguinte forma:

        • Use, pelo menos, 12 carateres.

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

  5. Clique em Guardar.

    É apresentada a página de detalhes da VM.

  6. Clique em Repor.

  7. Ligue-se à consola de série.

  8. Quando lhe for pedido, introduza as suas informações de início de sessão.

Windows

  1. Na Google Cloud consola, aceda à página Instâncias de VM.

    Aceder às instâncias de VM

  2. Na coluna Nome, clique no nome da MV à qual quer adicionar uma palavra-passe local.

    É apresentada a página de detalhes da VM.

  3. Clique em Editar.

    É aberta a página para editar os detalhes da VM.

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

    1. Se a VM tiver um script de arranque existente, armazene o script num local seguro e, em seguida, para eliminar o script, clique em Eliminar item.

    2. Clique em Adicionar item.

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

    4. No campo Valor, introduza o seguinte script:

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

      Substitua o seguinte:

      • USERNAME: o nome de utilizador que quer adicionar.

      • PASSWORD: a palavra-passe do nome de utilizador. Como alguns sistemas operativos requerem um comprimento e uma complexidade mínimos da palavra-passe, especifique uma palavra-passe da seguinte forma:

        • Use, pelo menos, 12 carateres.

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

  5. Clique em Guardar.

    É apresentada a página de detalhes da VM.

  6. Clique em Repor.

  7. Ligue-se à consola de série.

  8. Quando lhe for pedido, introduza as suas informações de início de sessão.

Depois de criar o utilizador, substitua o script de arranque pelo script de arranque que armazenou nesta secção.

Configurar uma palavra-passe local através do passwd na VM

As instruções seguintes descrevem como configurar uma palavra-passe local para um utilizador numa VM, para que o utilizador possa iniciar sessão na consola série dessa VM através da palavra-passe especificada.

  1. Estabeleça ligação à VM. Substitua instance-name pelo nome da sua instância.

    gcloud compute ssh instance-name

  2. Na VM, crie uma palavra-passe local com o seguinte comando. Esta ação define uma palavra-passe para o utilizador com sessão iniciada.

    sudo passwd $(whoami)

  3. Siga as instruções para criar uma palavra-passe.

  4. Em seguida, termine sessão na instância e ligue-se à consola série.

  5. Introduza as suas informações de início de sessão quando lhe for pedido.

Configurar um início de sessão noutras portas de série

As mensagens de início de sessão estão ativadas na porta 1 por predefinição em todas as imagens públicas do Linux que usam a gestão de serviços systemd. Para imagens do Windows, os pedidos de início de sessão estão ativados na porta 2 por predefinição e são geridos pelo Gestor de dispositivos. No entanto, a porta 1 pode ficar frequentemente sobrecarregada com dados de registo e outras informações impressas na porta. Em alternativa, pode optar por ativar um pedido de início de sessão noutra porta, como a porta 2 (ttyS1), executando o seguinte comando na sua VM:

Linux

Para sistemas operativos Linux que usam o systemd:

  • Ative o serviço temporariamente até ao próximo reinício:

    sudo systemctl start serial-getty@ttyS1.service

  • Ative o serviço permanentemente, começando com o próximo reinício:

    sudo systemctl enable serial-getty@ttyS1.service

Windows

Para sistemas operativos Windows:

  • Abra a Linha de comandos como administrador

  • Altere a porta EMS de COM2 para COM1:

    bcdedit /emssettings EMSPORT:1 EMSBAUDRATE:9600

  • Reiniciar a VM

Compreender a numeração das portas de série

Cada instância de máquina virtual tem quatro portas de série. Para manter a consistência com a API getSerialPortOutput, cada porta é numerada de 1 a 4. O Linux e outros sistemas semelhantes numeram as portas série de 0 a 3. Por exemplo, em muitas imagens de sistemas operativos, os dispositivos correspondentes são /dev/ttyS0 a /dev/ttyS3. O Windows refere-se às portas série como COM1 a COM4. Para se ligar ao que o Windows considera COM3 e o Linux considera ttyS2, deve especificar a porta 3. Use a tabela seguinte para ajudar a determinar a porta à qual quer estabelecer ligação.

Portas de série de instâncias de máquinas virtuais Portas de série Linux padrão Portas COM do Windows
1 /dev/ttyS0 COM1
2 /dev/ttyS1 COM2
3 /dev/ttyS2 COM3
4 /dev/ttyS3 COM4

Tenha em atenção que muitas imagens do Linux usam a porta 1 (/dev/ttyS0) para registar mensagens do kernel e dos programas do sistema.

Enviar uma pausa em série

A funcionalidade tecla Magic SysRq permite-lhe realizar tarefas de baixo nível, independentemente do estado do sistema. Por exemplo, pode sincronizar sistemas de ficheiros, reiniciar a instância, terminar processos e desmontar sistemas de ficheiros através da funcionalidade da tecla Magic SysRq.

Para enviar um comando Magic SysRq através de uma interrupção de série simulada:

  1. Prima a tecla ENTER.
  2. Escreva ~B (til, seguido de B em maiúsculas).
  3. Escreva o comando Magic SysRq.

Visualizar registos de auditoria da consola de série

O Compute Engine fornece registos de auditoria para acompanhar quem se ligou e desligou da consola série de uma instância. Para ver os registos, tem de ter autorizações para o visualizador de registos ou ser um visitante ou um editor do projeto.

  1. Na Google Cloud consola, aceda à página Explorador de registos.

    Aceda ao Explorador de registos

  2. Expanda o menu pendente e selecione GCE VM Instance.
  3. Na barra de pesquisa, escreva ssh-serialport.googleapis.com e prima Enter.
  4. É apresentada uma lista de registos de auditoria. Os registos descrevem as ligações e as desligações de uma consola de série. Expanda qualquer uma das entradas para obter mais informações.

Para qualquer um dos registos de auditoria, pode:

  1. Expanda a propriedade protoPayload.
  2. Procure methodName para ver a atividade à qual este registo se aplica (um pedido de ligação ou de desassociação). Por exemplo, se este registo monitorizar uma desconexão da consola série, o nome do método indicaria "google.ssh-serialport.v1.disconnect". Da mesma forma, um registo de ligação indicaria "google.ssh-serialport.v1.connect". É registada uma entrada do registo de auditoria no início e no fim de cada sessão na consola série.

Existem diferentes propriedades de registo de auditoria para diferentes tipos de registos. Por exemplo, os registos de auditoria relacionados com associações têm propriedades específicas dos registos de associações, enquanto os registos de auditoria de desassociações têm o seu próprio conjunto de propriedades. Existem determinadas propriedades do registo de auditoria que também são partilhadas entre os dois tipos de registos.

Todos os registos da consola de série

A tabela seguinte fornece as propriedades do registo de auditoria e os respetivos valores para todos os registos da consola série:

Propriedade Valor
requestMetadata.callerIp O endereço IP e o número da porta de origem da ligaçã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 série para indicar a que consola série se refere. Por exemplo, projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2 é o número da porta 2, também conhecido 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 Uma data/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. Pode usá-la para associar uma entrada de desassociação à entrada de associação correspondente.
operation.producer ssh-serialport.googleapis.com

Registos de ligação

A tabela seguinte fornece propriedades do registo de auditoria e os respetivos valores específicos para registos de ligação:

Propriedade Valor
methodName google.ssh-serialport.v1.connect
status.message Connection succeeded.
request.serialConsoleOptions Quaisquer opções especificadas com o pedido, incluindo o número da porta série.
request.@type type.googleapis.com/google.compute.SerialConsoleSessionBegin
request.username O nome de utilizador especificado para este pedido. Esta opção é usada para selecionar a chave pública para fazer a correspondência.
operation.first TRUE
status.code Para pedidos de ligação bem-sucedidos, um valor status.code de google.rpc.Code.OK indica que a operação foi concluída com êxito e sem erros. Uma vez que o valor de enumeração desta propriedade é 0, a propriedade status.code não é apresentada. No entanto, qualquer código que verifique um valor status.code de google.rpc.Code.OK funciona conforme esperado.

Registos de desassociação

A tabela seguinte fornece propriedades do registo de auditoria e os respetivos valores específicos para registos de desativação:

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

Registos de ligações com falhas

Quando uma ligação falha, o Compute Engine cria uma entrada no registo de auditoria. Um registo de ligação com falha é muito semelhante a uma entrada de ligação bem-sucedida, mas tem as seguintes propriedades para indicar uma ligação com falha.

Propriedade Valor
severity ERROR
status.code

O código de erro canónico da API Google que melhor descreve o erro. Seguem-se possíveis códigos de erro que podem ser apresentados:

  • google.rpc.Code.INVALID_ARGUMENT: a ligação falhou porque o cliente indicou 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: não ativou a consola série interativa no servidor de metadados. Para mais informações, consulte o artigo Ativar o acesso interativo na consola série.
  • google.rpcCode.UNAUTHENTICATED: Não foram encontradas chaves SSH ou não foi encontrada nenhuma chave SSH correspondente para esta instância. Verifique se tem autenticação na instância de VM.
  • google.rpc.Code.UNKNOWN: ocorreu um erro desconhecido com o seu pedido. Pode contactar a Google no grupo de discussão do GCE ou comunicar um erro.
status.message A mensagem legível para esta entrada.

Desativar o acesso interativo à consola de série

Pode desativar o acesso interativo à consola série alterando os metadados na instância ou no projeto específico, ou definindo uma política da organização que desative o acesso interativo à consola série para todas as instâncias de VM de um ou mais projetos que façam parte da organização.

Desativar a consola de série interativa numa instância ou num projeto específico

Os proprietários e os editores do projeto, bem como os utilizadores aos quais foi concedida a função compute.instanceAdmin.v1, podem desativar o acesso à consola série alterando os metadados na instância ou no projeto específico. Semelhante à ativação do acesso à consola de série, defina os metadados serial-port-enable como FALSE:

serial-port-enable=FALSE

Por exemplo, através da Google Cloud CLI, pode aplicar estes metadados a uma instância específica da seguinte forma:

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

Desativar o acesso interativo à consola de série através da política da organização

Se lhe tiver sido atribuído o papel de orgpolicy.policyAdmin na organização, pode definir uma política da organização que impeça o acesso interativo à consola série, independentemente de o acesso interativo à consola série estar ativado no servidor de metadados. Depois de a política de organização ser definida, a política substitui efetivamente a chave de metadados serial-port-enable e nenhum utilizador da organização ou do projeto pode ativar o acesso interativo à consola série. Por predefinição, esta restrição está definida como FALSE.

A restrição para desativar o acesso interativo à consola de série é a seguinte:

compute.disableSerialPortAccess

Conclua as seguintes instruções para definir esta política na organização. Depois de configurar uma política, pode conceder isenções por projeto.

gcloud

Para definir a política através da CLI do Google Cloud, execute o comando resource-manager enable-enforce. Substitua organization-id pelo seu 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 um pedido POST para o 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 do pedido deve conter um objeto policy com a seguinte restrição:

"constraint": "constraints/compute.disableSerialPortAccess"

Por exemplo:

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

A política entra em vigor imediatamente, pelo que todos os projetos na organização deixam imediatamente de permitir o acesso interativo à consola de série.

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

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

Em alternativa, pode fazer um pedido de API em que o corpo do pedido define o parâmetro enforced como FALSE:

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

Definir a política de organização ao nível do projeto

Pode definir a mesma política organizacional por projeto. Isto substitui a definição ao nível da organização.

gcloud

Para desativar a aplicação desta política para um projeto específico. Substitua project-id pelo ID do seu projeto.

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

Pode ativar a aplicação desta política através do comando enable-enforce com os mesmos valores.

REST

Na API, faça um pedido POST ao seguinte URL para ativar o acesso interativo à consola em série para o projeto, substituindo project-id pelo ID do projeto:

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

O corpo do pedido deve conter um objeto policy com a seguinte restrição:

"constraint": "constraints/compute.disableSerialPortAccess"

Por exemplo:

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

Sugestões e truques

  • Se estiver a ter problemas ao estabelecer ligação através de um cliente SSH padrão, mas o gcloud compute connect-to-serial-port estabelecer ligação com êxito, pode ser útil executar o gcloud compute connect-to-serial-port com a opção de linha de comandos --dry-run para ver o comando SSH que teria sido executado em seu nome e comparar as opções com o comando que está a usar.

  • Se estiver a usar uma VM do Windows com o Início de sessão do SO ativado e encontrar um erro UNAUTHENTICATED, verifique se as suas chaves SSH públicas foram publicadas nos metadados do projeto ou da instância. Para saber mais, consulte o artigo Gerir chaves SSH nos metadados.

  • Ao definir a taxa de bits, também conhecida como taxa de baud, pode definir qualquer taxa de bits que quiser, como stty 9600, mas a funcionalidade normalmente força a taxa efetiva para 115 200 bps (~11,5 kB/seg.). Isto deve-se ao facto de muitas imagens públicas terem taxas de bits lentas por predefinição, como 9600 na consola série, e serem iniciadas lentamente.

  • Algumas imagens do SO têm predefinições inconvenientes na porta série. Por exemplo, no CentOS 7, o valor predefinido para a tecla Enter na consola é enviar um CR, também conhecido como ^M.stty icrnl A shell bash pode ocultar esta informação até tentar definir uma palavra-passe, altura em que pode questionar-se por que motivo parece estar bloqueada no comando password:.

  • Algumas imagens públicas têm chaves de controlo de tarefas desativadas por predefinição se anexar um shell a uma porta de determinadas formas. Alguns exemplos destas teclas incluem ^Z e ^C. O comando setsid pode corrigir este problema. Caso contrário, se vir uma mensagem job control is disabled in this shell, tenha cuidado para não executar comandos que tenha de interromper.

  • Pode ser útil indicar ao sistema o tamanho da janela que está a usar, para que o bash e os editores possam geri-la corretamente. Caso contrário, pode experienciar um comportamento de apresentação estranho porque o bash ou os editores tentam manipular a apresentação com base em pressupostos incorretos sobre o número de linhas e colunas disponíveis. Use o comando stty rows Y cols X e o sinalizador stty -a para ver qual é a definição. Por exemplo: stty rows 60 cols 120 (se a sua janela tiver 120 carateres por 60 linhas).

  • Por exemplo, se estabelecer ligação através de SSH da máquina A à máquina B e, em seguida, à máquina C, criando uma sessão SSH aninhada, e quiser usar comandos com til (~) para terminar a ligação ou enviar um sinal de interrupção em série, tem de adicionar carateres de til adicionais suficientes ao comando para aceder ao cliente SSH correto. Um comando após um único til é interpretado pelo cliente SSH na máquina A; um comando após dois tils consecutivos (Enter~~) é interpretado pelo cliente na máquina B e assim sucessivamente. Só tem de premir Enter uma vez, porque essa ação é transmitida até ao destino SSH mais interior. Isto é verdade para qualquer utilização de clientes SSH que ofereçam a funcionalidade de escape com til.

    Se perder a noção do número de carateres til que precisa, prima a tecla Enter e, em seguida, escreva os carateres til um de cada vez até a instância repetir o til. Este eco indica que atingiu o fim da cadeia e que agora sabe que, para enviar um comando com til ao cliente SSH mais aninhado, precisa de um til a menos do que o número de tils que digitou.

Opções avançadas

Também pode usar as seguintes opções avançadas com a porta série.

Controlar o número máximo de ligações

Pode definir a propriedade max-connections para controlar o número de ligações simultâneas que podem ser feitas a esta porta de série de cada vez. O número predefinido e máximo de ligações é 5. Por 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=3@ssh-serialport.googleapis.com

Definir opções de repetição

Por predefinição, sempre que se liga à consola série, recebe uma repetição das últimas 10 linhas de dados, independentemente de as últimas 10 linhas terem sido vistas por outro cliente SSH. Pode alterar esta definição e controlar quantas linhas são devolvidas e quais são, definindo as seguintes opções:

  • replay-lines=N: defina N para o número de linhas que quer repetir. Por exemplo, se N for 50, as últimas 50 linhas da saída da consola são incluídas.
  • replay-bytes=N: repete os N bytes mais recentes. Também pode definir N como new, que repete toda a saída que ainda não foi enviada a nenhum cliente.
  • replay-from=N: repete a saída a partir de um índice de bytes absoluto que indicar. Pode obter o índice de bytes atual da saída da consola de série fazendo um pedido getSerialPortOutput. Se definir replay-from, todas as outras opções de repetição são ignoradas.

Com a CLI do Google Cloud, anexe o seguinte ao comando connect-to-serial-port, em que N é o número especificado de linhas (ou bytes ou índice de bytes absoluto, consoante a opção de repetição que estiver a selecionar):

--extra-args replay-lines=N

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

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

Também pode usar uma combinação destas opções. Por exemplo:

replay-lines=N e replay-bytes=new
Repetir o número especificado de linhas OU repetir toda a saída não enviada anteriormente a nenhum cliente, consoante o que for maior. O primeiro cliente a estabelecer ligação com esta combinação de flags vê toda a saída que foi enviada para a porta série, e os clientes que estabelecem ligação posteriormente só veem 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=new@ssh-serialport.googleapis.com
replay-lines=N e replay-bytes=M
Repete até, mas não mais do que, o número de linhas ou bytes descritos por estas flags, consoante o que for inferior. Esta opção não repete mais de 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=M@ssh-serialport.googleapis.com

Tratamento de resultados ignorados

O último 1 MiB de saída para cada porta de série está sempre disponível e, geralmente, o seu cliente SSH não deve perder nenhuma saída da porta de série. Se, por algum motivo, o seu cliente SSH deixar de aceitar resultados durante um período de tempo, mas não se desligar, e forem produzidos mais de 1 MiB de novos dados, o seu cliente SSH pode perder alguns resultados. Quando o cliente SSH não está a aceitar dados com rapidez suficiente para acompanhar a saída na porta da consola série, pode definir a propriedade on-dropped-output para determinar o comportamento da consola.

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

  • insert-stderr-note: Insira uma nota no stderr do cliente SSH a indicar que a saída foi ignorada. Esta é a opção predefinida.
  • ignore: ignora silenciosamente a saída e não faz nada.
  • disconnect: interrompa a associação.

Por 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=ignore@ssh-serialport.googleapis.com

Ativar a desassociação através de comandos de saída ou de fim de sessão

Pode ativar a desassociação em comandos de saída ou de fim de sessão definindo a propriedade on-dtr-low como disconnect quando se liga à consola série.

Na CLI gcloud, anexe a seguinte flag ao comando connect-to-serial-port:

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

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

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

A ativação da opção disconnect pode fazer com que a instância se desligue uma ou mais vezes quando a reinicia, porque o sistema operativo repõe as portas série durante o arranque.

A predefinição da opção on-dtr-low é none. Se usar a definição predefinida none, pode reiniciar a instância sem que a ligação à consola série seja terminada. No entanto, a ligação à consola não é terminada por meios normais, como os comandos exit ou logout, ou combinações de teclas normais, como Ctrl+D.

O que se segue?