Como interagir com o console serial

Esta página descreve como ativar o acesso interativo ao console serial de uma instância para depurar problemas de inicialização e rede, solucionar problemas em instâncias com mau funcionamento, interagir com o GRand Unified Bootloader (GRUB, na sigla em inglês) e executar outras tarefas de resolução de problemas.

Uma instância de máquina virtual 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 em nível de sistema usam a primeira porta serial (porta 1), que geralmente é mencionada como o console serial.

Se você precisar visualizar somente a saída da porta serial sem emitir nenhum comando para o console serial, chame o método getSerialPortOutput ou use o Stackdriver para ler as informações que sua instância gravou na porta serial. Consulte Como visualizar registros de portas seriais. Contudo, se você tiver problemas para acessar sua instância por meio do SSH ou precisar solucionar problemas em uma instância que não está totalmente inicializada, é 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 de sua instância. Por exemplo, é possível executar comandos diretamente e responder a prompts na porta serial.

Antes de começar

Permissões necessárias para a tarefa

Para executar essa tarefa, é necessário ter as permissões abaixo.

  • compute.instances.setMetadata na instância, caso seja ativado o acesso interativo em uma instância específica
  • compute.projects.setCommonInstanceMetadata no projeto, caso seja ativado o acesso interativo em todo o projeto

Como ativar o acesso interativo no console serial

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

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. Você pode desativá-lo explicitamente definindo a chave serial-port-enable como 0, em vez de 1. Em qualquer um dos casos, qualquer configuração por instância substituirá a configuração no nível do projeto ou a configuração padrão.

Console

  1. Acesse a página Metadados.
  2. Clique em Editar para editar entradas de metadados.
  3. Adicione uma nova entrada com a chave serial-port-enable e o valor 1. Captura de tela para adicionar chave de metadados do console serial
  4. Salve as alterações.

gcloud

Use o comando project-info add-metadata. Exemplo:

gcloud compute project-info add-metadata --metadata serial-port-enable=1

API

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

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

Como ativar 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, se existir, substituirá toda configuração para envolvidos no projeto. Também é possível desativar o acesso para uma instância específica, mesmo se o acesso estiver ativado para envolvidos no projeto, definindo serial-port-enable como 0, em vez de 1. Da mesma maneira, será 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. 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

Com a ferramenta de linha de comando gcloud, use o comando instances add-metadata:

gcloud compute instances add-metadata INSTANCE \
  --metadata serial-port-enable=1

API

Faça uma solicitação para o método instances().setMetadata com a chave serial-port-enable e o valor 1:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

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

Conexão com um console serial

Depois de ativar o acesso interativo para o console serial de uma instância, é possível estabelecer conexão com o console serial usando o Console do Google Cloud Platform, a ferramenta de linha de comando gcloud ou um cliente SSH de terceiros.

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

Console

  1. 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 estabeleça conexão com a Porta 2 para acessar o console serial.

gcloud

Use o subcomando gcloud compute connect-to-serial-port para estabelecer a conexão usando a ferramenta de linha de comando gcloud. Exemplo:

gcloud compute connect-to-serial-port [INSTANCE_NAME]

em que [INSTANCE_NAME] é o nome da instância com o console serial que você quer acessar.

Por padrão, o comando connect-to-serial-port estabelece conexão com a porta 1 do console serial. Se você estiver estabelecendo conexão com uma instância de VM do Windows, faça isso por meio da porta 2:

gcloud compute connect-to-serial-port [INSTANCE_NAME] --port 2

Para estabelecer conexão com outra porta, forneça um número de porta diferente usando a sinalização --port. É possível fornecer um número de porta de 1 a 4. Para saber mais sobre números de portas, consulte Como entender a numeração de portas seriais.

Outros clientes SSH

Você pode estabelecer conexão com o console serial de uma instância usando outros clientes SSH de terceiros, desde que o cliente permita a conexão com uma porta TCP 9600.

Por exemplo, o comando SSH a seguir estabelece conexão com a porta serial padrão (1) de uma instância chamada example-instance com o nome de usuário jane em um projeto com o ID de projeto myproject. A instância está na zona us-central1-f:

ssh -i [PRIVATE_SSH_KEY_FILE] -p 9600 \
myproject.us-central1-f.example-instance.jane@ssh-serialport.googleapis.com

Mais detalhadamente, é possível a conexão com o console serial de uma instância usando as seguintes informações de login e endereço:

[PROJECT_ID].[ZONE].[INSTANCE_NAME].[USERNAME].[OPTIONS]@ssh-serialport.googleapis.com

onde:

  • [PROJECT_ID] é o ID de projeto dessa instância;
  • [ZONE] é a zona da instância;
  • [INSTANCE_NAME] é o nome da instância;
  • [USERNAME] é o nome de usuário que você está usando para estabelecer conexão com sua instância. Normalmente, esse é o nome de usuário em sua máquina local;
  • [OPTIONS] são opções adicionais que você pode especificar para essa conexão. Por exemplo, é possível especificar determinada porta serial e qualquer uma das opções avançadas a seguir. 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.

Se você estiver estabelecendo conexão com uma instância de VM do Windows, faça isso por meio da porta 2, usando o seguinte comando:

ssh -i [PRIVATE_SSH_KEY_FILE] -p 9600 \
[PROJECT_ID].[ZONE].[INSTANCE_NAME].[USERNAME].port=2@ssh-serialport.googleapis.com

Se estiver com problemas para estabelecer a conexão usando um cliente SSH de terceiros, é possível 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 com o comando que você está usando.

Configuração de uma conexão segura

Ao usar um cliente SSH de terceiros, que não seja a ferramenta de linha de comando gcloud, você pode garantir sua proteção contra falsificação de identidade ou ataques intermediários verificando a chave SSH do servidor de portas seriais do Google. Siga estas instruções para configurar seu sistema para verificar a chave do servidor SSH:

  1. Faça o download da chave SSH do servidor de portas seriais do Google.
  2. Abra seu arquivo hosts conhecido, normalmente localizado em ~/.ssh/known_hosts.
  3. Adicione o conteúdo da chave do servidor SSH com o prefixo ssh-serialport.googleapis.com incluído na chave. Por exemplo, se a chave do servidor contiver a linha ssh-rsa AAAAB3NzaC1yc..., o arquivo ~/.ssh/known_hosts precisará ter a linha:

    ssh-serialport.googleapis.com ssh-rsa AAAAB3NzaC1yc...
    

Por razões de segurança, o Google pode alterar a chave SSH do servidor de portas seriais do Google de vez em quando. Caso seu cliente deixe de autenticar a chave do servidor, aborte a tentativa de conexão imediatamente e siga as orientações acima para fazer o download de uma nova chave SSH do servidor de portas seriais 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 tentar estabelecer conexão com a porta serial e entre em contato com o Suporte do Google. Não forneça nenhuma credencial através de uma conexão em que a autenticação do host falhou.

Desconexão do console serial

Para desconectar do console serial:

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

Você pode descobrir outros comandos digitando ~? ou examinando a página man do SSH:

man ssh

Não use nenhum dos métodos a seguir para tentar desconectar:

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

  • O comando exit ou logout não funciona porque o convidado não tem acesso a nenhuma rede ou conexão do modem. Usar esse comando causa o fechamento e a reabertura do console, e a conexão com a sessão continua estabelecida. Para ativar os comandos exit e logout para a sessão, configure a opção on-dtr-low.

Como conectar-se a um console serial por prompt de login

Se estiver tentando solucionar um problema com uma instância que inicializou completamente, ou tentando solucionar um problema que ocorre após a inicialização no modo de usuário único, talvez você veja um prompt 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. Caso sua instância esteja executando uma imagem pré-configurada com logins de portas seriais, é necessário configurar uma senha local na instância de máquina virtual para que você possa fazer login no console serial, se solicitado.

Como configurar uma senha local

As instruções a seguir descrevem como configurar uma senha local pra um usuário em uma instância de máquina virtual para que o usuário possa fazer login no console serial dessa instância usando a senha especificada.

  1. Estabeleça conexão com a 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 solicitadas.

Configuração de 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. Como alternativa, é possível optar por ativar um prompt de login em outra porta, como a porta 2 (ttyS1), executando um dos comandos a seguir em sua instância. Você pode ver uma lista das portas disponíveis para uma instância em Como entender 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/D

Para ativar os prompts de login em outras portas seriais, use as instruções a seguir.

systemd

Para sistemas operacionais Linux que utilizam o systemd, faça o seguinte:

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

    sudo systemctl start serial-getty@ttyS1.service
    
  • Ative o serviço permanentemente, a partir da próxima reinicialização:

    sudo systemctl enable serial-getty@ttyS1.service
    

upstart

Para sistemas operacionais Linux que utilizam o upstart, faça isto:

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

    • No Ubuntu 14.04:

      sudo sh -c "sed -e s/ttyS0/ttyS1/g < /etc/init/ttyS0.conf > /etc/init/ttyS1.conf"
      
    • 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 um prompt de login na ttyS1 sem reiniciar:

    sudo start ttyS1
    

sysvinit

Para sistemas operacionais Linux que utilizam sysvinit, execute os seguintes comandos:

 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 COM1 a COM4. Para estabelecer conexão com o que o Windows considera como COM3 e o Linux considera ttyS2 se você especificasse a porta 3. Use a tabela a seguir para ajudá-lo a descobrir em qual porta você quer estabelecer a conexão.

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 registrar mensagens provenientes do kernel e dos programas do sistema.

Envio de uma interrupção serial

O recurso chave Magic SysRq permite executar tarefas de baixo nível independentemente do estado do sistema. Por exemplo, com o recurso chave Magic SysRq, você pode sincronizar sistemas de arquivos, reinicializar a instância, encerrar processos, desmontar sistemas de arquivos e assim por diante.

Para enviar um comando Magic SysRq usando uma interrupção serial simulada:

  1. Pressione a tecla ENTER.
  2. digite ~B (til seguido de B em letras maiúsculas);
  3. digite o comando Magic SysRq desejado.

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, você precisa ter permissões para o Visualizador de registros ou ser um leitor ou editor do projeto.

  1. Acesse a página "Registros" no Console do GCP:

    Acessar a página "Registros"

  2. Expanda o menu suspenso e selecione GCE VM Instance.
  3. Na barra de pesquisa, insira ssh-serialport.googleapis.com e pressione Enter.
  4. Será exibida uma lista de registros de auditoria que descrevem a conexão e a desconexão de um console serial. Expanda qualquer uma das entradas para ver mais informações:

    Captura de tela de registros de auditoria do console serial

Em qualquer um dos registros de auditoria, você pode:

  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 esse registro rastreia a desconexão do console serial, o nome do método seria "google.ssh-serialport.v1.disconnect". Igualmente, 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 diferentes tipos de registro. Por exemplo, os registros de auditoria relacionados a conexões sempre terão algumas propriedades específicas dos registros de conexão, enquanto os registros de auditoria de desconexões terão o próprio conjunto de propriedades. Há algumas propriedades de registros de auditoria que também são compartilhadas entre os tipos de registro.

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 contendo o código 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, na instância example-instance.
resource.labels Propriedades que identificam o ID, a zona e o ID de projeto da instância.
timestamp Data e hora que indicam quando a sessão começou ou terminou.
severity NOTICE
operation.id Uma string de ID que identifica exclusivamente a sessão. Você pode usá-la para associar uma entrada Desconexão à entrada Conexão correspondente.
operation.producer ssh-serialport.googleapis.com

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 de enum dessa propriedade é 0, a propriedade status.code não será exibida nesse caso. Contudo, qualquer código que verifique se a propriedade status.code contém o valor google.rpc.Code.OK funcionará de maneira esperada.

Registros de desconexão

Propriedade Valor
methodName google.ssh-serialport.v1.disconnect
response.duration A duração da sessão em segundos.
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:

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 em um projeto em especial

Os proprietários e os editores de projetos, bem como os usuários que receberem o papel compute.instanceAdmin.v1 podem desativar o acesso ao console serial alterando os metadados na instância ou no projeto em especial. De maneira semelhante à ativação do acesso ao console serial, defina os metadados serial-port-enable como 0:

serial-port-enable=0

Por exemplo, usando a ferramenta de linha de comando gcloud, você pode aplicar esses metadados a uma instância específica, como:

gcloud compute instances add-metadata [INSTANCE_NAME]  \
    --metadata=serial-port-enable=0

Para aplicar os metadados ao projeto:

gcloud compute project-info add-metadata --metadata=serial-port-enable=0

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

Se você tiver recebido o papel orgpolicy.policyAdmin na organização, será possível definir uma política de organização que impeça o acesso interativo ao console serial, mesmo que esteja ativado no servidor de metadados. Uma vez definida, a política substitui efetivamente a chave de metadados serial-port-enable, e nenhum usuário da organização ou do projeto pode ativar o acesso ao console serial interativo. Por padrão, essa restrição é definida como falsa.

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

compute.disableSerialPortAccess

Siga as instruções abaixo sobre como definir essa política na organização. Depois de configurar uma política, você poderá conceder isenções por projeto.

gcloud

Para definir a política usando a ferramenta de linha de comando gcloud, execute o comando resource-manager enable-enforce:

gcloud alpha resource-manager org-policies enable-enforce --organization [ORGANIZATION_ID] \
    compute.disableSerialPortAccess

em que [ORGANIZATION_ID] é o código da organização numérica. Por exemplo, 1759840282.

API

Para definir uma política na API, faça uma solicitação POST para o seguinte URL:

 POST https://cloudresourcemanager.googleapis.com/v1beta1/[ORGANIZATION_NAME]:setOrgPolicy

em que [ORGANIZATION_NAME] é o nome da organização. Por exemplo, organizations/1759840282.

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. Dessa forma, qualquer projeto na organização deixará de permitir o acesso interativo ao console serial.

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

gcloud alpha resource-manager org-policies disable-enforce --organization [ORGANIZATION_ID] \
    compute.disableSerialPortAccess

Você também pode fazer uma solicitação à 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 de organização no nível do 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 restrição dessa política para um projeto específico:

gcloud alpha resource-manager org-policies disable-enforce --project [PROJECT_ID]
    compute.disableSerialPortAccess

em que o código do projeto [PROJECT_ID] para essa solicitação seja como my-example-project.

Você pode ativar a restrição dessa política usando o comando enable-enforce com os mesmos valores.

API

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

POST https://cloudresourcemanager.googleapis.com/v1beta1/projects/[PROJECT_ID]:setOrgPolicy

em que [PROJECT_NAME] é o código do projeto.

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 truques

  • Se estiver com dificuldade para estabelecer conexão usando um cliente SSH padrão, mas o comando gcloud compute connect-to-serial-port estabelecer conexão 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 de SO assumem taxas de bits baixas, como 9.600, no console serial e inicializariam lentamente.

  • Algumas imagens de OS têm padrões inconvenientes na porta serial. Por exemplo, no CentOS 7, stty icrnl é necessário para informar ao console a ação correta quando a tecla Enter for pressionada, o que envia um CR, também conhecido como ^M. O shell Bash pode mascarar isso até você tentar definir uma senha e ficar imaginando porque parece preso no prompt password:.

  • Algumas imagens de SO têm chaves de controle do job que serão desativadas por padrão se você anexar um shell a uma porta de determinadas maneiras. ^Z e ^C são exemplos dessas chaves. 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 está usando, assim o Bash e os editores podem gerenciá-la corretamente. Caso contrário, pode ocorrer comportamento incomum da tela conforme o Bash ou os editores a tentam manipular com base em hipóteses incorretas sobre o número de linhas e colunas disponíveis. Use o comando stty rows Y cols X e stty -a para ver qual é a configuração. Por exemplo: stty rows 60 cols 120, se a janela medir 120 caracteres por 60 linhas.

  • Se você estabelecer conexão usando o SSH a partir da máquina A para a máquina B, e em seguida para a máquina C (e assim por diante), criando uma sessão SSH aninhada, e quiser usar comandos ~ para encerrar a conexão ou enviar um sinal de interrupção serial, será necessário adicionar caracteres ~ suficientes ao comando para chegar ao cliente SSH certo. Um comando após um único ~ será interpretado pelo cliente SSH na máquina A. Dois ~ consecutivos (ENTER~~) serão interpretados pelo cliente na máquina B, e assim por diante. Você só precisa pressionar ENTER uma vez, porque ele chegará até o destino SSH mais interno. Isso é verdadeiro para qualquer uso de clientes SSH que proporcionem o recurso de escape ~.

    Se você perder o controle de quantos caracteres ~ são necessários, pressione a tecla ENTER e digite um caractere ~ por vez, até a instância ecoar o ~ de volta. Isso indica que você chegou ao final da cadeia e agora sabe que, para enviar um comando ~ para o cliente SSH mais aninhado, será necessário um ~ a menos do que digitou.

Opções avançadas

Controle do máximo de conexões

Você pode definir a propriedade max-connections para controlar quantas conexões concorrentes podem ser estabelecidas nessa porta seria 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=3@ssh-serialport.googleapis.com

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

Por padrão, sempre que você estabelecer conexão com o 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 exibidas fornecendo as seguintes opções:

  • replay-lines=N: defina em N o número de linhas que quer reproduzir novamente. Por exemplo, se N era 50, as últimas 50 linhas da saída do console serão incluídas.
  • replay-bytes=N: reproduz novamente os N bytes mais recentes. Também é possível definir N para 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 replay-from for definido, todas as outras opções de nova reprodução serão ignoradas.

Com a ferramenta de linha de comando gcloud, 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=N@ssh-serialport.googleapis.com

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

replay-lines=N e replay-bytes=new

reproduzem novamente 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á toda a saída 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=new@ssh-serialport.googleapis.com
replay-lines=N e replay-bytes=M

reproduzem novamente no máximo o número de linhas ou bytes descritos por essas sinalizações, o que for menor. Essa opção não reproduzirá novamente mais 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=M@ssh-serialport.googleapis.com

Como processar a saída eliminada

O 1 MiB mais recente de saída para cada porta serial sempre está disponível e, geralmente, seu cliente SSH não deve perder 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, seu cliente SSH pode perder alguma saída. Nesses cenários, quando seu cliente SSH não estiver aceitando dados rápido o suficiente para acompanhar a saída na porta do console serial, é possível definir 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: insere 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: encerra 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=ignore@ssh-serialport.googleapis.com

Ativação da 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 para disconnect ao estabelecer conexão com o console serial.

Na ferramenta de linha de comando gcloud, anexe o seguinte ao 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=disconnect@ssh-serialport.googleapis.com

Ativar essa opção pode fazer com que sua instância encerre a conexão uma ou mais vezes enquanto estiver reinicializando a instância, já que o sistema operacional redefine as portas seriais durante a inicialização.

A configuração padrão dessa opção é none, em que nada acontece quando a linha DTR muda. Se você alterá-la para "none", poderá reiniciar sua instância sem perder a conexão com o console serial, mas o console não encerrará a conexão por meios normais, como os comandos exit ou logout, nem por combinações normais de teclas, como Ctrl+d.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Compute Engine