Interagir avec la console série

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 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 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 à Stackdriver 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.

Avant de commencer

Autorisations requises pour cette tâche

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

  • compute.instances.setMetadata pour l'instance si vous souhaitez activer l'accès interactif sur une instance spécifique
  • compute.projects.setCommonInstanceMetadata pour le projet si vous souhaitez activer l'accès interactif à l'échelle du projet

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 0 au lieu de 1. 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. Accédez à 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é enable-port-serial et la valeur 1. Capture d'écran illustrant l'ajout de la clé de métadonnées de la console série
  4. Enregistrez les modifications.

gcloud

Utilisez la commande project-info add-metadata. Exemple :

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

API

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

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

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 0 au lieu de 1. 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. 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 de série.
  5. Enregistrez les modifications.

gcloud

À l'aide de l'outil de ligne de commande gcloud, exécutez la commande instances add-metadata :

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

API

Envoyez une requête à la méthode instances().setMetadata en spécifiant la clé serial-port-enable avec la valeur 1 :

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

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

Se connecter à une console série

Après avoir activé l'accès interactif à la console série de votre instance, vous pouvez vous connecter via la console Google Cloud Platform, de l'outil de ligne de commande gcloud ou d'un client SSH tiers.

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. L'outil gcloud et la console Google Cloud Platform ajoutent automatiquement les clés SSH au projet. Si vous utilisez un client tiers, vous devrez peut-être ajouter les clés SSH manuellement.

Console

  1. 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, cliquez sur le menu déroulant situé à côté du bouton et connectez-vous au port 2 pour accéder à la console série.

gcloud

Exécutez la sous-commande gcloud compute connect-to-serial-port dans l'outil de ligne de commande gcloud pour vous connecter. Exemple :

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

[INSTANCE_NAME] est le nom de l'instance pour laquelle vous souhaitez accéder à la console série.

Par défaut, la commande connect-to-serial-port se connecte au port 1 de la console série. Si vous vous connectez à une instance de VM Windows, utilisez le port 2 :

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

Pour vous connecter à un autre port, indiquez un numéro de port différent à l'aide de l'indicateur --port. Entrez un numéro de port 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.

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 est dans la zone us-central1-f :

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

où :

  • [PROJECT_ID] est l'ID du projet pour cette instance.
  • [ZONE] est la zone de l'instance.
  • [INSTANCE_NAME] est le nom de l'instance.
  • [USERNAME] est le nom d'utilisateur qui vous permet de vous connecter à votre instance. En règle générale, il s'agit du nom d'utilisateur sur votre ordinateur local.
  • [OPTIONS] sont des options supplémentaires que vous pouvez spécifier pour cette connexion. Par exemple, vous pouvez choisir un certain port série ainsi que l'une ou l'autre des options avancées ci-dessous. 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. Si vous ne spécifiez pas de numéro de port, 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 ne parvenez pas à vous connecter à l'aide d'un client SSH tiers, exécutez la commande gcloud compute connect-to-serial-port avec l'option de ligne de commande --dry-run pour afficher la commande SSH que le client aurait dû exécuter, et comparez les options avec la commande que vous utilisez.

Configurer une connexion sécurisée

Lorsque vous utilisez un client SSH tiers en dehors de l'outil de ligne de commande gcloud, assurez-vous d'être protégé contre l'usurpation d'identité ou les attaques de type "homme du milieu" en vérifiant la clé SSH du serveur de port série 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 de port série de Google.
  2. Ouvrez votre fichier d'hôtes connus, généralement situé dans ~/.ssh/known_hosts.
  3. Ajoutez le contenu de la clé SSH du serveur avec le préfixe ssh-serialport.googleapis.com à la clé. Par exemple, si la clé du serveur contient la ligne ssh-rsa AAAAB3NzaC1yc..., alors ~/.ssh/known_hosts doit contenir la ligne 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 instructions ci-dessus 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).

Saisissez ~? pour découvrir d'autres commandes ou consultez la page du manuel relative au protocole SSH :

man ssh

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

  • Combinaison des touches CTRL+ALT+DELETE ou autres combinaisons semblables. Cela ne fonctionnera pas, car la console série ne reconnaît pas les combinaisons de clavier PC.

  • Commandes exit ou logout. Cela ne fonctionnera pas, car aucune information de connexion réseau ou modem n'est fournie à l'invité. 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, sélectionnez l'option on-dtr-low et définissez les paramètres.

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

Si vous tentez de résoudre un problème sur une instance 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 fournies par Google ne sont pas configurées pour autoriser les connexions par mot de passe aux utilisateurs locaux. Si votre instance exécute une image préconfigurée avec des connexions de port série, vous devez définir un mot de passe local sur l'instance de la machine virtuelle pour pouvoir vous connecter à la console série si vous y êtes invité.

Configurer un mot de passe local

Les instructions suivantes décrivent comment définir un mot de passe d'utilisateur local sur une instance de machine virtuelle afin que cet utilisateur puisse se connecter à la console série de cette instance à l'aide du mot de passe spécifié.

  1. Connectez-vous à l'instance :

    gcloud compute ssh [INSTANCE_NAME]
    
  2. Dans l'instance, 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. Entrez 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 instance. Consultez la liste des ports disponibles pour une instance 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 Port(s) avec une invite de connexion par défaut Service Management
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 ND

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

systemd

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

Systèmes d'exploitation Linux utilisant upstart :

  1. Copiez et modifiez un fichier /etc/init/ttyS1.conf existant pour créer un fichier ttyS0.conf correspondant à ttyS1. Exemple :

    • Sous Ubuntu 14.04 :

      sudo sh -c "sed -e s/ttyS0/ttyS1/g < /etc/init/ttyS0.conf > /etc/init/ttyS1.conf"
      
    • 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 les commandes suivantes :

 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 assurer la 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 au port série Windows COM3 et Linux 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 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 la majuscule B).
  3. Saisissez la commande Magic SysRq de votre choix.

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. Accédez à la page Journaux de la console GCP.

    Accéder à la page 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. Une liste des journaux d'audit décrivant les connexions et les déconnexions d'une console série s'affiche. Cliquez sur l'une des entrées pour plus de détails :

    Capture d'écran des journaux d'audit pour la console série

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

  1. Développer la propriété protoPayload.
  2. Lancer une recherche methodName pour consulter l'activité correspondant à ce journal (demande de connexion ou de déconnexion). Par exemple, si le journal doit suivre une déconnexion de la console série, le nom de la méthode indiquera "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 relatifs aux connexions sont dotés de propriétés spécifiques aux journaux de connexion, tandis que les journaux d'audit relatifs aux 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

Propriété 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 port numéro 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

Propriété 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. La valeur enum de cette propriété étant 0, dans ce cas, la propriété status.code ne sera 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

Propriété 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 :

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 de projets, ainsi que les utilisateurs auxquels le rôle compute.instanceAdmin.v1 a été accordé, 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 0 :

serial-port-enable=0

Par exemple, en utilisant l'outil de ligne de commande gcloud, vous pouvez appliquer ces métadonnées à une instance spécifique comme celle-ci :

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

Pour appliquer les métadonnées au projet :

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

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 la règle définie, la clé de métadonnées serial-port-enable est ignorée, et aucun utilisateur de l'organisation ou du projet ne peut activer l'accès interactif à la console série. Par défaut, cette contrainte est définie sur faux.

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

compute.disableSerialPortAccess

Pour savoir comment définir cette règle dans l'organisation, reportez-vous aux 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 l'outil de ligne de commande gcloud, exécutez la commande resource-manager enable-enforce suivante :

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

[ORGANIZATION_ID] est l'ID numérique de l'organisation. Par exemple, 1759840282.

API

Pour définir une règle dans l'API, envoyez une requête POST à l'URL suivante :

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

[ORGANIZATION_NAME] est le nom de l'organisation. Par exemple, organizations/1759840282.

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 interrompues pour tous les projets de l'organisation.

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

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

Vous pouvez également créer une requête API où 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 :

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

[PROJECT_ID] est l'ID du projet pour cette requête, par exemple my-example-project.

Pour activer l'application de cette règle, utilisez la commande enable-enforce avec les mêmes valeurs.

API

Dans l'API, envoyez une requête POST à l'URL suivante pour activer l'accès interactif à la console série pour le projet :

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

[PROJECT_NAME] est l'ID du projet.

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 ne parvenez pas à vous connecter avec un client SSH standard, mais que gcloud compute connect-to-serial-port se connecte correctement, exécutez la commande gcloud compute connect-to-serial-port avec l'option de ligne de commande --dry-run pour afficher la commande SSH que le client aurait dû exécuter, et comparez les options avec 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 d'OS 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, le paramètre stty icrnl est nécessaire pour indiquer à la console l'action à effectuer sur la touche Entrée (qui envoie une CR, soit ^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 d'OS 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, comme les clés ^Z et ^C. La commande setsid permet de 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 que vous devrez alors 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 lorsque 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 vérifier les paramètres. Par exemple : stty rows 60 cols 120 (si votre fenêtre contient 120 caractères sur 60 lignes).

  • Si vous vous connectez en SSH de la machine A à la machine B, puis à la machine C (et ainsi de suite), créant ainsi une session SSH imbriquée, et que vous voulez utiliser des commandes ~ pour, par exemple, vous déconnecter ou envoyer un signal d'interruption série, vous devez ajouter à la commande autant de caractères ~ nécessaires 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 ~ (ENTER~~) 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 ENTER, 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é ~.

    Si vous ne savez plus le nombre de caractères ~ dont vous avez besoin, appuyez sur la touche ENTER, 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.

Options avancées

Contrôler le nombre maximal de connexions

La propriété max-connections permet de définir le nombre maximal de connexions pouvant être effectuées simultanément sur ce port série. 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éfinit N sur le nombre de lignes à répéter. 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 : répète les N derniers octets. Vous pouvez également définir N sur new afin de répéter tous les résultats qui n'ont pas encore été envoyés à un client.
  • replay-from=N : répète les résultats à partir d'une valeur indexée absolue que vous indiquez. Pour obtenir la valeur indexée actuelle des résultats de la console série, envoyez une requête getSerialPortOutput. Une fois le paramètre replay-from défini, toutes les autres options de répétition seront ignorées.

À l'aide de l'outil de ligne de commande gcloud, ajoutez ce qui suit à votre commande connect-to-serial-port, où N représente le nombre de lignes spécifié (ou le nombre d'octets, ou encore la valeur indexée absolue, selon votre choix) :

--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. Dans ces circonstances, lorsque votre client SSH n'accepte pas les données assez rapidement pour suivre le flux sortant sur le port de la console série, vous pouvez définir 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 sur le flux stderr du client SSH pour indiquer que des sorties ont été supprimées. Il s'agit de l'option par défaut.
  • ignore : supprime silencieusement la sortie et ne fait rien.
  • disconnect : interrompt 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"

Pour activer la déconnexion avec les commandes "exit" ou "logout", définissez la propriété on-dtr-low sur disconnect lorsque vous vous connectez à la console série.

Dans l'outil de ligne de commande gcloud, ajoutez ce qui suit à 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 cette option 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 pour cette option est none, où rien ne se produit lorsque la ligne DTR est modifiée. Si vous revenez au paramètre par défaut, 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.

Étapes suivantes

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Compute Engine