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.

Remarque :Vous ne pouvez pas activer l'accès interactif à la console série pour les instances bare metal. La console série est en lecture seule pour les instances bare metal. Pour exécuter des commandes de manière interactive, vous pouvez vous connecter à l'instance à l'aide de SSH une fois qu'elle a démarré.

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 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 en sélectionnant l'une des options suivantes:
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

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

     gcloud init

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

  REST

  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.

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

  gcloud init

  Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud.

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.

Avertissement : La console série interactive n'accepte pas les restrictions d'accès basées sur l'adresse IP, telles que les listes d'autorisation d'adresses IP, sauf si vous utilisezVPC Service Controls. Si vous activez l'accès interactif à la console série sur une instance, les clients peuvent tenter de se connecter à cette instance depuis n'importe quelle adresse IP. Autrement dit, quiconque connaissant la clé SSH, le nom d'utilisateur, l'ID de projet, la zone et le nom de l'instance pourra se connecter à cette instance.

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

1. Dans la console Google Cloud, accédez à la page Métadonnées.

   Accéder à la page "Métadonnées"

2. Cliquez sur Modifier pour modifier les entrées de métadonnées.
3. Ajoutez une entrée en spécifiant la clé serial-port-enable et la valeur TRUE.
4. 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

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

   Accéder à la page Instances de VM

2. Cliquez sur l'instance pour laquelle vous souhaitez activer l'accès.
3. Cliquez sur Modifier.
4. Sous la section Accès à distance, cochez la case Activer la connexion aux ports série.
5. 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"
  }
 ]
}

Configurer la console série pour une instance bare metal

Pour les instances bare metal, augmentez le débit binaire, également appelé débit en bauds, de la console série à 115 200 bps (environ 11,5 Ko/s). Utiliser une vitesse plus lente entraîne une sortie de console illisible ou manquante.

La configuration du bootloader varie selon les systèmes d'exploitation et les versions. Pour connaître la marche à suivre, reportez-vous à la documentation du distributeur de l'OS.

Si vous modifiez le débit de données sur la ligne de commande pour la session en cours, utilisez une commande semblable à la suivante:

console=ttyS0,115200

Si vous modifiez la configuration GRUB, utilisez une commande semblable à la suivante:

serial --speed=115200

Assurez-vous de mettre à jour la configuration réelle du bootloader. Vous pouvez le faire avec update-grub, grub2-mkconfig ou une commande similaire.

Se connecter à une console série

Compute Engine propose des passerelles de console série régionales pour chaque région Google Cloud. Après avoir activé l'accès interactif pour la console série d'une VM, vous pouvez vous connecter à une console série régionale.

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.

Attention :Il est déconseillé de se connecter directement à la console série à l'aide de son adresse IP plutôt que de son nom d'hôte. Les adresses IP de la console série peuvent changer sans préavis.

Console

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

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

   Accéder à la page Instances de VM

2. Cliquez sur l'instance à laquelle vous souhaitez vous connecter.
3. Sous Accès à distance, cliquez sur Se connecter à la console série pour vous connecter au port par défaut (port 1).
4. 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.
5. 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 d'une VM, utilisez la commande gcloud compute connect-to-serial-port:

  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.

• PORT_NUMBER : numéro de port que vous souhaitez connecter. Pour les VM Linux, utilisez 1, et 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

Remarque : Vous devez avoir ajouté votre clé publique aux métadonnées du projet ou de l'instance avant de pouvoir utiliser un client SSH tiers. Si vous avez déjà utilisé gcloud CLI pour vous connecter à d'autres instances dans le même projet, votre PUBLIC_KEY_FILE est probablement situé à l'adresse $HOME/.ssh/google_compute_engine.pub. Si vous ne vous êtes encore jamais connecté à une instance de ce projet (vous n'avez donc jamais ajouté de clés publiques), vous devez ajouter vos clés SSH aux métadonnées du projet ou de l'instance avant de pouvoir vous connecter à l'aide d'un client SSH tiers. Consultez la section Gérer des clés SSH dans les métadonnées pour en savoir plus.

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.

Pour vous connecter à la console série régionale d'une VM, exécutez l'une des commandes suivantes en fonction de l'OS de votre VM:

• Pour vous connecter à une VM Linux:

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

• Pour vous connecter à une VM Windows:

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

Remplacez les éléments suivants :

• PRIVATE_SSH_KEY_FILE: clé SSH privée de l'instance.
• PROJECT_ID : ID du projet pour cette instance de VM.
• ZONE: zone de l'instance de VM
• REGION: région de l'instance de VM.
• VM_NAME : nom de l'instance de VM.
• 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.

Attention: La passerelle de console série globale a été abandonnée le 30 avril 2024 et n'est plus disponible pour les nouveaux projets ni pour ceux qui n'ont pas encore été utilisés. Si vous utilisez la passerelle de console série globale, passez plutôt aux passerelles régionales. Pour en savoir plus, consultez la section Arrêt de la passerelle de console série globale.

Pour vous connecter à la passerelle de console série globale, remplacez REGION-ssh-serialport.googleapis.com par ssh-serialport.googleapis.com comme nom d'hôte.

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 :

1. Téléchargez la clé SSH du serveur pour la console série que vous utiliserez :
   • Pour les connexions régionales, la clé SSH du serveur d'une région se trouve sur https://www.gstatic.com/vm_serial_port/region/region.pub.
   • Pour les connexions globales, téléchargez la clé SSH du serveur de port série de Google.
2. Ouvrez votre fichier d'hôtes connus, généralement situé à l'adresse ~/.ssh/known_hosts.

3. Ajoutez le contenu de la clé SSH du serveur, en ajoutant le nom d'hôte du serveur en préfixe à la clé. Par exemple, si la clé du serveur us-central1 contient la ligne ssh-rsa AAAAB3NzaC1yc..., ~/.ssh/known_hosts doit comporter une ligne semblable à la suivante:

   [us-central1-ssh-serialport.googleapis.com]:9600 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 :

1. Appuyez sur la touche ENTER.
2. 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.

Remarque : Cette étape n'est pas obligatoire si vous interagissez avec le système pendant ou avant le démarrage, ou avec un service basé sur un port série ne nécessitant pas de mot de passe. Cette étape n'est pas nécessaire non plus si vous avez configuré getty pour vous connecter automatiquement sans mot de passe à l'aide de l'indicateur "-a root".

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.

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

   Accéder à la page "Instances de VM"

2. Sélectionnez la VM pour laquelle vous souhaitez ajouter le mot de passe local.

3. 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

4. Cliquez sur Enregistrer.

5. Pour redémarrer la VM, cliquez sur Réinitialiser. Pour en savoir plus, consultez la section Réinitialiser une VM.

6. Connectez-vous à la console série.

7. Saisissez vos informations de connexion lorsque vous y êtes invité.

8. 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é.

1. Connectez-vous à la VM. Remplacez instance-name par le nom de votre instance.

   gcloud compute ssh instance-name

2. 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)

3. Suivez les instructions pour créer un mot de passe.

4. Ensuite, déconnectez-vous de l'instance et connectez-vous à la console série.

5. 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.

Remarque : Les instructions ci-dessous sont réparties entre les systèmes d'exploitation qui exécutent systemd, upstart ou sysvinit. Pour l'ensemble des instructions, vous pouvez remplacer ttyS1 par un autre port série si vous le souhaitez.

systemd

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

• Activez temporairement le service jusqu'au prochain redémarrage :

  sudo systemctl start [e-mail]

• Activez le service en permanence, en commençant par le prochain redémarrage :

  sudo systemctl enable [e-mail]

upstart

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

1. 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. Google vous recommande donc de copier le fichier ttysS0.conf depuis Ubuntu 14.04 et de l'utiliser sur l'instance exécutant 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"

2. 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 's/^#T([01])/T\1/' /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 suivant 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 :

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

Remarque  La fonctionnalité Magic SysRq est normalement activée à l'aide de combinaisons de touches enfoncées simultanément sur un clavier d'ordinateur, mais il n'existe pas d'équivalent direct sur un port série. Cette méthode est recommandée pour accéder à la fonctionnalité 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.

1. Dans Google Cloud Console, accédez à la page Explorateur de journaux.

   Accéder à l'explorateur de journaux

2. Développez le menu déroulant et sélectionnez GCE VM Instance.
3. Dans la barre de recherche, saisissez ssh-serialport.googleapis.com et appuyez sur Entrée.

4. 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 :

1. Développer la propriété protoPayload.
2. 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
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).

• Par exemple, si vous vous connectez à l'aide de SSH de la machine A à la machine B, puis à la machine C, créant ainsi une session SSH imbriquée, et que vous souhaitez utiliser des commandes tilde (~) pour vous déconnecter ou envoyer un signal de rupture série, vous devrez ajouter suffisamment de caractères tilde supplémentaires à la commande 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

Vous pouvez également utiliser les options avancées suivantes avec le port série.

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=[e-mail]

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=[e-mail]

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=[e-mail]

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=[e-mail]

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=[e-mail]

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=[e-mail]

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.

Remarque : Sur certains systèmes d'exploitation, ce paramètre n'a aucune incidence sur le port série 1. Cependant, il devrait fonctionner sur les ports 2 à 4 pour la plupart des systèmes d'exploitation ainsi que sur le port 1 pour certains systèmes.

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.