Risoluzione dei problemi utilizzando la console seriale

Questa pagina descrive come abilitare l'accesso interattivo alla console seriale di un'istanza per eseguire il debug dei problemi di avvio e di rete, la risoluzione dei problemi di malfunzionamento delle istanze, l'interazione con il Bootloader unificato GRand (GRUB) ed altre attività di risoluzione dei problemi.

Nota: non puoi abilitare l'accesso interattivo alla console seriale per le istanze bare metal; la console seriale è di sola lettura per le istanze bare metal. Per eseguire i comandi in modo interattivo, puoi connetterti all'istanza tramite SSH dopo l'avvio dell'istanza.

Un'istanza di una macchina virtuale (VM) ha quattro porte seriali virtuali. L'interazione con una porta seriale è simile all'utilizzo di una finestra di terminale, in quanto gli input e gli output sono interamente in modalità di testo e non sono disponibili interfacce grafica o mouse. Il sistema operativo, il BIOS e altre entità a livello di sistema dell'istanza spesso scrivono l'output sulle porte seriali e possono accettare input come comandi o risposte a prompt. In genere, queste entità a livello di sistema utilizzano la prima porta seriale (porta 1), mentre la porta seriale 1 viene spesso definita console seriale.

Se hai bisogno solo di visualizzare l'output della porta seriale senza inviare alcun comando alla console seriale, puoi chiamare il metodo getSerialPortOutput o utilizzare Cloud Logging per leggere le informazioni che l'istanza ha scritto sulla sua porta seriale. Consulta Visualizzazione dei log delle porte seriali. Tuttavia, se riscontri problemi ad accedere all'istanza mediante SSH o devi risolvere i problemi di un'istanza non completamente avviata, puoi abilitare l'accesso interattivo alla console seriale, che ti consente di connetterti e interagire con qualsiasi porta seriale dell'istanza. Ad esempio, puoi eseguire direttamente comandi e rispondere ai prompt.

Quando abiliti o disattivi la porta seriale, puoi utilizzare qualsiasi valore booleano accettato dal server di metadati. Per maggiori informazioni, consulta la sezione Impostazione dei valori booleani.

Prima di iniziare

• Se non l'hai già fatto, configura l'autenticazione. L'autenticazione è il processo mediante il quale viene verificata l'identità dell'utente per ottenere l'accesso ai servizi e alle API Google Cloud. Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi eseguire l'autenticazione in Compute Engine come segue.
  

  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. Installa Google Cloud CLI, quindi initialize eseguendo questo comando:

     gcloud init

     Nota: se hai già installato gcloud CLI in precedenza, assicurati di disporre della versione più recente eseguendo gcloud components update.
  2. Set a default region and zone.

  REST

  Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

  Installa Google Cloud CLI, quindi initialize eseguendo questo comando:

  gcloud init

  Per maggiori informazioni, consulta Autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Autorizzazioni richieste per questa attività

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni:

• compute.instances.setMetadata sulla VM se abiliti l'accesso interattivo su una VM specifica
• compute.projects.setCommonInstanceMetadata nel progetto, se abiliti l'accesso interattivo per tutte le VM nel progetto
• Ruolo iam.serviceAccountUser nell'account di servizio dell'istanza

Abilitazione dell'accesso interattivo nella console seriale

Abilita l'accesso interattivo alla console seriale per singole istanze VM o per un intero progetto.

Attenzione: la console seriale interattiva non supporta le restrizioni degli accessi basati su IP, come le liste consentite IP, a meno che non utilizzi Controlli di servizio VPC. Se abiliti la console seriale interattiva su un'istanza, i client possono tentare di connettersi all'istanza da qualsiasi indirizzo IP. Chiunque può connettersi a questa istanza se conosce la chiave SSH, il nome utente, l'ID progetto, la zona e il nome dell'istanza corretti.

Abilitazione dell'accesso per un progetto

L'abilitazione dell'accesso interattivo alla console seriale in un progetto consente l'accesso per tutte le istanze VM che fanno parte di quel progetto.

L'accesso alle porte seriali interattive è disattivato per impostazione predefinita. Puoi anche disabilitarlo esplicitamente impostando la chiave serial-port-enable su FALSE. In entrambi i casi, qualsiasi impostazione per istanza sostituisce l'impostazione a livello di progetto o l'impostazione predefinita.

Console

1. Nella console Google Cloud, vai alla pagina Metadati.

   Vai a Metadati

2. Fai clic su Modifica per modificare le voci dei metadati.
3. Aggiungi una nuova voce che utilizza la chiave serial-port-enable e il valore TRUE.
4. Salva le modifiche.

gcloud

Utilizzando Google Cloud CLI, inserisci il comando project-info add-metadata come segue:

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

REST

Nell'API, effettua una richiesta al metodo projects().setCommonInstanceMetadata, fornendo alla chiave serial-port-enable il valore TRUE:

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

Abilitazione dell'accesso per un'istanza VM

Abilita l'accesso alla console seriale interattiva per un'istanza specifica. Un'impostazione per istanza, se esistente, sostituisce qualsiasi impostazione a livello di progetto. Puoi anche disabilitare l'accesso per un'istanza specifica, anche se è abilitato a livello di progetto, impostando serial-port-enable su FALSE, anziché su TRUE. Allo stesso modo, puoi abilitare l'accesso per una o più istanze anche se è disabilitato per il progetto, in modo esplicito o per impostazione predefinita.

Console

1. Nella console Google Cloud, vai alla pagina Istanze VM.

   Vai alla pagina Istanze VM

2. Fai clic sull'istanza per la quale vuoi abilitare l'accesso.
3. Fai clic su Modifica.
4. Nella sezione Accesso remoto, seleziona la casella di controllo Abilita connessione alle porte seriali.
5. Salva le modifiche.

gcloud

Utilizzando Google Cloud CLI, inserisci il comando instances add-metadata, sostituendo instance-name con il nome della tua istanza.

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

REST

Nell'API, effettua una richiesta al metodo instances().setMetadata con la chiave serial-port-enable e il valore 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"
  }
 ]
}

Configura la console seriale per un'istanza bare metal

Per le istanze bare metal, aumenta la velocità in bit, nota anche come baud rate, per la console seriale a 115.200 bps (~11,5 kB/sec). Se la velocità è inferiore, l'output della console è incomprensibile o mancante.

La configurazione del bootloader varia in base ai sistemi operativi e alle versioni del sistema operativo. Per istruzioni, consulta la documentazione del distributore del sistema operativo.

Se modifichi la velocità in bit nella riga di comando per la sessione corrente, utilizza un comando simile al seguente:

console=ttyS0,115200

Se modifichi la configurazione GRUB, usa un comando simile al seguente:

serial --speed=115200

Assicurati di aggiornare la configurazione effettiva del bootloader. Questa operazione può essere eseguita con update-grub, grub2-mkconfig o un comando simile.

Connessione a una console seriale

Compute Engine offre gateway della console seriale a livello di regione per ogni regione Google Cloud. Dopo aver abilitato l'accesso interattivo per la console seriale di una VM, puoi connetterti a una console seriale regionale.

La console seriale autentica gli utenti con le chiavi SSH. In particolare, devi aggiungere la tua chiave SSH pubblica ai metadati del progetto o dell'istanza e archiviare la chiave privata sulla macchina locale da cui vuoi connetterti. gcloud CLI e la console Google Cloud aggiungono automaticamente chiavi SSH al progetto. Se utilizzi un client di terze parti, potrebbe essere necessario aggiungere manualmente le chiavi SSH.

Attenzione :la connessione diretta alla console seriale tramite l'indirizzo IP anziché il nome host non è consigliata. Gli indirizzi IP della console seriale possono cambiare senza preavviso.

Console

Per connetterti alla console seriale regionale di una VM, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Istanze VM.

   Vai alla pagina Istanze VM

2. Fai clic sull'istanza a cui vuoi connetterti.
3. In Accesso remoto, fai clic su Connetti a console seriale per collegarti sulla porta predefinita (porta 1).
4. Se vuoi connetterti a un'altra porta seriale, fai clic sulla Freccia giù accanto al pulsante Connetti alla console seriale e modifica il numero di porta di conseguenza.
5. Per le istanze Windows, apri il menu a discesa accanto al pulsante e connettiti alla porta 2 per accedere alla console seriale.

gcloud

Per connetterti alla console seriale regionale di una VM, utilizza il comando gcloud compute connect-to-serial-port:

  gcloud compute connect-to-serial-port VM_NAME 

      --port=PORT_NUMBER
  

Sostituisci quanto segue:

• VM_NAME: il nome della VM di cui vuoi connetterti alla console seriale.

• PORT_NUMBER: il numero di porta che vuoi connettere. Per le VM Linux, usa 1, per le VM Windows, usa 2. Per scoprire di più sui numeri di porta, consulta Informazioni sulla numerazione delle porte seriali.

  Nota: il numero di porta predefinito è 1.

Altri client SSH

Nota: devi aver aggiunto la chiave pubblica ai metadati del progetto o dell'istanza prima di poter utilizzare un client SSH di terze parti. Se in passato hai utilizzato gcloud CLI per connetterti ad altre istanze nello stesso progetto, è probabile che PUBLIC_KEY_FILE si trovi in $HOME/.ssh/google_compute_engine.pub. Se non hai mai effettuato la connessione a un'istanza in questo progetto (quindi non hai mai aggiunto chiavi pubbliche), devi aggiungere le tue chiavi SSH ai metadati del progetto o dell'istanza prima di poterti connettere utilizzando un client SSH di terze parti. Per ulteriori informazioni, consulta Gestione delle chiavi SSH nei metadati.

Puoi connetterti alla console seriale di un'istanza utilizzando altri client SSH di terze parti, purché il client consenta di connetterti alla porta TCP 9600.

Per connetterti alla console seriale regionale di una VM, esegui uno dei seguenti comandi, a seconda del sistema operativo della VM:

• Per connetterti a una VM Linux:

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

• Per connetterti a una VM Windows:

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

Sostituisci quanto segue:

• PRIVATE_SSH_KEY_FILE: la chiave SSH privata per l'istanza.
• PROJECT_ID: l'ID progetto per questa istanza VM.
• ZONE: la zona dell'istanza VM.
• REGION: la regione dell'istanza VM.
• VM_NAME: il nome dell'istanza VM.
• USERNAME: il nome utente che stai utilizzando per connetterti all'istanza. In genere, si tratta del nome utente del computer locale.
• OPTIONS: opzioni aggiuntive che puoi specificare per questa connessione. Ad esempio, puoi specificare una determinata porta seriale e specificare qualsiasi opzione avanzata. Il numero di porta può essere compreso tra 1 e 4. Per ulteriori informazioni sui numeri di porta, consulta Informazioni sulla numerazione delle porte seriali. Se omesso, ti connetterai alla porta seriale 1.

Attenzione: il gateway della console seriale globale è stato ritirato il 30 aprile 2024 e non può più essere utilizzato in nuovi progetti o progetti in cui non è stato usato in precedenza. Se utilizzi il gateway della console seriale globale, passa all'utilizzo di gateway regionali. Per maggiori informazioni, consulta Ritiro del gateway della console seriale globale.

Per connetterti al gateway della console seriale globale, sostituisci REGION-ssh-serialport.googleapis.com con ssh-serialport.googleapis.com come nome host.

Se hai difficoltà a connetterti utilizzando un client SSH di terze parti, puoi eseguire il comando gcloud compute connect-to-serial-port con l'opzione della riga di comando --dry-run per visualizzare il comando SSH che avrebbe eseguito per tuo conto. Quindi puoi confrontare le opzioni con il comando che stai utilizzando.

Configurare una connessione sicura

Quando utilizzi un client SSH di terze parti diverso da Google Cloud CLI, puoi assicurarti di proteggerti da attacchi di impersonificazione o man in the middle controllando la chiave SSH del server della porta seriale di Google. Per configurare il sistema in modo che controlli la chiave SSH del server, completa questi passaggi:

1. Scarica la chiave SSH del server per la console seriale che utilizzerai:
   • Per le connessioni a livello di regione, la chiave SSH del server per una regione è disponibile all'indirizzo https://www.gstatic.com/vm_serial_port/region/region.pub
   • Per le connessioni globali, scarica la chiave SSH del server della porta seriale di Google
2. Apri il file degli host noti, che in genere si trova in ~/.ssh/known_hosts.

3. Aggiungi i contenuti della chiave SSH del server, aggiungendo il nome host del server alla chiave. Ad esempio, se la chiave server us-central1 contiene la riga ssh-rsa AAAAB3NzaC1yc..., ~/.ssh/known_hosts dovrebbe avere una riga simile alla seguente:

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

Per motivi di sicurezza, di tanto in tanto Google potrebbe modificare la chiave SSH del server della porta seriale Google. Se il client non riesce ad autenticare la chiave server, termina immediatamente il tentativo di connessione e completa i passaggi precedenti per scaricare una nuova chiave SSH del server della porta seriale di Google.

Se, dopo l'aggiornamento della chiave host, continui a ricevere un errore di autenticazione host dal client, interrompi i tentativi di connessione alla porta seriale e contatta l'Assistenza Google. Non fornire credenziali su una connessione in cui l'autenticazione dell'host non è andata a buon fine.

Disconnessione dalla console seriale

Per disconnetterti dalla console seriale:

1. Premi il tasto ENTER.
2. Digita ~. (tilde, seguito da un punto).

Puoi scoprire altri comandi digitando ~? o esaminando la pagina man per SSH:

man ssh

Non provare a disconnetterti utilizzando uno dei seguenti metodi:

• La combinazione di tasti CTRL+ALT+DELETE o altre combinazioni simili. Questo non funziona perché la console seriale non riconosce le combinazioni di tastiere di PC.

• Il comando exit o logout non funziona perché l'ospite non è a conoscenza delle connessioni di rete o del modem. Se utilizzi questo comando, la console si chiude e poi riapre, mantenendo la connessione alla sessione. Se vuoi abilitare i comandi exit e logout per la tua sessione, puoi abilitarli impostando l'opzione on-dtr-low.

Configura la console seriale per un'istanza bare metal

Per le istanze bare metal, aumenta la velocità in bit, nota anche come baud rate, per la console seriale a 115.200 bps (~11,5 kB/sec). Se la velocità è inferiore, l'output della console è incomprensibile o mancante.

Modifica il bootloader e la riga di comando del kernel in modo che utilizzi 115.200 come velocità della console seriale per ttyS0. Per istruzioni su come modificare la velocità in bit per la console seriale, fai riferimento alla documentazione di distribuzione del sistema operativo.

Connessione a una console seriale con una richiesta di accesso

Se stai tentando di risolvere un problema con una VM completamente avviata o se stai tentando di risolvere un problema che si verifica dopo che la VM si è avviata dopo la modalità utente singolo, è possibile che ti vengano richieste le informazioni di accesso quando cerchi di accedere alla console seriale.

Per impostazione predefinita, le immagini di sistema Linux fornite da Google non sono configurate per consentire gli accessi basati su password per gli utenti locali. Tuttavia, le immagini Windows fornite da Google sono configurate per consentire accessi basati su password per gli utenti locali.

Se la tua VM esegue un'immagine preconfigurata con accessi alle porte seriali, devi impostare una password locale sulla VM in modo da poter accedere alla console seriale, se richiesto. Puoi configurare una password locale dopo aver connesso alla VM o usando uno script di avvio.

Nota: questo passaggio non è necessario se interagisci con il sistema durante o prima dell'avvio oppure con un servizio basato su porta seriale che non richiede una password. Inoltre, questo passaggio non è necessario se hai configurato getty in modo che acceda automaticamente senza password utilizzando il flag "-a root".

Configurazione di una password locale utilizzando uno script di avvio

Puoi utilizzare uno script di avvio per configurare una password locale che consenta di connetterti alla console seriale durante o dopo la creazione della VM.

Le seguenti istruzioni descrivono come configurare una password locale dopo la creazione di una VM.

1. Nella console Google Cloud, vai alla pagina Istanze VM.

   Vai a Istanze VM

2. Seleziona la VM per la quale vuoi aggiungere la password locale.

3. Fai clic su Modifica.

   Linux

   1. Vai alla sezione Metadati > Automazione.

   2. Se nella VM esiste uno script di avvio, copialo e incollalo in un luogo sicuro.

   3. Aggiungi il seguente script di avvio:

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

      Sostituisci quanto segue:

      • USERNAME: il nome utente che vuoi aggiungere
      • PASSWORD: la password per il nome utente. Evita password semplici, poiché alcuni sistemi operativi potrebbero richiedere lunghezza e complessità minime delle password.

   Windows

   1. Vai alla sezione Metadati personalizzati.
   2. Se la VM ha uno script di avvio esistente, copialo e incollalo in un luogo sicuro.
   3. Fai clic su Aggiungi elemento.
   4. Nel campo Key (Chiave), inserisci windows-startup-script-cmd.

   5. Nel campo Valore, inserisci il seguente script:

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

      Sostituisci quanto segue:

      • USERNAME: il nome utente che vuoi aggiungere
      • PASSWORD: la password per il nome utente

4. Fai clic su Salva.

5. Per riavviare la VM, fai clic su Reimposta. Per ulteriori informazioni, consulta Reimpostare una VM.

6. Connettiti alla console seriale.

7. Quando richiesto, inserisci i dati di accesso.

8. Rimuovi lo script di avvio dalla VM dopo la creazione dell'utente.

Configurazione di una password locale utilizzando passwd sulla VM

Le seguenti istruzioni descrivono come configurare una password locale per un utente su una VM, in modo che l'utente possa accedere alla console seriale della VM utilizzando la password specificata.

1. Connettiti alla VM. Sostituisci instance-name con il nome della tua istanza.

   gcloud compute ssh instance-name

2. Sulla VM, crea una password locale con il comando seguente. In questo modo viene impostata una password per l'utente con cui hai eseguito l'accesso.

   sudo passwd $(whoami)

3. Segui le istruzioni per creare una password.

4. Esci dall'istanza e connettiti alla console seriale.

5. Quando richiesto, inserisci i dati di accesso.

Configurazione di un accesso su altre porte seriali

Le richieste di accesso sono abilitate per impostazione predefinita sulla porta 1 sulla maggior parte dei sistemi operativi Linux. Tuttavia, la porta 1 può essere spesso sovraccarica dai dati di logging e da altre informazioni stampate nella porta. Puoi scegliere di abilitare un prompt di accesso su un'altra porta, come la porta 2 (ttyS1), eseguendo sulla VM uno dei seguenti comandi. Puoi vedere un elenco delle porte disponibili per una VM in Informazioni sulla numerazione delle porte seriali.

La tabella seguente elenca le immagini preconfigurate con un accesso alla console seriale e le porte predefinite.

Sistema operativo	Porte con richiesta di accesso per impostazione predefinita	Gestione servizio
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
Salto OpenSUSE	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

Per attivare le richieste di accesso su porte seriali aggiuntive, completa le seguenti istruzioni.

Nota: le seguenti istruzioni sono suddivise in base ai sistemi operativi in esecuzione su systemd, upstart o sysvinit. Per tutti gli insiemi di istruzioni, puoi sostituire ttyS1 con un'altra porta seriale, se vuoi.

systemd

Per sistemi operativi Linux che utilizzano systemd:

• Attiva temporaneamente il servizio fino al riavvio successivo:

  sudo systemctl start [e-mail]

• Attiva il servizio in modo permanente, a partire dal riavvio successivo:

  sudo systemctl enable [e-mail]

avviamento iniziale

Per sistemi operativi Linux che utilizzano upstart:

1. Crea un nuovo file /etc/init/ttyS1.conf per riflettere ttyS1 copiando e modificando un file ttyS0.conf esistente. Ad esempio:

   • Su Ubuntu 14.04:

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

     Nota: Ubuntu 12.04 non ha un ttyS0.conf, pertanto Google consiglia di copiare il file ttysS0.conf da Ubuntu 14.04 e di utilizzarlo sull'istanza che esegue Ubuntu 12.04.

   • Su RHEL 6.8 e 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. Avvia con una richiesta di accesso su ttyS1 senza riavviare:

   sudo start ttyS1

Sysvinit

Per sistemi operativi Linux che utilizzano sysvinit, esegui questo comando:

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

Informazioni sulla numerazione delle porte seriali

Ogni istanza di macchina virtuale ha quattro porte seriali. Per garantire la coerenza con l'API getSerialPortOutput, ogni porta è numerata da 1 a 4. Linux e altri sistemi simili numerano le porte seriali da 0 a 3. Ad esempio, su molte immagini di sistemi operativi, i dispositivi corrispondenti vanno da /dev/ttyS0 a /dev/ttyS3. Windows fa riferimento alle porte seriali come da COM1 a COM4. Per connetterti a ciò che Windows considera COM3 e Linux considera ttyS2, devi specificare la porta 3. Utilizza la seguente tabella per capire a quale porta vuoi connetterti.

Porte seriali di istanze VM	Porte seriali standard Linux	Porte COM Windows
1	/dev/ttyS0	COM1
2	/dev/ttyS1	COM2
3	/dev/ttyS2	COM3
4	/dev/ttyS3	COM4

Tieni presente che molte immagini Linux utilizzano la porta 1 (/dev/ttyS0) per il logging dei messaggi dei programmi del kernel e di sistema.

Invio di un'interruzione di serie

La funzionalità Chiave SysRq magica ti consente di eseguire attività di basso livello indipendentemente dallo stato del sistema. Ad esempio, puoi sincronizzare i file system, riavviare l'istanza, terminare i processi e smontare i file system utilizzando la funzionalità chiave SysRq magico.

Per inviare un comando SysRq magico utilizzando un'interruzione seriale simulata:

1. Premi il tasto ENTER.
2. Digita ~B (tilde, seguito dalla lettera maiuscola B).
3. Digita il comando SysRq magico.

Nota: il tasto SysRq magico solitamente viene implementato utilizzando codici di scansione della tastiera del PC, ma non esiste un equivalente diretto su una porta seriale. Questo è il metodo consigliato per accedere alla funzionalità Magic SysRq.

Visualizzazione degli audit log della console seriale

Compute Engine fornisce audit log per tenere traccia degli utenti connessi e disconnessi dalla console seriale di un'istanza. Per visualizzare i log, devi disporre delle autorizzazioni per il visualizzatore log o essere un visualizzatore o un editor del progetto.

1. Nella console Google Cloud, vai alla pagina Esplora log.

   Vai a Esplora log

2. Espandi il menu a discesa e seleziona Istanza VM GCE.
3. Nella barra di ricerca, digita ssh-serialport.googleapis.com e premi Invio.

4. Viene visualizzato un elenco di audit log. I log descrivono connessioni e disconnessioni da una console seriale. Espandi una delle voci per ottenere maggiori informazioni:

   

Per qualsiasi log di controllo, puoi:

1. Espandi la proprietà protoPayload.
2. Cerca methodName per vedere l'attività a cui si applica questo log (una richiesta di connessione o di disconnessione). Ad esempio, se questo log monitora una disconnessione dalla console seriale, il nome del metodo dirà "google.ssh-serialport.v1.disconnect". Analogamente, un log delle connessioni dirà "google.ssh-serialport.v1.connect". Viene registrata una voce di audit log all'inizio e alla fine di ogni sessione sulla console seriale.

Esistono proprietà diverse degli audit log per tipi di log diversi. Ad esempio, gli audit log relativi alle connessioni hanno proprietà specifiche per i log delle connessioni, mentre gli audit log per le disconnessioni hanno un proprio insieme di proprietà. Alcune proprietà degli audit log sono condivise anche tra i due tipi di log.

Tutti i log della console seriale

La tabella seguente fornisce le proprietà degli audit log e i relativi valori per tutti i log della console seriale:

Proprietà	Valore
requestMetadata.callerIp	L'indirizzo IP e il numero di porta da cui ha avuto origine la connessione.
serviceName	ssh-serialport.googleapis.com
resourceName	Una stringa contenente l'ID progetto, la zona, il nome dell'istanza e il numero di porta seriale per indicare a quale console seriale si riferisce. Ad esempio, projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2 è la porta 2, nota anche come COM2 o /dev/ttyS1, per l'istanza example-instance.
resource.labels	Proprietà che identificano l'ID istanza, la zona e l'ID progetto.
timestamp	Un timestamp che indica quando è iniziata o terminata la sessione.
severity	NOTICE
operation.id	Una stringa ID che identifica in modo univoco la sessione; puoi utilizzarla per associare una voce di disconnessione alla voce di connessione corrispondente.
operation.producer	ssh-serialport.googleapis.com

Log delle connessioni

La tabella seguente fornisce le proprietà degli audit log e i relativi valori specifici per i log delle connessioni:

Proprietà	Valore
methodName	google.ssh-serialport.v1.connect
status.message	Connection succeeded.
request.serialConsoleOptions	Qualsiasi opzione specificata con la richiesta, incluso il numero di porta seriale.
request.@type	type.googleapis.com/google.compute.SerialConsoleSessionBegin
request.username	Il nome utente specificato per questa richiesta. Viene utilizzato per selezionare la chiave pubblica da abbinare.
operation.first	TRUE
status.code	Per le richieste di connessione andate a buon fine, un valore status.code pari a google.rpc.Code.OK indica che l'operazione è stata completata correttamente senza errori. Poiché il valore enum per questa proprietà è 0, la proprietà status.code non viene visualizzata. Tuttavia, qualsiasi codice che verifichi un valore status.code pari a google.rpc.Code.OK funzionerà come previsto.

Log di disconnessione

La tabella seguente fornisce le proprietà degli audit log e i relativi valori specifici per i log di disconnessione:

Proprietà	Valore
methodName	google.ssh-serialport.v1.disconnect
response.duration	La durata, in secondi, della sessione.
response.@type	type.googleapis.com/google.compute.SerialConsoleSessionEnd
operation.last	TRUE

Log di connessione non riuscite

Quando una connessione non riesce, Compute Engine crea una voce di audit log. Un log di connessione non riuscita è molto simile a una voce di connessione riuscita, ma presenta le seguenti proprietà per indicare una connessione non riuscita.

Proprietà	Valore
severity	ERROR
status.code	Il codice di errore canonico dell'API di Google che descrive meglio l'errore. Di seguito sono riportati i possibili codici di errore che potrebbero essere visualizzati: google.rpc.Code.INVALID_ARGUMENT: la connessione non è riuscita perché il client ha fornito un numero di porta non valido o ha tentato di raggiungere un canale sconosciuto. Consulta l'elenco dei numeri di porta validi. google.rpc.Code.PERMISSION_DENIED: non hai abilitato la console seriale interattiva nel server dei metadati. Per maggiori informazioni, consulta Attivazione dell'accesso interattivo nella console seriale. google.rpcCode.UNAUTHENTICATED: nessuna chiave SSH trovata o nessuna chiave SSH corrispondente trovata per questa istanza. Verifica di aver eseguito l'autenticazione nell'istanza VM. google.rpc.Code.UNKNOWN: si è verificato un errore sconosciuto nella tua richiesta. Puoi contattare Google nel gruppo di discussione di gce o inviare una segnalazione di bug.
status.message	Il messaggio leggibile per questa voce.

Disabilitazione dell'accesso alla console seriale interattiva

Puoi disabilitare l'accesso alla console seriale interattiva modificando i metadati sull'istanza o sul progetto specifico oppure impostando un Criterio dell'organizzazione che disabiliti l'accesso alla console seriale interattiva a tutte le istanze VM di uno o più progetti che fanno parte dell'organizzazione.

Disabilitazione della console seriale interattiva su un'istanza o un progetto specifico

I proprietari e gli editor del progetto, nonché gli utenti a cui è stato concesso il ruolo compute.instanceAdmin.v1, possono disabilitare l'accesso alla console seriale modificando i metadati sull'istanza o sul progetto specifici. Analogamente all'abilitazione dell'accesso alla console seriale, imposta i metadati serial-port-enable su FALSE:

serial-port-enable=FALSE

Ad esempio, utilizzando Google Cloud CLI, puoi applicare questi metadati a un'istanza specifica in questo modo:

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

Per applicare i metadati al progetto:

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

Disabilitazione dell'accesso alla console seriale interattiva tramite il criterio dell'organizzazione

Se ti è stato concesso il ruolo orgpolicy.policyAdmin nell'organizzazione, puoi impostare un criterio dell'organizzazione che impedisce l'accesso interattivo alla console seriale, indipendentemente dal fatto che l'accesso alla console seriale interattiva sia abilitato sul server dei metadati. Una volta configurato il criterio dell'organizzazione, il criterio sostituisce in modo efficace la chiave di metadati serial-port-enable e nessun utente dell'organizzazione o del progetto potrà abilitare l'accesso interattivo alla console seriale. Per impostazione predefinita, questo vincolo è impostato su FALSE.

Il vincolo per disabilitare l'accesso alla console seriale interattiva è il seguente:

compute.disableSerialPortAccess

Completa le seguenti istruzioni per impostare questo criterio nell'organizzazione. Dopo aver configurato un criterio, puoi concedere esenzioni in base al progetto.

gcloud

Per impostare il criterio utilizzando Google Cloud CLI, esegui il comando resource-manager enable-enforce. Sostituisci organization-id con il tuo ID organizzazione. Ad esempio: 1759840282.

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

REST

Per impostare un criterio nell'API, effettua una richiesta POST al seguente URL. Sostituisci organization-name con il nome della tua organizzazione. Ad esempio: organizations/1759840282.

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

Il corpo della richiesta deve contenere un oggetto policy con il seguente vincolo:

"constraint": "constraints/compute.disableSerialPortAccess"

Ad esempio:

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

Il criterio viene applicato immediatamente, pertanto tutti i progetti nell'organizzazione interrompono immediatamente l'accesso interattivo alla console seriale.

Per disattivare temporaneamente il criterio, utilizza il comando disable-enforce:

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

In alternativa, puoi effettuare una richiesta API in cui il corpo della richiesta imposta il parametro enforced su FALSE:

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

Impostazione del criterio dell'organizzazione a livello di progetto

Puoi impostare lo stesso criterio dell'organizzazione in base al progetto. Questa operazione sostituisce l'impostazione a livello di organizzazione.

gcloud

Disattivare l'applicazione di questo criterio per un progetto specifico. Sostituisci project-id con il tuo ID progetto.

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

Puoi attivare l'applicazione di questo criterio utilizzando il comando enable-enforce con gli stessi valori.

REST

Nell'API, effettua una richiesta POST al seguente URL per abilitare l'accesso interattivo alla console seriale per il progetto, sostituendo project-id con l'ID progetto:

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

Il corpo della richiesta deve contenere un oggetto policy con il seguente vincolo:

"constraint": "constraints/compute.disableSerialPortAccess"

Ad esempio:

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

Suggerimenti utili

• Se hai difficoltà a connetterti utilizzando un client SSH standard, ma gcloud compute connect-to-serial-port si connette correttamente, potrebbe essere utile eseguire gcloud compute connect-to-serial-port con l'opzione della riga di comando --dry-run per visualizzare il comando SSH che avrebbe eseguito per conto tuo e confrontare le opzioni con il comando che stai utilizzando.

• Con l'impostazione della velocità in bit, nota anche come baud rate, puoi impostare la velocità in bit che desideri, ad esempio stty 9600, ma la funzionalità normalmente forza la velocità effettiva a 115.200 bps (~11,5 kB/sec). Questo perché molte immagini pubbliche hanno per impostazione predefinita velocità in bit lente, ad esempio 9600 sulla console seriale, e si avviano lentamente.

• Alcune immagini del sistema operativo presentano impostazioni predefinite sconvenienti sulla porta seriale. Ad esempio, su CentOS 7, il valore predefinito di stty icrnl per il tasto Invio sulla console è l'invio di un CR, noto anche come ^M. La shell bash potrebbe mascherarlo finché non provi a impostare una password, a quel punto potresti chiederti perché rimane bloccato al prompt di password:.

• Alcune immagini pubbliche hanno chiavi di controllo dei job che sono disabilitate per impostazione predefinita se colleghi una shell a una porta in determinati modi. Alcuni esempi di queste chiavi includono ^Z e ^C. Il comando setsid potrebbe risolvere il problema. In caso contrario, se viene visualizzato un messaggio job control is disabled in this shell, fai attenzione a non eseguire comandi che dovrai interrompere.

• Può essere utile comunicare al sistema le dimensioni della finestra che stai utilizzando, in modo che bash ed editor possano gestirla correttamente. In caso contrario, potresti riscontrare comportamenti di visualizzazione strani perché bash o editor tentano di manipolare la visualizzazione sulla base di ipotesi errate sul numero di righe e colonne disponibili. Utilizza il comando stty rows Y cols X e il flag stty -a per vedere l'impostazione. Ad esempio: stty rows 60 cols 120 (se la finestra è di 120 caratteri x 60 righe).

• Se, ad esempio, ti connetti utilizzando SSH dalla macchina A alla macchina B e poi alla macchina C, creando una sessione SSH nidificata e vuoi utilizzare i comandi tilde (~) per disconnettere o inviare un segnale di interruzione seriale, dovrai aggiungere abbastanza caratteri tilde al comando per raggiungere il client SSH corretto. Un comando che segue una singola tilde viene interpretato dal client SSH sulla macchina A; un comando che segue due tilde consecutive (Enter~~) viene interpretato dal client sulla macchina B e così via. Basta premere Invio una volta perché viene passato fino alla destinazione SSH più interna. Questo vale per qualsiasi utilizzo di client SSH che forniscono la funzionalità di escape tilde.

  Se non sai quanti caratteri tilde ti servono, premi il tasto Invio e digita la tilde uno alla volta finché l'istanza non riporterà la tilde. Questo echo indica che hai raggiunto la fine della catena e ora sai che per inviare un comando tilde al client SSH più nidificato, è necessaria una tilde in meno rispetto al numero di tilde digitato.

Opzioni avanzate

Controllo del numero massimo di connessioni

Puoi impostare la proprietà max-connections per controllare quante connessioni simultanee possono essere stabilite contemporaneamente a questa porta seriale. Il numero predefinito e massimo di connessioni è 5. Ad esempio:

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]

Impostazione delle opzioni di riproduzione

Per impostazione predefinita, ogni volta che ti connetti alla console seriale, riceverai una riproduzione delle ultime 10 righe di dati, indipendentemente dal fatto che siano state viste o meno da un altro client SSH. Puoi modificare questa impostazione e controllare quante e quali righe vengono restituite impostando le seguenti opzioni:

• replay-lines=N: imposta N sul numero di righe che vuoi ripetere. Ad esempio, se N è 50, vengono incluse le ultime 50 righe dell'output della console.
• replay-bytes=N: riproduce i N byte più recenti. Puoi anche impostare N su new in modo da ripetere tutti gli output che non sono ancora stati inviati a un client.
• replay-from=N: riproduce l'output a partire da un indice di byte assoluto da te fornito. Puoi ottenere l'indice di byte attuale dell'output della console seriale effettuando una richiesta getSerialPortOutput. Se imposti replay-from, tutte le altre opzioni di riproduzione vengono ignorate.

Con Google Cloud CLI, aggiungi quanto segue al comando connect-to-serial-port, dove N è il numero specificato di righe (o byte o indice di byte assoluti, a seconda dell'opzione di riproduzione selezionata):

--extra-args replay-lines=N

Se utilizzi un client SSH di terze parti, fornisci questa opzione nel tuo comando SSH:

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

Puoi anche utilizzare una combinazione di queste opzioni. Ad esempio:

replay-lines=N e replay-bytes=new

Riproduci di nuovo il numero di righe specificato OPPURE riproduci di nuovo tutti gli output non inviati in precedenza a un client, se il numero maggiore è maggiore. Il primo client che si connette con questa combinazione di flag vedrà tutto l'output inviato alla porta seriale, e i client che si connettono successivamente vedranno solo le ultime N righe. Esempi:

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

Riproduci di nuovo le righe fino al numero massimo di righe o byte descritto da questi flag, a seconda di quale sia il numero inferiore. Questa opzione non consente di ripetere più di N o M byte.

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]

Gestione dell'output ignorato

Il più recente 1 MiB di output per ogni porta seriale è sempre disponibile e, in genere, il tuo client SSH non dovrebbe perdere alcun output dalla porta seriale. Se, per qualche motivo, il client SSH smette di accettare l'output per un determinato periodo di tempo ma non si disconnette e viene generato più di 1 MiB di nuovi dati, il client SSH potrebbe perdere alcuni output. Se il client SSH non accetta dati abbastanza velocemente da stare al passo con l'output sulla porta della console seriale, puoi impostare la proprietà on-dropped-output per determinare il comportamento della console.

Imposta una delle seguenti opzioni applicabili con questa proprietà:

• insert-stderr-note: inserisci una nota nel stderr del client SSH per indicare che l'output è stato eliminato. Questa è l'opzione predefinita.
• ignore: ignora silenziosamente l'output e non fa nulla.
• disconnect: interrompi la connessione.

Ad esempio:

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]

Abilitazione della disconnessione tramite i comandi di uscita o di disconnessione

Puoi abilitare la disconnessione ai comandi di uscita o di disconnessione impostando la proprietà on-dtr-low su disconnect quando ti connetti alla console seriale.

In Google Cloud CLI, aggiungi il flag seguente al comando connect-to-serial-port:

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

Se utilizzi un client SSH di terze parti, fornisci questa opzione nel tuo comando SSH:

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

L'abilitazione dell'opzione disconnect potrebbe causare la disconnessione dell'istanza una o più volte al riavvio dell'istanza, perché il sistema operativo reimposta le porte seriali durante l'avvio.

Nota: con alcuni sistemi operativi, questa impostazione non ha effetto sulla porta seriale 1. Tuttavia, dovrebbe funzionare sulle porte da 2 a 4 per la maggior parte dei sistemi operativi e sulla porta 1 per alcuni sistemi.

L'impostazione predefinita per l'opzione on-dtr-low è none. Se utilizzi l'impostazione predefinita none, puoi riavviare l'istanza senza disconnetterti dalla console seriale, ma la console non si disconnetterà tramite metodi normali come i comandi exit o logout o normali combinazioni di tasti come Ctrl+D.

Passaggi successivi

• Scopri di più sull'API getSerialPortOutput.
• Scopri come conservare e visualizzare l'output della porta seriale anche dopo l'eliminazione di un'istanza VM.
• Leggi altri suggerimenti per la risoluzione dei problemi.
• Scopri di più sull'applicazione dei metadati.
• Scopri di più sulle chiavi SSH.