Dépannage à l'aide de la console série

Linux Windows

Cette page explique comment activer l'accès interactif à la console série d'une instance pour déboguer les problèmes de démarrage et de mise en réseau, résoudre les incidents, interagir avec le bootloader GRUB (GRand Unified Bootloader) et effectuer d'autres tâches de dépannage.

Une instance de machine virtuelle (VM) possède quatre ports série virtuels. Les interactions avec un port série sont semblables à l'utilisation d'une fenêtre de terminal, en ce sens que les entrées et les sorties sont entièrement en mode texte et qu'il n'existe pas d'interface graphique ni de support de souris. Le système d'exploitation de l'instance, le BIOS et d'autres entités de niveau système génèrent souvent des données en sortie sur les ports série, mais acceptent aussi les entrées comme les commandes ou les réponses à des invites. En règle générale, ces entités de niveau système utilisent le premier port série (port 1), que l'on désigne souvent par console série.

Si vous devez simplement afficher la sortie du port série sans émettre de commande sur la console série, vous pouvez appeler la méthode getSerialPortOutput ou recourir à Cloud Logging pour consulter les informations que votre instance a écrites sur son port série. Consultez la page Afficher les données en sortie du port série pour en savoir plus. Cependant, si vous ne parvenez pas à accéder à votre instance via SSH ou si une instance ne démarre pas complètement, vous pouvez activer un accès interactif à la console série pour vous connecter à tous les ports série de votre instance. Par exemple, vous pouvez exécuter directement des commandes et répondre aux invites du port série.

Lorsque vous activez ou désactivez le port série, vous pouvez utiliser n'importe quelle valeur booléenne acceptée par le serveur de métadonnées. Pour en savoir plus, consultez la section sur la définition de valeurs booléennes.

Avant de commencer

Si ce n'est pas déjà fait, configurez l'authentification. L'authentification est le processus permettant de valider votre identité pour accéder aux services et aux API Google Cloud. Pour exécuter du code ou des exemples depuis un environnement de développement local, vous pouvez vous authentifier auprès de Compute Engine comme suit :

Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :
Console

Lorsque vous utilisez la console Google Cloud pour accéder aux services et aux API Google Cloud, vous n'avez pas besoin de configurer l'authentification.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Définissez une région et une zone par défaut.
REST

Pour utiliser les exemples d'API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à gcloud CLI.

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes :

compute.instances.setMetadata sur la VM si l'accès interactif est activé sur une VM spécifique
compute.projects.setCommonInstanceMetadata sur le projet, si l'accès interactif est activé pour toutes les VM du projet
Rôle iam.serviceAccountUser sur le compte de service de l'instance

Activer l'accès interactif sur la console série

Vous pouvez activer l'accès interactif à la console série interactive pour des instances de VM individuelles ou pour l'ensemble d'un projet.

Activer l'accès pour un projet

L'activation de l'accès à la console série interactive sur un projet permet d'accéder à toutes les instances de VM disponibles dans ce projet.

Par défaut, l'accès au port série interactif est désactivé. Vous pouvez le désactiver explicitement en définissant la clé serial-port-enable sur FALSE. Dans les deux cas, si un paramètre est spécifié au niveau d'une instance, il remplace le paramètre au niveau du projet ou le paramètre par défaut.

Console

Dans Google Cloud Console, accédez à la page Métadonnées.
Accéder à la page "Métadonnées"
Cliquez sur Modifier pour modifier les entrées de métadonnées.
Ajoutez une entrée en spécifiant la clé serial-port-enable et la valeur TRUE.
Enregistrez les modifications.

gcloud

À l'aide de la Google Cloud CLI, saisissez la commande project-info add-metadata comme suit :

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

REST

Dans l'API, envoyez une requête à la méthode projects().setCommonInstanceMetadata, en fournissant la clé serial-port-enable avec la valeur TRUE :

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

Activer l'accès pour une instance de VM

Vous pouvez activer l'accès à la console série interactive pour une instance spécifique. Si un paramètre au niveau d'une instance est spécifié, il remplace le paramètre au niveau du projet. Vous pouvez également désactiver l'accès pour une instance spécifique, même si l'accès est activé au niveau du projet, en définissant serial-port-enable sur FALSE au lieu de TRUE. De même, vous pouvez activer l'accès pour une ou plusieurs instances même s'il est désactivé pour le projet, explicitement ou par défaut.

Console

Dans Google Cloud Console, accédez à la page Instances de VM.
Accéder à la page Instances de VM
Cliquez sur l'instance pour laquelle vous souhaitez activer l'accès.
Cliquez sur Modifier.
Sous la section Accès à distance, cochez la case Activer la connexion aux ports série.
Enregistrez les modifications.

gcloud

À l'aide de Google Cloud CLI, saisissez la commande instances add-metadata en remplaçant instance-name par le nom de votre instance.

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

REST

Dans l'API, envoyez une requête à la méthode instances().setMetadata en fournissant la clé serial-port-enable avec la valeur 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"
  }
 ]
}

Se connecter à une console série

Après avoir activé l'accès interactif pour la console série d'une instance, vous pouvez vous connecter à la console série.

Compute Engine propose une passerelle de console série globale et des passerelles de console série régionale pour chaque région Google Cloud. Vous pouvez choisir de vous connecter à la console série d'une VM à l'aide de la passerelle globale ou régionale. Cependant, nous vous recommandons d'utiliser la passerelle régionale pour une meilleure fiabilité.

Lorsque vous vous connectez à la console série à l'aide de la console Google Cloud, vous vous connectez automatiquement à la console série régionale. Lorsque vous utilisez la Google Cloud CLI, vous pouvez choisir entre la passerelle régionale ou globale. Les connexions via d'autres clients SSH ne sont compatibles qu'avec la passerelle globale.

La console série authentifie les utilisateurs avec des clés SSH. Plus précisément, vous devez ajouter votre clé SSH publique aux métadonnées du projet ou de l'instance et stocker votre clé privée sur l'ordinateur local à partir duquel vous souhaitez vous connecter. gcloud CLI et Google Cloud Console ajoutent automatiquement des clés SSH au projet. Si vous utilisez un client tiers, vous devrez peut-être ajouter les clés SSH manuellement.

Console

Pour vous connecter à la console série régionale d'une VM, procédez comme suit :

Dans Google Cloud Console, accédez à la page Instances de VM.
Accéder à la page Instances de VM
Cliquez sur l'instance à laquelle vous souhaitez vous connecter.
Sous Accès à distance, cliquez sur Se connecter à la console série pour vous connecter au port par défaut (port 1).
Si vous souhaitez vous connecter à un autre port série, cliquez sur la flèche vers le bas située à côté du bouton Se connecter à la console série et modifiez le numéro de port en conséquence.
Pour les instances Windows, ouvrez le menu déroulant situé à côté du bouton et connectez-vous au port 2 pour accéder à la console série.

gcloud

Pour vous connecter à la console série régionale ou globale d'une VM, utilisez l'une des commandes suivantes :

Recommandé : Pour vous connecter à la console série régionale d'une VM, utilisez la commande gcloud compute connect-to-serial-port et ajoutez l'option --location :
```
gcloud compute connect-to-serial-port VM_NAME \
  --location=REGION \
  --port=PORT_NUMBER
```
Pour vous connecter à la console série globale d'une VM, utilisez la commande gcloud compute connect-to-serial-port et omettez l'option --location :
```
gcloud compute connect-to-serial-port VM_NAME \
  --port=PORT_NUMBER
```

Remplacez les éléments suivants :

VM_NAME : nom de la VM pour laquelle vous souhaitez vous connecter à la console série.
REGION : région de la VM pour laquelle vous souhaitez vous connecter à la console série.
PORT_NUMBER : numéro de port que vous souhaitez connecter. Pour les VM Linux, utilisez 1 pour les VM Windows, utilisez 2. Pour en savoir plus sur les numéros de port, consultez la section Présentation de la numérotation des ports série.

Remarque : le numéro de port par défaut est 1.

Autres clients SSH

Vous pouvez vous connecter à la console série d'une instance en utilisant d'autres clients SSH tiers, à condition que la connexion au port TCP 9600 soit autorisée par le client.

Par exemple, la commande SSH suivante se connecte au port série par défaut (1) d'une instance nommée example-instance avec le nom d'utilisateur jane dans un projet dont l'ID est myproject. L'instance se trouve dans la zone us-central1-f. Remplacez private-ssh-key-file par le fichier de clé SSH privée de l'instance.

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane@ssh-serialport.googleapis.com

Plus précisément, vous vous connectez à la console série d'une instance en utilisant les informations de connexion et d'adresse suivantes :

project-id.zone.instance-name.username.options@ssh-serialport.googleapis.com

Remplacez l'élément suivant :

project-id : ID de projet pour cette instance.
zone : zone de l'instance.
instance-name : nom de l'instance.
username : nom d'utilisateur qui vous permet de vous connecter à l'instance. En règle générale, il s'agit du nom d'utilisateur sur votre ordinateur local.
options : options supplémentaires que vous pouvez spécifier pour cette connexion. Par exemple, vous pouvez spécifier un port série et une option avancée. Le numéro de port peut être compris entre 1 et 4. Pour en savoir plus sur les numéros de port, consultez la section Présentation de la numérotation des ports série. En cas d'omission, vous serez connecté au port série 1.

Si vous vous connectez à une instance de VM Windows, sélectionnez le port 2 en exécutant la commande suivante :

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.port=2@ssh-serialport.googleapis.com

Si vous rencontrez des problèmes de connexion avec un client SSH tiers, vous pouvez exécuter gcloud compute connect-to-serial-port avec l'option de ligne de commande --dry-run pour afficher la commande SSH exécutée en votre nom, puis comparer les options avec celles de la commande que vous utilisez.

Configurer une connexion sécurisée

Lorsque vous utilisez un client SSH tiers autre que Google Cloud CLI, vous pouvez vous assurer que vous êtes protégé contre toute tentative d'usurpation d'identité ou d'attaque de l'intercepteur en vérifiant la clé SSH du serveur de port série de Google. Pour configurer votre système afin de vérifier la clé SSH du serveur, procédez comme suit :

Téléchargez la clé SSH du serveur de port série de Google.
Ouvrez votre fichier d'hôtes connus, généralement situé à l'adresse ~/.ssh/known_hosts.
Enregistrez le contenu de la clé SSH du serveur, en ajoutant ssh-serialport.googleapis.com en préfixe à la clé. Par exemple, si la clé du serveur contient la ligne ssh-rsa AAAAB3NzaC1yc..., ~/.ssh/known_hosts doit comporter une ligne semblable à la suivante :
```
ssh-serialport.googleapis.com ssh-rsa AAAAB3NzaC1yc...
```

Pour des raisons de sécurité, Google peut parfois modifier la clé SSH du serveur de port série Google. Si votre client ne parvient pas à authentifier la clé du serveur, annulez immédiatement la tentative de connexion et suivez les étapes précédentes pour télécharger une nouvelle clé SSH de serveur de port série Google.

Si vous continuez à recevoir une erreur d'authentification de l'hôte du client après la mise à jour de la clé hôte, arrêtez les tentatives de connexion au port série et contactez l'assistance Google. N'indiquez aucune information d'identification sur une connexion où l'authentification de l'hôte a échoué.

Se déconnecter de la console série

Pour vous déconnecter de la console série :

Appuyez sur la touche ENTER.
Saisissez ~. (tilde, suivi d'un point).

Vous pouvez découvrir d'autres commandes en saisissant ~? ou en consultant la page de manuel pour SSH :

man ssh

N'essayez pas de vous déconnecter au moyen de l'une des méthodes suivantes :

Combinaison de touches CTRL+ALT+DELETE ou autres combinaisons similaires. Cela ne fonctionne pas, car la console série ne reconnaît pas les combinaisons de clavier PC.
La commande exit ou logout ne fonctionne pas, car l'invité n'a connaissance d'aucune connexion réseau ou modem. L'utilisation de ces commandes provoque la fermeture, puis la réouverture de la console, sans fermeture de votre session. Si vous souhaitez activer les commandes exit et logout pour votre session, définissez l'option on-dtr-low.

Se connecter à une console série via une invite de connexion

Si vous tentez de résoudre un problème sur une VM entièrement démarrée ou survenu après un démarrage en mode mono-utilisateur, les informations de connexion vous seront probablement demandées au moment d'accéder à la console série.

Par défaut, les images système Linux fournies par Google ne sont pas configurées pour autoriser les connexions par mot de passe aux utilisateurs locaux. Toutefois, les images Windows fournies par Google sont configurées pour autoriser les connexions par mot de passe aux utilisateurs locaux.

Si votre VM exécute une image préconfigurée avec des connexions de port série, vous devez définir un mot de passe local sur la VM avant de pouvoir vous connecter à la console série, si vous y êtes invité. Vous pouvez configurer un mot de passe local après vous être connecté à la VM ou en utilisant un script de démarrage.

Configurer un mot de passe local à l'aide d'un script de démarrage

Vous pouvez utiliser un script de démarrage pour configurer un mot de passe local permettant de vous connecter à la console série pendant ou après la création de la VM.

Les instructions suivantes décrivent comment configurer un mot de passe local après la création de la VM.

Dans Google Cloud Console, accédez à la page Instances de VM.

Accéder à la page "Instances de VM"
Sélectionnez la VM pour laquelle vous souhaitez ajouter le mot de passe local.
Cliquez sur Modifier.
Linux
1. Accédez à la section Métadonnées > Automatisation.
2. Si la VM dispose d'un script de démarrage existant, copiez et collez celui-ci dans un endroit sûr.
3. Ajoutez le script de démarrage suivant :
  #!/bin/bash useradd USERNAME echo USERNAME:PASSWORD | chpasswd usermod -aG google-sudoers USERNAME
  Remplacez les éléments suivants :
  - USERNAME : nom d'utilisateur que vous souhaitez ajouter
  - PASSWORD : mot de passe du nom d'utilisateur. Évitez les mots de passe simples, car certains systèmes d'exploitation peuvent imposer une longueur et une complexité minimales.
Windows
1. Accédez à la section Métadonnées personnalisées.
2. Si la VM dispose d'un script de démarrage existant, copiez et collez celui-ci dans un endroit sûr.
3. Cliquez sur Ajouter un élément.
4. Dans le champ Clé, saisissez windows-startup-script-cmd.
5. Dans le champ Valeur, saisissez les valeurs suivantes :
  net user USERNAME PASSWORD /ADD /Y net localgroup administrators USERNAME /ADD
  Remplacez les éléments suivants :
  - USERNAME : nom d'utilisateur que vous souhaitez ajouter
  - PASSWORD : mot de passe du nom d'utilisateur
Cliquez sur Enregistrer.
Pour redémarrer la VM, cliquez sur Réinitialiser. Pour en savoir plus, consultez la section Réinitialiser une VM.
Connectez-vous à la console série.
Saisissez vos informations de connexion lorsque vous y êtes invité.
Supprimez le script de démarrage de la VM après la création de l'utilisateur.

Configurer un mot de passe local à l'aide de `passwd` sur la VM

Les instructions suivantes décrivent comment définir un mot de passe d'utilisateur local sur une VM afin que cet utilisateur puisse se connecter à la console série de cette VM en utilisant le mot de passe spécifié.

Connectez-vous à la VM. Remplacez instance-name par le nom de votre instance.
```
gcloud compute ssh instance-name
```
Sur la VM, créez un mot de passe local à l'aide de la commande suivante. Un mot de passe est alors défini pour l'utilisateur au nom duquel vous êtes actuellement connecté.
```
sudo passwd $(whoami)
```
Suivez les instructions pour créer un mot de passe.
Ensuite, déconnectez-vous de l'instance et connectez-vous à la console série.
Saisissez vos informations de connexion lorsque vous y êtes invité.

Configurer une connexion sur d'autres ports série

Les invites de connexion sont activées sur le port 1 par défaut sur la plupart des systèmes d'exploitation Linux. Toutefois, le port 1 est souvent surchargé en raison des données de journalisation et autres informations enregistrées sur le port. Pour contourner ce problème, il est possible d'activer une invite de connexion sur un autre port, tel que le port 2 (ttyS1), en exécutant l'une des commandes suivantes sur votre VM. Consultez la liste des ports disponibles pour une VM dans la section Présentation de la numérotation des ports série.

Le tableau suivant répertorie les images préconfigurées avec une connexion à la console série et les ports par défaut.

Système d'exploitation	Ports avec une invite de connexion par défaut	Gestion des services
CentOS 6	1	`upstart`
CentOS 7	1	`systemd`
CoreOS	1	`systemd`
COS	1	`systemd`
Debian 8	1	`systemd`
Debian 9	1	`systemd`
openSUSE 13	1	`systemd`
OpenSUSE Leap	1	`systemd`
RHEL 6	1	`upstart`
RHEL 7	1	`systemd`
SLES 11	1	`sysvinit`
SLES 12	1	`systemd`
Ubuntu 14.04	1	`upstart`
Ubuntu 16.04	1	`systemd`
Ubuntu 17.04	1	`systemd`
Ubuntu 17.10	1	`systemd`
Windows	COM2	N/A

Pour activer les invites de connexion sur des ports série supplémentaires, procédez comme suit.

systemd

Pour les systèmes d'exploitation Linux utilisant systemd :

Activez temporairement le service jusqu'au prochain redémarrage :
```
sudo systemctl start serial-getty@ttyS1.service
```
Activez le service en permanence, en commençant par le prochain redémarrage :
```
sudo systemctl enable serial-getty@ttyS1.service
```

upstart

Pour les systèmes d'exploitation Linux utilisant upstart :

Créez un fichier /etc/init/ttyS1.conf en copiant et en modifiant un fichier ttyS1 existant pour refléter ttyS0.conf. Exemple :
- Sous Ubuntu 14.04 :
```
sudo sh -c "sed -e s/ttyS0/ttyS1/g < /etc/init/ttyS0.conf > /etc/init/ttyS1.conf"
```
  Remarque : Ubuntu 12.04 n'a pas de ttyS0.conf. Nous vous recommandons donc de copier le fichier ttysS0.conf depuis Ubuntu 14.04 et de l'utiliser sur Ubuntu 12.04.
- Sous RHEL 6.8 et 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"
```
Commencez par une invite de connexion sur ttyS1 sans redémarrage :
```
sudo start ttyS1
```

sysvinit

Pour les systèmes d'exploitation Linux utilisant sysvinit, exécutez la commande suivante :

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

Présentation de la numérotation des ports série

Chaque instance de machine virtuelle possède quatre ports série. Pour des raisons de cohérence avec l'API getSerialPortOutput, chaque port est numéroté de 1 à 4. Linux et d'autres systèmes semblables numérotent leurs ports série de 0 à 3. Par exemple, sur de nombreuses images de systèmes d'exploitation, les périphériques correspondants sont référencés de /dev/ttyS0 à /dev/ttyS3. Windows référence les ports série sous les désignations COM1 à COM4. Pour vous connecter à ce que Windows considère comme COM3 et que Linux considère comme ttyS2, vous devez spécifier le port 3. Le tableau ci-dessous vous aidera à déterminer le port auquel vous souhaitez vous connecter.

Ports série d'instance de machine virtuelle	Ports série Linux standard	Ports COM Windows
`1`	`/dev/ttyS0`	`COM1`
`2`	`/dev/ttyS1`	`COM2`
`3`	`/dev/ttyS2`	`COM3`
`4`	`/dev/ttyS3`	`COM4`

Notez que de nombreuses images Linux utilisent le port 1 (/dev/ttyS0) pour enregistrer les messages du noyau et des programmes système.

Envoyer une interruption série

La fonctionnalité Magic SysRq key vous permet d'effectuer des tâches de bas niveau, quel que soit l'état du système, comme synchroniser des systèmes de fichiers, redémarrer l'instance, supprimer des processus, désinstaller des systèmes de fichiers, etc.

Pour envoyer une commande Magic SysRq en utilisant une interruption série simulée :

Appuyez sur la touche ENTER.
Saisissez ~B (tilde, suivi de majuscule B).
Saisissez la commande Magic SysRq.

Afficher les journaux d'audit de la console série

Compute Engine fournit des journaux d'audit pour savoir qui s'est connecté et déconnecté de la console série d'une instance. Pour afficher les journaux, vous devez disposer des autorisations d'accès à la visionneuse de journaux ou du rôle de lecteur ou d'éditeur de projet.

Dans Google Cloud Console, accédez à la page Explorateur de journaux.
Accéder à l'explorateur de journaux
Développez le menu déroulant et sélectionnez GCE VM Instance.
Dans la barre de recherche, saisissez ssh-serialport.googleapis.com et appuyez sur Entrée.
La liste des journaux d'audit s'affiche. Les journaux décrivent les connexions et les déconnexions d'une console série. Cliquez sur l'une des entrées pour plus de détails :

Quel que soit le journal d'audit, il est possible de :

Développer la propriété protoPayload.
Rechercher methodName pour voir l'activité à laquelle ce journal s'applique (requête de connexion ou de déconnexion). Par exemple, si ce journal enregistre une déconnexion de la console série, le nom de la méthode sera "google.ssh-serialport.v1.disconnect". De même, un journal de connexion indiquera "google.ssh-serialport.v1.connect". Une entrée de journal d'audit est enregistrée au début et à la fin de chaque session sur la console série.

Les propriétés de journal d'audit varient selon les différents types de journaux. Par exemple, les journaux d'audit concernant les connexions sont dotés de propriétés spécifiques aux journaux de connexion, tandis que les journaux d'audit concernant les déconnexions possèdent leur propre ensemble de propriétés. Certaines propriétés de journal d'audit sont également partagées entre les deux types de journaux.

Ensemble des journaux de console série

Le tableau suivant fournit les propriétés des journaux d'audit et leurs valeurs pour tous les journaux de la console série :

Valeur	Valeur
`requestMetadata.callerIp`	Adresse IP et numéro de port d'origine de la connexion.
`serviceName`	`ssh-serialport.googleapis.com`
`resourceName`	Chaîne contenant l'ID du projet, la zone, le nom de l'instance et le numéro de port série pour indiquer la console série correspondante. Par exemple, `projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2` correspond au numéro de port 2, également appelé COM2 ou /dev/ttyS1, pour l'instance `example-instance`.
`resource.labels`	Propriétés d'identification pour l'ID d'instance, la zone et l'ID de projet.
`timestamp`	Horodatage indiquant le début ou la fin de la session.
`severity`	`NOTICE`
`operation.id`	Chaîne d'identification unique de la session, qui permet d'associer une entrée de déconnexion à l'entrée de connexion correspondante.
`operation.producer`	`ssh-serialport.googleapis.com`

Journaux de connexion

Le tableau suivant fournit les propriétés des journaux d'audit et leurs valeurs spécifiques aux journaux de connexion :

Valeur	Valeur
`methodName`	`google.ssh-serialport.v1.connect`
`status.message`	`Connection succeeded.`
`request.serialConsoleOptions`	Toutes les options spécifiées avec la requête, y compris le numéro de port série.
`request.@type`	`type.googleapis.com/google.compute.SerialConsoleSessionBegin`
`request.username`	Nom d'utilisateur spécifié pour cette requête, utilisé pour sélectionner la clé publique à associer.
`operation.first`	`TRUE`
`status.code`	Pour toute demande de connexion réussie, une valeur `status.code` de `google.rpc.Code.OK` indique que l'opération s'est terminée sans erreur. Comme la valeur d'énumération de cette propriété est `0`, la propriété `status.code` n'est pas affichée. Cependant, tout code vérifiant une valeur `status.code` de `google.rpc.Code.OK` fonctionnera comme prévu.

Journaux de déconnexion

Le tableau suivant fournit les propriétés des journaux d'audit et leurs valeurs spécifiques aux journaux de déconnexion :

Valeur	Valeur
`methodName`	`google.ssh-serialport.v1.disconnect`
`response.duration`	Durée de la session en secondes.
`response.@type`	`type.googleapis.com/google.compute.SerialConsoleSessionEnd`
`operation.last`	`TRUE`

Journaux des échecs de connexion

Lorsqu'une connexion échoue, Compute Engine crée une entrée de journal d'audit. Un journal d'échec de connexion est semblable à une entrée de connexion réussie, mais possède les propriétés suivantes pour indiquer un échec de connexion.

Propriété Valeur

severity ERROR

Propriété	Valeur
`severity`	`ERROR`
`status.code`	Le code d'erreur canonique de l'API Google qui correspond le mieux à l'erreur. Les codes d'erreur suivants peuvent apparaître : `google.rpc.Code.INVALID_ARGUMENT` : la connexion a échoué, car le client a fourni un numéro de port non valide ou a tenté d'atteindre un canal inconnu. Consultez la liste des numéros de port valides. `google.rpc.Code.PERMISSION_DENIED` : vous n'avez pas activé la console série interactive sur le serveur de métadonnées. Pour en savoir plus, consultez la section Activer l'accès interactif sur la console série. `google.rpcCode.UNAUTHENTICATED` : aucune clé SSH n'a été trouvée ou aucune clé SSH correspondante n'a été trouvée pour cette instance. Vérifiez que vous êtes authentifié sur l'instance de VM. `google.rpc.Code.UNKNOWN` : une erreur inconnue s'est produite lors de votre requête. Vous pouvez contacter Google à l'aide du groupe de discussion gce ou remplir un rapport de bug.
`status.message`	Message dans un format lisible pour cette entrée.

status.code

Le code d'erreur canonique de l'API Google qui correspond le mieux à l'erreur. Les codes d'erreur suivants peuvent apparaître :

google.rpc.Code.INVALID_ARGUMENT : la connexion a échoué, car le client a fourni un numéro de port non valide ou a tenté d'atteindre un canal inconnu. Consultez la liste des numéros de port valides.
google.rpc.Code.PERMISSION_DENIED : vous n'avez pas activé la console série interactive sur le serveur de métadonnées. Pour en savoir plus, consultez la section Activer l'accès interactif sur la console série.
google.rpcCode.UNAUTHENTICATED : aucune clé SSH n'a été trouvée ou aucune clé SSH correspondante n'a été trouvée pour cette instance. Vérifiez que vous êtes authentifié sur l'instance de VM.
google.rpc.Code.UNKNOWN : une erreur inconnue s'est produite lors de votre requête. Vous pouvez contacter Google à l'aide du groupe de discussion gce ou remplir un rapport de bug.

status.message Message dans un format lisible pour cette entrée.

Désactiver l'accès interactif à la console série

Pour désactiver l'accès interactif à la console série, vous pouvez modifier les métadonnées sur l'instance ou le projet spécifique ou définir une règle d'administration qui désactive l'accès interactif à la console série pour toutes les instances de VM sur un ou plusieurs projets faisant partie de l'organisation.

Désactiver l'accès interactif à la console série sur une instance ou un projet particulier

Les propriétaires et les éditeurs du projet, ainsi que les utilisateurs ayant obtenu le rôle compute.instanceAdmin.v1, peuvent désactiver l'accès à la console série en modifiant les métadonnées de l'instance ou du projet en question. De la même manière que pour activer l'accès à la console série, définissez les métadonnées serial-port-enable sur FALSE :

serial-port-enable=FALSE

Par exemple, à l'aide de la Google Cloud CLI, vous pouvez appliquer ces métadonnées à une instance spécifique comme ceci :

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

Pour appliquer les métadonnées au projet :

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

Désactiver l'accès interactif à la console série via une règle d'administration

Si le rôle orgpolicy.policyAdmin vous a été attribué dans l'organisation, vous pouvez définir une règle d'administration qui empêche l'accès interactif à la console série, que cet accès soit activé ou non sur le serveur de métadonnées. Une fois définie, la règle remplace effectivement la clé de métadonnées serial-port-enable et aucun utilisateur de l'organisation ou du projet ne peut activer l'accès à la console série interactive. Par défaut, cette contrainte est définie sur FALSE.

La contrainte permettant de désactiver l'accès interactif à la console série est la suivante :

compute.disableSerialPortAccess

Pour définir cette règle dans l'organisation, suivez les instructions ci-dessous. Après avoir configuré une règle, vous pouvez accorder des exceptions par projet.

gcloud

Pour définir la règle à l'aide de Google Cloud CLI, exécutez la commande resource-manager enable-enforce. Remplacez organization-id par votre ID d'organisation. Exemple : 1759840282.

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

REST

Pour définir une règle dans l'API, envoyez une requête POST à l'URL suivante : Remplacez organization-name par le nom de votre organisation. Par exemple, organizations/1759840282.

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

Le corps de la requête doit contenir un objet policy avec la contrainte suivante :

"constraint": "constraints/compute.disableSerialPortAccess"

Exemple :

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

La règle étant effective immédiatement, les autorisations d'accès interactif à la console série sont instantanément interrompues pour tous les projets de l'organisation.

Pour désactiver temporairement la règle, utilisez la commande disable-enforce :

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

Vous pouvez également effectuer une requête d'API dans laquelle le corps de la requête définit le paramètre enforced sur FALSE :

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

Définir la règle d'administration au niveau du projet

Vous pouvez définir la même règle d'administration pour chaque projet, ce qui a pour effet d'ignorer le paramètre défini au niveau de l'organisation.

gcloud

Pour désactiver l'application de cette règle dans le cadre d'un projet spécifique, procédez comme suit. Remplacez project-id par votre ID de projet :

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

Vous pouvez activer l'application de cette règle en utilisant la commande enable-enforce avec les mêmes valeurs.

REST

Dans l'API, envoyez une requête POST à l'URL suivante pour activer l'accès interactif à la console série pour le projet, en remplaçant project-id par l'ID du projet :

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

Le corps de la requête doit contenir un objet policy avec la contrainte suivante :

"constraint": "constraints/compute.disableSerialPortAccess"

Exemple :

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

Conseils et astuces

Si vous rencontrez des problèmes de connexion avec un client SSH tiers mais que gcloud compute connect-to-serial-port se connecte correctement, vous pouvez exécuter gcloud compute connect-to-serial-port avec l'option de ligne de commande --dry-run pour afficher la commande SSH exécutée en votre nom et comparer les options avec celles de la commande que vous utilisez.
Pour définir le débit binaire, également appelé débit en bauds, vous pouvez choisir la valeur de votre choix, telle que stty 9600. Toutefois, la fonctionnalité force normalement le taux effectif à 115 200 bps (environ 11,5 Ko/s). En effet, de nombreuses images publiques ralentissent le débit, par exemple 9 600 bits sur la console série, et démarrent lentement.
Certaines images d'OS présentent des valeurs par défaut inadaptées sur le port série. Par exemple, sur CentOS 7, la valeur stty icrnl par défaut pour la touche Entrée de la console correspond à l'envoi d'un CR, alias ^M. L'interface système bash peut masquer ce problème jusqu'à ce que vous définissiez un mot de passe. Vous vous demandez alors pourquoi il semble bloqué à l'invite password:.
Certaines images publiques ont des clés de contrôle de tâches désactivées par défaut si une interface système est reliée à un port selon certains paramètres. Voici quelques exemples de ces clés : ^Z et ^C. La commande setsid peut résoudre ce problème. Dans tous les cas, si le message job control is disabled in this shell s'affiche, veillez à ne pas exécuter les commandes car vous devrez alors les interrompre.
Il peut être utile d'indiquer au système la taille de la fenêtre que vous utilisez, afin que le bash et les éditeurs puissent la gérer correctement. Sinon, vous pourriez rencontrer un comportement d'affichage anormal, car le bash ou les éditeurs tentent de traiter l'affichage à partir d'hypothèses erronées quant au nombre de lignes et de colonnes disponibles. Utilisez les commandes stty rows Y cols X et stty -a pour afficher le paramètre. Par exemple : stty rows 60 cols 120 (si votre fenêtre comporte 120 caractères sur 60 lignes).
Si vous vous connectez en SSH d'une machine A à une machine B, puis à une machine C (et ainsi de suite), créant ainsi une session SSH imbriquée, et que vous voulez utiliser des commandes tilde (~) pour vous déconnecter ou envoyer un signal d'interruption série, vous devez ajouter à la commande autant de caractères "~" que nécessaire pour accéder au bon client SSH. Une commande qui suit un seul caractère "~" sera interprétée par le client SSH sur la machine A, deux caractères "~" consécutifs seront interprétés par le client sur la machine B, et ainsi de suite. Il suffit d'appuyer une seule fois sur Entrée, car l'action est transmise jusqu'à la destination SSH la plus profonde. Cela est valable pour toutes les utilisations de clients SSH qui fournissent la fonctionnalité d'échappement "~".

Si vous ne savez plus le nombre de caractères "~" dont vous avez besoin, appuyez sur la touche Entrée, puis saisissez les caractères "~" un par un jusqu'à recevoir un écho "~" de l'instance. Vous saurez ainsi que vous avez atteint la fin de la chaîne et que, pour envoyer une commande "~" au client SSH le plus imbriqué, vous devez saisir un caractère "~" de moins que votre saisie initiale.

Options avancées

Contrôler le nombre maximal de connexions

Vous pouvez définir la propriété max-connections pour contrôler le nombre de connexions simultanées pouvant être effectuées sur ce port série en même temps. Le nombre maximal de connexions par défaut est de 5. Exemple :

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

Définir les options de répétition

Par défaut, chaque fois que vous vous connectez à la console série, les 10 dernières lignes de données sont répétées, que celles-ci aient été lues ou non par un autre client SSH. Les options suivantes permettent de modifier ce paramètre et de contrôler le nombre et la sélection des lignes renvoyées :

replay-lines=N : définissez N sur le nombre de lignes que vous souhaitez rejouer. Par exemple, si N est défini sur 50, les 50 dernières lignes des résultats de la console seront répétées.
replay-bytes=N : relance les octets N les plus récents. Vous pouvez également définir N sur new, ce qui rejoue toutes les sorties qui n'ont encore été envoyées à aucun client.
replay-from=N : relance la sortie à partir d'un index d'octets absolu que vous fournissez. Pour obtenir la valeur indexée actuelle des résultats de la console série, envoyez une requête getSerialPortOutput. Si vous définissez replay-from, toutes les autres options de relecture sont ignorées.

Avec Google Cloud CLI, ajoutez la commande suivante à votre commande connect-to-serial-port, où N correspond au nombre de lignes spécifié (ou octets ou index absolus, selon l'option de relecture sélectionnée) :

--extra-args replay-lines=N

Si vous utilisez un client SSH tiers, indiquez cette option dans votre commande 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

Vous pouvez également combiner ces options. Exemple :

replay-lines=N et replay-bytes=new: Répétez le nombre de lignes spécifié OU répétez tous les résultats qui n'ont pas encore été envoyés à un client, selon la valeur la plus élevée. Avec cette combinaison d'indicateurs, le premier client à se connecter verra tous les résultats envoyés au port série, et les clients qui se connecteront par la suite ne verront que les N dernières lignes. Exemples :

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 et replay-bytes=M: Répétez les lignes jusqu'à, au plus, le nombre de lignes ou d'octets défini par ces indicateurs, selon le moins élevé des deux. Avec cette option, la répétition sera limitée à N ou M octets.

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

Traiter des résultats ignorés

Les derniers 1 Mio de résultats pour chaque port série sont toujours disponibles et, de manière générale, votre client SSH ne doit omettre aucune sortie du port série. Si, pour une raison ou une autre, votre client SSH cesse d'accepter des résultats pendant un certain temps tout en restant connecté, et que de nouvelles données au-delà de 1 Mio sont générées, certains résultats ont probablement été ignorés par le client SSH. Lorsque votre client SSH n'accepte pas les données assez rapidement pour suivre la sortie sur le port série, définissez la propriété on-dropped-output pour déterminer le comportement de la console.

Définissez l'une des options applicables suivantes avec cette propriété :

insert-stderr-note : insère une note dans le fichier stderr du client SSH, indiquant que la sortie a été supprimée. Il s'agit de l'option par défaut.
ignore : supprime silencieusement la sortie et ne fait rien.
disconnect : arrête la connexion.

Exemple :

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

Activer la déconnexion à l'aide des commandes "exit" ou "logout"

Vous pouvez activer la déconnexion sur les commandes de sortie ou de déconnexion en définissant la propriété on-dtr-low sur disconnect lorsque vous vous connectez à la console série.

Dans la Google Cloud CLI, ajoutez l'option suivante à votre commande connect-to-serial-port :

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

Si vous utilisez un client SSH tiers, indiquez cette option dans votre commande 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

L'activation de l'option disconnect peut entraîner une ou plusieurs déconnexions de votre instance lors de son redémarrage, car le système d'exploitation réinitialise les ports série au démarrage.

Le paramètre par défaut de l'option on-dtr-low est none. Si vous utilisez le paramètre par défaut none, vous pouvez redémarrer votre instance sans être déconnecté de la console série. Cependant, la console ne se déconnectera pas par les moyens habituels tels que les commandes exit ou logout, ou les combinaisons de touches courantes comme Ctrl+D.

Étape suivante

En savoir plus sur l'API getSerialPortOutput.
Découvrez comment conserver et afficher la sortie du port série, même après la suppression d'une instance de VM.
Découvrez les conseils de dépannage.
Obtenez plus d'informations sur l'application des métadonnées.
Renseignez-vous sur les clés SSH.

Dépannage à l'aide de la console série

Avant de commencer

Console

gcloud

REST

Autorisations requises pour cette tâche

Activer l'accès interactif sur la console série

Activer l'accès pour un projet

Console

gcloud

REST

Activer l'accès pour une instance de VM

Console

gcloud

REST

Se connecter à une console série

Console

gcloud

Autres clients SSH

Se déconnecter de la console série

Se connecter à une console série via une invite de connexion

Configurer un mot de passe local à l'aide d'un script de démarrage

Linux

Windows

Configurer un mot de passe local à l'aide de passwd sur la VM

Configurer une connexion sur d'autres ports série

systemd

upstart

sysvinit

Présentation de la numérotation des ports série

Envoyer une interruption série

Afficher les journaux d'audit de la console série

Désactiver l'accès interactif à la console série

Désactiver l'accès interactif à la console série sur une instance ou un projet particulier

Désactiver l'accès interactif à la console série via une règle d'administration

gcloud

REST

Définir la règle d'administration au niveau du projet

gcloud

REST

Conseils et astuces

Options avancées

Contrôler le nombre maximal de connexions

Définir les options de répétition

Traiter des résultats ignorés

Activer la déconnexion à l'aide des commandes "exit" ou "logout"

Étape suivante

Configurer un mot de passe local à l'aide de `passwd` sur la VM