Fehlerbehebung mit serieller Konsole

Diese Seite gibt eine Anleitung zum Einrichten eines interaktiven Zugriffs auf die serielle Konsole einer Instanz zum Beheben von Start- und Netzwerkproblemen, Korrigieren von Instanzen mit Fehlfunktionen, zur Interaktion mit dem GRand Unified Bootloader (GRUB) und für die Behebung von anderen Fehlern.

Die Instanz einer virtuellen Maschine (VM) hat vier virtuelle serielle Ports. Die Interaktion mit einer seriellen Schnittstelle ähnelt der Verwendung eines Terminalfensters dahingehend, dass die Ein- und Ausgabe vollständig im Textmodus erfolgt und keine grafische Benutzeroberfläche oder Maus-Unterstützung vorhanden ist. Das Betriebssystem, das BIOS und andere Einheiten auf Systemebene der Instanz senden Ausgabeaufforderungen häufig an die seriellen Schnittstellen und können Eingaben wie Befehle oder Antworten auf Aufforderungen annehmen. Üblicherweise verwenden diese Funktionen auf Systemebene die erste serielle Schnittstelle (Port 1), die häufig als serielle Konsole bezeichnet wird.

Wenn Sie nur die Ausgabe des seriellen Ports benötigen, ohne dass Sie Befehle an die serielle Konsole senden wollen, können Sie durch Aufruf der Methode getSerialPortOutput oder mithilfe von Cloud Logging die Informationen lesen, die Ihre Instanz an den seriellen Port gesendet hat. Siehe Ausgabe des seriellen Ports ansehen. Wenn Sie jedoch Probleme haben, auf Ihre Instanz über SSH zuzugreifen oder Fehler an einer Instanz beheben müssen, die nicht vollständig gestartet wurde, können Sie den interaktiven Zugriff auf die serielle Konsole aktivieren, die Ihnen eine Verbindung zu den seriellen Ports Ihrer Instanz ermöglicht, sodass Sie mit diesen interagieren können. Sie können zum Beispiel direkt Befehle ausführen und auf Aufforderungen in der seriellen Schnittstelle reagieren.

Wenn Sie den seriellen Port aktivieren oder deaktivieren, können Sie einen beliebigen booleschen Wert verwenden, der vom Metadatenserver akzeptiert wird. Weitere Informationen finden Sie unter Boolesche Werte festlegen.

Hinweise

  • Richten Sie die Authentifizierung ein, falls Sie dies noch nicht getan haben. Bei der Authentifizierung wird Ihre Identität für den Zugriff auf Google Cloud-Dienste und APIs überprüft. Zur Ausführung von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich so bei Compute Engine authentifizieren.

    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
    2. Set a default region and zone.

      3. REST

      Verwenden Sie die von der gcloud CLI bereitgestellten Anmeldedaten, um die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung zu verwenden.

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

        gcloud init

      Weitere Informationen finden Sie unter Für die Verwendung von REST authentifizieren in der Dokumentation zur Google Cloud-Authentifizierung.

Interaktiven Zugriff auf die serielle Konsole aktivieren

Aktivieren Sie den interaktiven Zugriff auf die serielle Konsole für einzelne VM-Instanzen oder für ein ganzes Projekt.

Zugriff für ein Projekt aktivieren

Durch Aktivieren des interaktiven Zugriffs auf die serielle Konsole in einem Projekt wird der Zugriff für alle VM-Instanzen ermöglicht, die Teil dieses Projekts sind.

Standardmäßig ist der Zugriff auf interaktive serielle Ports deaktiviert. Sie können ihn auch explizit deaktivieren. Dazu setzen Sie den Parameter serial-port-enable auf FALSE. In jedem Fall überschreibt jede Einstellung pro Instanz die Einstellung auf Projektebene oder die Standardeinstellung.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Metadaten auf.

    Zur Seite "Metadaten"

  2. Klicken Sie auf Bearbeiten, um Metadateneinträge zu bearbeiten.
  3. Fügen Sie einen neuen Eintrag hinzu, der den Schlüssel serial-port-enable mit dem Wert TRUE verwendet.
  4. Speichern Sie die Änderungen.

gcloud

Geben Sie über die Google Cloud CLI den Befehl project-info add-metadata so ein:

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

REST

Senden Sie in der API eine Anfrage an die Methode projects().setCommonInstanceMetadata und geben Sie für den Schlüssel serial-port-enable den Wert TRUE an:

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

Zugriff für eine VM-Instanz aktivieren

Aktivieren Sie den interaktiven seriellen Konsolenzugriff für eine bestimmte Instanz. Eine Einstellung pro Instanz überschreibt, sofern vorhanden, alle Einstellungen auf Projektebene. Sie können den Zugriff für eine bestimmte Instanz auch dann deaktivieren, wenn der Zugriff auf Projektebene aktiviert ist, indem Sie serial-port-enable auf FALSE statt auf TRUE setzen. Entsprechend können Sie den Zugriff für eine oder mehrere Instanzen aktivieren, auch wenn dieser explizit oder standardmäßig für das Projekt deaktiviert ist.

Console

  1. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.

    Zur Seite "VM-Instanzen"

  2. Klicken Sie auf die Instanz, für die Sie den Zugriff aktivieren möchten.
  3. Klicken Sie auf Bearbeiten.
  4. Klicken Sie im Bereich Remotezugriff auf das Kästchen Verbindung mit seriellen Ports aktivieren.
  5. Speichern Sie die Änderungen.

gcloud

Geben Sie über die Google Cloud CLI den Befehl instances add-metadata ein. Ersetzen Sie dabei instance-name durch den Namen der Instanz.

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

REST

Senden Sie in der API eine Anfrage an die Methode instances().setMetadata mit dem Schlüssel serial-port-enable und dem Wert 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"
  }
 ]
}

Verbindung zu einer seriellen Konsole herstellen

Nach der Aktivierung des interaktiven Zugriffs auf die serielle Konsole einer Instanz können Sie eine Verbindung zur seriellen Konsole herstellen.

Compute Engine bietet für jede Google Cloud-Region ein globales Gateway der seriellen Konsole und regionale Gateways der seriellen Konsole. Sie können über ein globales oder regionales Gateway eine Verbindung zur seriellen Konsole einer VM herstellen. Für eine bessere Zuverlässigkeit empfehlen wir jedoch das regionale Gateway.

Wenn Sie über die Google Cloud Console eine Verbindung zur seriellen Konsole herstellen, wird automatisch eine Verbindung zur regionalen seriellen Konsole hergestellt. Wenn Sie das Google Cloud CLI verwenden, können Sie zwischen dem regionalen oder globalen Gateway wählen. Verbindungen über andere SSH-Clients unterstützen nur das globale Gateway.

Die serielle Konsole authentifiziert Nutzer mit SSH-Schlüsseln. Genauer gesagt, müssen Sie Ihren öffentlichen SSH-Schlüssel den Projekt- oder Instanz-Metadaten hinzufügen und Ihren privaten Schlüssel auf dem lokalen Computer speichern, von dem aus Sie eine Verbindung herstellen möchten. Die gcloud CLI und die Google Cloud Console fügen dem Projekt automatisch SSH-Schlüssel hinzu. Wenn Sie einen Drittanbieter-Client verwenden, müssen Sie den SSH-Schlüssel manuell hinzufügen.

Console

So stellen Sie eine Verbindung zur regionalen seriellen Konsole einer VM her:

  1. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.

    Zur Seite "VM-Instanzen"

  2. Klicken Sie auf die Instanz, zu der Sie eine Verbindung herstellen möchten.
  3. Klicken Sie unter Remotezugriff auf die Schaltfläche Mit serieller Konsole verbinden, um sich mit dem Standardport (Port 1) zu verbinden.
  4. Wenn Sie eine Verbindung zu einem anderen seriellen Port herstellen möchten, klicken Sie auf den Abwärtspfeil neben der Schaltfläche Mit serieller Konsole verbinden und ändern Sie die Portnummer entsprechend.
  5. Bei Windows-Instanzen öffnen Sie das Drop-down-Menü neben der Schaltfläche und stellen eine Verbindung zu Port 2 her, um auf die serielle Konsole zuzugreifen.

gcloud

Verwenden Sie einen der folgenden Befehle, um eine Verbindung zur regionalen oder globalen seriellen Konsole einer VM herzustellen:

  • Empfohlen: Wenn Sie eine Verbindung zur regionalen seriellen Konsole einer VM herstellen möchten, verwenden Sie den Befehl gcloud compute connect-to-serial-port und fügen Sie das Flag --location ein:

    gcloud compute connect-to-serial-port VM_NAME \
  --location=REGION \
  --port=PORT_NUMBER

  • Wenn Sie eine Verbindung zur globalen seriellen Konsole einer VM herstellen möchten, verwenden Sie den Befehl gcloud compute connect-to-serial-port und lassen das Flag --location weg:

    gcloud compute connect-to-serial-port VM_NAME \
  --port=PORT_NUMBER

Ersetzen Sie Folgendes:

  • VM_NAME: Name der VM, zu deren serielle Konsole Sie eine Verbindung herstellen möchten.
  • REGION: Region der VM, zu deren serieller Konsole Sie eine Verbindung herstellen möchten.

  • PORT_NUMBER: Portnummer, die Sie verbinden möchten. Verwenden Sie für Linux-VMs 1 und für Windows-VMs 2. Weitere Informationen zu Portnummern finden Sie in der Erläuterung der Nummerierung serieller Ports.

Andere SSH-Clients

Zur Verbindung mit der seriellen Konsole einer Instanz können Sie auch einen SSH-Client eines Drittanbieters verwenden, wenn dieser eine Verbindung zum TCP-Port 9600 ermöglicht.

Mit dem folgenden SSH-Befehl kann beispielsweise eine Verbindung zum standardmäßigen seriellen Port (1) einer Instanz namens example-instance mit dem Nutzernamen jane in einem Projekt mit der Projekt-ID myproject hergestellt werden. Die Instanz befindet sich in der Zone us-central1-f: Ersetzen Sie private-ssh-key-file durch die private SSH-Schlüsseldatei für die Instanz.

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

Im Einzelnen können Sie mit der seriellen Konsole einer Instanz mit folgendem Benutzernamen und folgenden Adressinformationen eine Verbindung herstellen:

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

Dabei gilt:

  • project-id: Projekt-ID für diese Instanz
  • zone: Zone der Instanz
  • instance-name: Name der Instanz
  • username: Nutzername, den Sie zum Herstellen einer Verbindung zu Ihrer Instanz verwenden. Normalerweise ist dies der Benutzername auf dem lokalen Rechner.
  • options: Zusätzliche Optionen, die Sie für diese Verbindung angeben können. Sie können beispielsweise einen bestimmten seriellen Port und eine beliebige erweiterte Option angeben. Es kann eine Portnummer von 1 bis einschließlich 4 angegeben werden. Weitere Informationen zu Portnummern finden Sie in der Erläuterung der Nummerierung serieller Ports. Ist keine Nummer angegeben, wird eine Verbindung zum seriellen Port 1 hergestellt.

Wenn Sie eine Verbindung zu einer Windows-VM-Instanz herstellen, müssen Sie Port 2 ansteuern:

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

Sollten beim Verbindungsaufbau über den SSH-Client eines Drittanbieters Probleme auftreten, können Sie den Befehl gcloud compute connect-to-serial-port mit der Befehlszeilenoption --dry-run ausführen. So sehen Sie den SSH-Befehl, den der Client in Ihrem Namen ausgeführt hätte. Anschließend können Sie die Optionen mit dem von Ihnen verwendeten Befehl vergleichen.

Eine sichere Verbindung einrichten

Wenn Sie statt der Google Cloud CLI den SSH-Client eines Drittanbieters verwenden, können Sie sich vor Identitätsdiebstahl oder Man-in-the-Middle-Angriffen schützen, indem Sie den SSH-Schlüssel des seriellen Port-Servers von Google prüfen. Mit den folgenden Schritten richten Sie Ihr System so ein, dass der SSH-Schlüssel des Servers überprüft wird:

  1. Laden Sie den SSH-Schlüssel des Serial Port Servers von Google herunter.
  2. Öffnen Sie die Datei Ihnen bekannter Hosts, die sich in der Regel unter ~/.ssh/known_hosts befindet.

  3. Fügen Sie den Inhalt des Server-SSH-Schlüssels mit ssh-serialport.googleapis.com vor dem Schlüssel ein. Wenn der Serverschlüssel beispielsweise die Zeile ssh-rsa AAAAB3NzaC1yc... enthält, sollte ~/.ssh/known_hosts eine Zeile wie diese haben:

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

Aus Sicherheitsgründen kann Google gelegentlich den SSH-Schlüssel des seriellen Port-Servers ändern. Wenn im Client die Server-Schlüssel-Authentifizierung fehlschlägt, brechen Sie den Verbindungsversuch unverzüglich ab und folgen Sie der vorstehenden Anleitung, um den neuen SSH-Schlüssel des seriellen Port-Servers von Google herunterzuladen.

Wenn Sie auch nach der Aktualisierung des Host-Schlüssels weiterhin einen Host-Authentifizierungsfehler von Ihrem Client erhalten, unternehmen Sie keine weiteren Verbindungsversuche zum seriellen Port und wenden Sie sich an den Google-Support. Senden Sie keine Anmeldedaten über eine Verbindung, für die die Host-Authentifizierung fehlgeschlagen ist.

Verbindung zur seriellen Konsole aufheben

Anleitung zum Aufheben der Verbindung zur seriellen Konsole:

  1. Drücken Sie die Taste ENTER.
  2. Geben Sie "~." ein (Tilde gefolgt von einem Punkt).

Sie können weitere Befehle anzeigen lassen, indem Sie ~? eingeben oder auf der SSH-Manpage nachsehen:

man ssh

Versuchen Sie nicht, die Verbindung mit einer der folgenden Methoden aufzuheben:

  • Die Tastenkombination CTRL+ALT+DELETE oder eine ähnliche Kombination. Dies funktioniert nicht, da die serielle Konsole keine Tastenkombinationen der PC-Tastatur erkennt.

  • Der Befehl exit oder logout funktioniert nicht, da der Gast keine Netzwerk- oder Modemverbindungen kennt. Dieser Befehl bewirkt, dass die Konsole geschlossen und dann wieder neu geöffnet wird, während Sie mit der Sitzung verbunden bleiben. Wenn Sie die Befehle exit und logout für Ihre Sitzung aktivieren möchten, legen Sie die Option on-dtr-low fest.

Verbindung zu einer seriellen Konsole mit einer Anmeldeaufforderung herstellen

Wenn Sie ein Problem mit einer VM beheben möchten, die vollständig gestartet wurde, oder versuchen, ein Problem zu beheben, das erst nach dem Starten der VM über den Einzelnutzermodus hinaus auftritt, können Sie beim Zugriff auf die serielle Konsole zur Eingabe von Anmeldeinformationen aufgefordert werden.

Von Google bereitgestellte Linux-System-Images sind standardmäßig so konfiguriert, dass sie eine passwortbasierte Anmeldung für lokale Nutzer nicht zulassen. Von Google bereitgestellte Windows-Images sind jedoch so konfiguriert, dass sie die passwortbasierte Anmeldung für lokale Nutzer zulassen.

Wird auf Ihrer VM ein Image mit vorkonfigurierten Anmeldekonten für serielle Ports ausgeführt, ist die Einrichtung eines lokalen Passworts auf der VM erforderlich, damit Sie sich bei Aufforderung in der seriellen Konsole anmelden können. Sie können ein lokales Passwort einrichten, nachdem Sie eine Verbindung zur VM hergestellt haben, oder indem Sie ein Startskript verwenden.

Lokales Passwort mit einem Startskript einrichten

Sie können ein Startskript verwenden, um ein lokales Passwort einzurichten, mit dem Sie während oder nach der VM-Erstellung eine Verbindung zur seriellen Konsole herstellen können.

In der folgenden Anleitung wird beschrieben, wie Sie ein lokales Passwort nach dem Erstellen einer VM einrichten.

  1. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.

    Zu „VM-Instanzen“

  2. Wählen Sie die VM aus, für die Sie das lokale Passwort hinzufügen möchten.

  3. Klicken Sie auf Bearbeiten.

    Linux

    1. Gehen Sie zu Metadaten > Automatisierung.

    2. Wenn die VM bereits ein Startskript hat, kopieren Sie es und fügen Sie es an einem sicheren Ort ein.

    3. Fügen Sie das folgende Startskript hinzu:

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

      Dabei gilt:

      • USERNAME: Nutzername, den Sie hinzufügen möchten
      • PASSWORD: Passwort für den Nutzernamen Vermeiden Sie einfache Passwörter, da einige Betriebssysteme möglicherweise eine minimale Passwortlänge und Komplexität erfordern.

    Windows

    1. Wechseln Sie zum Abschnitt Benutzerdefinierte Metadaten.
    2. Wenn die VM ein vorhandenes Startskript hat, kopieren Sie es und fügen Sie es an einem sicheren Ort ein.
    3. Klicken Sie auf Zeile hinzufügen.
    4. Geben Sie im Feld Schlüssel windows-startup-script-cmd ein.

    5. Geben Sie im Feld Wert folgendes Skript ein:

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

      Dabei gilt:

      • USERNAME: Nutzername, den Sie hinzufügen möchten
      • PASSWORD: Passwort für den Nutzernamen

  4. Klicken Sie auf Speichern.

  5. Klicken Sie auf Zurücksetzen, um die VM neu zu starten. Weitere Informationen finden Sie unter VM zurücksetzen.

  6. Verbindung zur seriellen Konsole herstellen.

  7. Geben Sie Ihre Anmeldedaten ein, wenn Sie dazu aufgefordert werden.

  8. Entfernen Sie das Startskript vom VM nach dem Erstellen des Nutzers.

Lokales Passwort mit passwd auf der VM einrichten

Nachstehend wird beschrieben, wie Sie für einen Nutzer ein lokales Passwort auf einer VM einrichten, damit sich dieser Nutzer mit diesem Passwort bei der seriellen Konsole dieser VM anmelden kann.

  1. Stellen Sie eine Verbindung zur VM her. Ersetzen Sie instance-name durch den Namen Ihrer Instanz.

    gcloud compute ssh instance-name

  2. Erstellen Sie auf der VM ein lokales Passwort mit dem folgenden Befehl. Dadurch wird ein Passwort für den Nutzer erstellt, als der Sie gerade angemeldet sind.

    sudo passwd $(whoami)

  3. Folgen Sie den Anweisungen, um ein Passwort zu erstellen.

  4. Melden Sie sich anschließend von der Instanz ab und stellen Sie eine Verbindung zur seriellen Konsole her.

  5. Geben Sie Ihre Anmeldedaten ein, wenn Sie dazu aufgefordert werden.

Anmeldekonto an einem seriellen Port erstellen

Auf den meisten Linux-Systemen ist eine Anmeldeaufforderung standardmäßig auf Port 1 aktiviert. Allerdings kann Port 1 oft durch die Protokollierung von Daten und anderen Informationen, die an den Port ausgegeben werden, überfordert sein. Stattdessen können Sie die Anmeldeaufforderung an einem anderen Port, z. B. Port 2 (ttyS1), aktivieren. Führen Sie dazu auf Ihrer VM einen der folgenden Befehle aus. Eine Liste der verfügbaren Ports einer VM finden Sie unter Erläuterung der Nummerierung serieller Ports.

Die folgende Tabelle listet Images auf, die mit einer Anmeldeaufforderung an der seriellen Konsole vorkonfiguriert sind, sowie die entsprechenden Standard-Ports.

Betriebssystem Port(s) mit standardmäßiger Anmeldeaufforderung Dienstverwaltung
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 –

So können Sie Anmeldeaufforderungen für zusätzliche serielle Ports aktivieren.

systemd

Für Linux-Betriebssysteme, die systemd verwenden:

  • Vorübergehende Aktivierung des Dienstes bis zum nächsten Neustart:

    sudo systemctl start serial-getty@ttyS1.service

  • Aktivieren des Dienstes permanent ab dem nächsten Neustart:

    sudo systemctl enable serial-getty@ttyS1.service

upstart

Für Linux-Betriebssysteme, die upstart verwenden:

  1. Erstellen Sie eine neue Datei /etc/init/ttyS1.conf zur Darstellung von ttyS1. Dazu kopieren und bearbeiten Sie eine vorhandene ttyS0.conf-Datei. Beispiel:

    • Unter Ubuntu 14.04:

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

    • Unter RHEL 6.8 und 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. Mit einer Anmeldeaufforderung auf ttyS1 ohne Neustart starten:

    sudo start ttyS1

sysvinit

Führen Sie für Linux-Betriebssysteme, die sysvinit verwenden, den folgenden Befehl aus:

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

Erläuterung der Nummerierung serieller Ports

Jede Instanz einer virtuellen Maschine verfügt über vier serielle Ports. Damit diese Ports der API getSerialPortOutput entsprechen, sind sie von 1 bis 4 nummeriert. Linux und andere ähnliche Systeme nummerieren ihre seriellen Ports von 0 bis 3. Beispielsweise haben auf vielen Betriebssystem-Images die entsprechenden Geräte die Bezeichnung /dev/ttyS0 bis /dev/ttyS3. Windows nummeriert serielle Ports von COM1 bis COM4. Möchten Sie also eine Verbindung mit dem Port COM3 unter Windows bzw. ttyS2 unter Linux herstellen, geben Sie Port 3 an. Verwenden Sie die folgende Tabelle, um herauszufinden, mit welchem Port Sie sich verbinden möchten.

Serielle Ports der VM-Instanz Standardmäßige serielle Ports unter Linux COM-Ports unter Windows
1 /dev/ttyS0 COM1
2 /dev/ttyS1 COM2
3 /dev/ttyS2 COM3
4 /dev/ttyS3 COM4

Beachten Sie, dass viele Linux-Images Port 1 (/dev/ttyS0) verwenden, um Meldungen vom Kernel und von Systemprogrammen zu protokollieren.

Serielle Port-Unterbrechung senden

Mit den Funktionen der Magischen S-Abf-Taste können Sie Aufgaben auf einer niedrigen Ebene unabhängig vom Systemstatus ausführen. Beispielsweise können Sie mit den Funktionen der Magischen S-Abf-Taste Dateisysteme synchronisieren, die Instanz neu starten, Prozesse beenden oder die Bereitstellung von Dateisystemen aufheben.

So senden Sie einen Befehl mit der Magischen S-Abf-Taste unter Verwendung einer simulierten Port-Unterbrechung:

  1. Drücken Sie die Taste ENTER.
  2. Geben Sie ~B ein (Tilde, gefolgt vom Großbuchstaben B).
  3. Geben Sie den Systemabfrage-Befehl ein.

Audit-Logs der seriellen Konsole anzeigen

Compute Engine bietet Audit-Logs, anhand derer sich prüfen lässt, wer zur seriellen Konsole einer Instanz eine Verbindung hergestellt oder getrennt hat. Damit Sie Logs anzeigen können, benötigen Sie Berechtigungen für die Log-Anzeige oder die Anzeige bzw. Bearbeitung des Projekts.

  1. Rufen Sie in der Google Cloud Console die Seite Logs-Explorer auf.

    Zum Log-Explorer

  2. Erweitern Sie das Drop-down-Menü und wählen Sie GCE VM Instance.
  3. Geben Sie in die Suchleiste ssh-serialport.googleapis.com ein und drücken Sie die Eingabetaste.

  4. Eine Liste der Audit-Logs wird angezeigt. In den Logs sind die Verbindungen zur seriellen Konsole aufgeführt, die hergestellt und getrennt wurden. Sie können jeden der Einträge erweitern, um zusätzliche Informationen zu erhalten:

    Audit-Logs für die serielle Konsole.

Bei allen Audit-Logs können Sie Folgendes tun:

  1. Maximieren Sie das Attribut protoPayload.
  2. Unter methodName finden Sie die Aktivität, auf die sich dieses Log bezieht (entweder eine Anfrage zum Herstellen oder zum Trennen einer Verbindung). Wenn dieses Log beispielsweise das Trennen der Verbindung zur seriellen Konsole aufzeichnet, würde die Methode den Namen "google.ssh-serialport.v1.disconnect" tragen. Dementsprechend würde ein Log hergestellter Verbindungen "google.ssh-serialport.v1.connect" heißen. Ein Audit-Log-Eintrag wird jeweils am Anfang und am Ende jeder Sitzung auf der seriellen Konsole vorgenommen.

Es gibt verschiedene Audit-Logattribute für verschiedene Logtypen. Audit-Logs hergestellter Verbindungen haben z. B. dafür spezifische Attribute, ebenso wie Logs getrennter Verbindungen eigene Attribute haben. Es gibt bestimmte Attribute von Audit-Logs, die bei beiden Logtypen vorkommen.

Alle Logs serieller Konsolen

Die folgende Tabelle enthält die Attribute von Audit-Logs und ihre Werte für alle Logs serieller Konsolen:

Attribut Wert
requestMetadata.callerIp Die IP-Adresse und Portnummer, von der die Verbindung stammt.
serviceName ssh-serialport.googleapis.com
resourceName Ein String, der die Projekt-ID, die Zone, den Instanznamen und die Nummer des seriellen Ports enthält, um anzugeben, auf welche serielle Konsole sich diese Informationen beziehen. Zum Beispiel ist projects/myproject/zones/us-east1-a/instances/example-instance/SerialPort/2 die Port Nummer 2, auch als COM2 oder /dev/ttyS1 bezeichnet, für die Instanz example-instance.
resource.labels Attribute zur Kennzeichnung der Instanz-ID, der Zone und der Projekt-ID.
timestamp Ein Zeitstempel, der anzeigt, wann die Sitzung begonnen oder beendet wurde.
severity NOTICE
operation.id Ein ID-String, der die Sitzung eindeutig identifiziert. Diesen können Sie verwenden, um einen Eintrag über eine Verbindungstrennung mit dem entsprechenden Verbindungseintrag zu verknüpfen.
operation.producer ssh-serialport.googleapis.com

Logs hergestellter Verbindungen

Die folgende Tabelle enthält die Attribute von Audit-Logs und deren Werte, die für Verbindungslogs spezifisch sind:

Attribut Wert
methodName google.ssh-serialport.v1.connect
status.message Connection succeeded.
request.serialConsoleOptions Alle Optionen, die mit der Anfrage angegeben wurden, einschließlich der Nummer des seriellen Ports.
request.@type type.googleapis.com/google.compute.SerialConsoleSessionBegin
request.username Der für diese Anforderung angegebene Nutzername, der verwendet wird, um den passenden öffentlichen Schlüssel auszuwählen.
operation.first TRUE
status.code Bei erfolgreichen Verbindungsanfragen hat das Attribut status.code den Wert google.rpc.Code.OK, was bedeutet, dass der Vorgang fehlerfrei durchgeführt wurde. Da der Aufzählungswert dieses Attributs 0 ist, wird das status.code-Attribut nicht angezeigt. Allerdings funktioniert jeder Code, der das Attribut status.code auf den Wert google.rpc.Code.OK prüft, wie erwartet.

Logs getrennter Verbindungen

Die folgende Tabelle enthält die Attribute von Audit-Logs und deren Werte, die speziell für Verbindungslogs gelten:

Attribut Wert
methodName google.ssh-serialport.v1.disconnect
response.duration Dauer der Sitzung in Sekunden
response.@type type.googleapis.com/google.compute.SerialConsoleSessionEnd
operation.last TRUE

Logs fehlgeschlagener Verbindungen

Wenn eine Verbindung fehlschlägt, erstellt Compute Engine einen Audit-Logeintrag. Das Log einer fehlgeschlagenen Verbindung sieht dem Log einer erfolgreichen Verbindung sehr ähnlich, weist jedoch folgende Attribute auf, die eine ausgefallene Verbindung anzeigen.

Attribut Wert
severity ERROR
status.code

Der kanonische Google API-Fehlercode, der den Fehler am ehesten beschreibt. Folgende mögliche Fehlercodes können an dieser Stelle angezeigt werden:

  • google.rpc.Code.INVALID_ARGUMENT: Die Verbindung ist fehlgeschlagen, weil der Client eine ungültige Portnummer zur Verfügung gestellt oder versucht hat, einen unbekannten Kanal zu erreichen. Siehe dazu die Liste der gültigen Portnummern.
  • google.rpc.Code.PERMISSION_DENIED: Sie haben die interaktive serielle Konsole nicht auf dem Metadaten-Server aktiviert. Weitere Informationen finden Sie unter: Interaktiven Zugriff auf die serielle Konsole aktivieren.
  • google.rpcCode.UNAUTHENTICATED: Es wurden keine oder keine passenden SSH-Schlüssel für diese Instanz gefunden. Vergewissern Sie sich, dass Sie auf der VM-Instanz authentifiziert sind.
  • google.rpc.Code.UNKNOWN: Bei Ihrer Anfrage ist ein unbekannter Fehler aufgetreten. Sie können sich diesbezüglich über die Gruppe "gce-discussion" an Google wenden oder einen Fehlerbericht einreichen.
status.message Die für Menschen lesbare Nachricht zu diesem Eintrag.

Interaktiven seriellen Konsolenzugriff deaktivieren

Sie können den interaktiven Zugriff auf die serielle Konsole deaktivieren, indem Sie Metadaten auf der entsprechenden Instanz oder dem Projekt ändern, oder indem Sie eine Organisationsrichtlinie festlegen, die den interaktiven seriellen Konsolenzugriff auf alle VM-Instanzen für ein oder mehrere Projekte, die Teil der Organisation sind, deaktiviert.

Die interaktive serielle Konsole auf einer bestimmten Instanz oder einem Projekt deaktivieren

Projektinhaber und -bearbeiter sowie Nutzer, denen die Rolle compute.instanceAdmin.v1 zugewiesen wurde, können den Zugriff auf die serielle Konsole deaktivieren. Dazu ändern Sie die Metadaten der betreffenden Instanz oder des Projekts. Legen Sie ähnlich wie beim Aktivieren des Zugriffs auf die serielle Konsole die Metadaten für serial-port-enable auf FALSE fest:

serial-port-enable=FALSE

Mit der Google Cloud CLI können Sie diese Metadaten beispielsweise auf eine bestimmte Instanz anwenden:

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

So wenden Sie die Metadaten auf ein Projekt an:

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

Den interaktiven seriellen Konsolenzugriff über die Organisationsrichtlinie deaktivieren

Wenn Sie die Rolle orgpolicy.policyAdmin in der Organisation erhalten haben, können Sie eine Organisationsrichtlinie festlegen, die interaktiven Zugriff auf die serielle Konsole verhindert, auch wenn auf dem Metadatenserver der interaktive Zugriff auf die serielle Konsole aktiviert ist. Nachdem die Organisationsrichtlinie festgelegt wurde, überschreibt sie den Metadatenschlüssel serial-port-enable. Für Nutzer der Organisation oder des Projekts ist es dann unmöglich, den Zugriff auf die interaktive serielle Konsole zu aktivieren. Standardmäßig ist diese Einschränkung auf FALSE eingestellt.

Die Einschränkung zum Deaktivieren des Zugriffs auf die interaktive serielle Konsole lautet:

compute.disableSerialPortAccess

Nachstehend wird beschrieben, wie Sie diese Richtlinie für die Organisation festlegen können. Nachdem Sie diese Richtlinie festgelegt haben, können Sie für jedes einzelne Projekt Ausnahmen einrichten.

gcloud

Mit dem Befehl resource-manager enable-enforce legen Sie die Richtlinie über die Google Cloud CLI fest. Ersetzen Sie organization-id durch Ihre Organisations-ID. Beispiel: 1759840282

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

REST

Senden Sie eine POST-Anfrage an folgende URL, um eine Richtlinie in der API festzulegen: Ersetzen Sie dabei organization-name durch den Namen der Organisation. Beispiel: organizations/1759840282.

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

Der Anfragetext sollte ein policy-Objekt mit folgender Einschränkung beinhalten:

"constraint": "constraints/compute.disableSerialPortAccess"

Beispiel:

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

Die Richtlinie ist sofort wirksam, sodass alle Projekte unter der Organisation den interaktiven Zugriff auf die serielle Konsole sperren.

Verwenden Sie den Befehl disable-enforce, um die Richtlinie vorübergehend zu deaktivieren:

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

Alternativ können Sie eine API-Anfrage stellen, bei der der Anfragetext den enforced-Parameter auf FALSE setzt:

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

Festlegung der Organisationsrichtlinie auf Projektebene

Sie können dieselbe Organisationsrichtlinie auch pro Projekt festlegen. Dies überschreibt die Einstellung auf der Organisationsebene.

gcloud

So deaktivieren Sie diese Richtlinie für ein bestimmtes Projekt: Ersetzen Sie project-id durch Ihre Projekt-ID.

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

Mit dem Befehl enable-enforce mit denselben Werten können Sie diese Richtlinie aktivieren.

REST

Senden Sie in der API eine POST-Anfrage an die folgende URL, um den interaktiven Zugriff auf die serielle Konsole für das Projekt zu aktivieren. Ersetzen Sie dabei project-id durch die Projekt-ID:

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

Der Anfragetext sollte ein policy-Objekt mit folgender Einschränkung beinhalten:

"constraint": "constraints/compute.disableSerialPortAccess"

Beispiel:

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

Tipps und Tricks

  • Wenn bei der Verbindung über einen Standard-SSH-Client Probleme auftreten, aber eine Verbindung über gcloud compute connect-to-serial-port erfolgreich ist, kann es hilfreich sein, gcloud compute connect-to-serial-port mit der Befehlszeilenoption --dry-run auszuführen, um den SSH-Befehl zu sehen, den er für Sie ausgeführt hätte, und die Optionen mit den Befehlen zu vergleichen, die Sie verwenden.

  • Festlegen der Bitrate, auch Baudrate genannt: Sie können eine beliebige Bitrate nach Ihren Wünschen festlegen, etwa stty 9600, aber die Funktion erzwingt normalerweise eine effektive Rate von 115.200 bps (rund 11,5 kB/s). Das liegt daran, dass viele öffentliche Images standardmäßig niedrige Bitraten von z. B. 9.600 auf der seriellen Konsole verwenden und nur langsam starten würden.

  • Einige Betriebssystem-Images verwenden ungünstige Standardwerte am seriellen Port. Unter CentOS 7 lautet der Standardwert stty icrnl für die Eingabetaste in der Konsole zum Beispiel: CR, auch ^M. Eventuell maskiert die Bash-Shell dies, bis Sie versuchen, ein Passwort festzulegen und sich fragen, warum bei der Eingabeaufforderung password: keine Reaktion mehr erfolgt.

  • Bei einigen öffentlichen Images sind manche Job-Steuertasten standardmäßig deaktiviert, wenn Sie eine Shell auf eine bestimmte Art mit einem Port verknüpfen. Zu diesen Tasten gehören beispielsweise ^Z und ^C. Mit dem Befehl setsid lässt sich dies eventuell beheben. Andernfalls müssen Sie, wenn die Meldung job control is disabled in this shell angezeigt wird, darauf achten, dass keine Befehle ausgeführt werden, die Sie gegebenenfalls unterbrechen müssten.

  • Es kann hilfreich sein, dem System die Größe des verwendeten Fensters mitzuteilen, damit Bash und Bearbeitungsprogramme es richtig verwalten können. Andernfalls kann es zu ungewöhnlichem Anzeigeverhalten kommen, da Bash oder Bearbeitungsprogramme versuchen, die Anzeige aufgrund von falschen Annahmen bezüglich der Anzahl verfügbarer Zeilen und Spalten anzupassen. Verwenden Sie den Befehl stty rows Y cols X und das Flag stty -a, um die Einstellung zu sehen. Beispiel: stty rows 60 cols 120, wenn Ihr Fenster 120 Zeichen in 60 Zeilen enthält.

  • Wenn Sie beispielsweise über SSH den Computer A mit Computer B und weiter mit Computer C verbinden, eine verschachtelte SSH-Sitzung erstellen und Tilde-Befehle (~) verwenden, um die Verbindung zu trennen oder ein serielles Unterbrechungssignal zu senden, müssen Sie genügend zusätzliche Tildezeichen zum Befehl hinzufügen, um den richtigen SSH-Client zu erreichen. Einen Befehl hinter einem einzelnen Tildezeichen bezieht der SSH-Client auf Computer A. Ein Befehl, der zwei aufeinanderfolgenden Tilden folgt (~~), wird vom Client auf Computer B ausgeführt usw. Sie müssen die Eingabetaste nur einmal drücken, da sie bis zum innersten SSH-Ziel weitergeleitet wird. Dies gilt für jede Verwendung von SSH-Clients, die die Maskierungsfunktion über die Tilde realisieren.

    Wenn Sie nicht mehr genau wissen, wie viele Tildezeichen Sie benötigen, drücken Sie die Eingabetaste und geben Sie dann Tildezeichen einzeln ein, bis die Instanz die Tilde zurückgibt. Dies gibt an, dass Sie das Ende der Kette erreicht haben und Sie wissen, dass Sie zum Erreichen des am tiefsten verschachtelten SSH-Clients mit dem Tildebefehl ein Tildezeichen weniger eingeben müssen, als Sie gerade eben eingegeben haben.

Erweiterte Optionen

Max. Verbindungsanzahl steuern

Sie können das Attribut max-connections festlegen, um zu bestimmen, wie viele gleichzeitige Verbindungen jeweils zu diesem seriellen Port vorgenommen werden können. Die standardmäßige und maximale Anzahl von Verbindungen ist 5. Beispiel:

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

Wiederholungsoptionen festlegen

Standardmäßig wird jedes Mal, wenn Sie eine Verbindung zur seriellen Konsole herstellen, eine Wiederholung der letzten 10 Datenzeilen ausgegeben, unabhängig davon, ob die letzten 10 Zeilen durch einen anderen SSH-Client gesehen wurden. Über die folgenden Optionen können Sie diese Einstellung ändern und steuern, wie viele und welche Zeilen ausgegeben werden:

  • replay-lines=N: Legen Sie für N die Anzahl der Zeilen fest, die ausgegeben werden soll. Wird zum Beispiel für N 50 angegeben, werden die letzten 50 Zeilen der Konsolenausgabe ausgegeben.
  • replay-bytes=N: Gibt die letzten N Byte noch einmal aus. Sie können N auch auf new setzen, sodass alle Daten nochmal ausgegeben werden, die noch an keinen Client gesendet wurden.
  • replay-from=N: Startet eine neue Ausgabe von einem von Ihnen angegebenen absoluten Byteindex ausgehend. Sie können den aktuellen Byteindex der Ausgabe der seriellen Konsole mit der Anfrage getSerialPortOutput abrufen. Wenn Sie replay-from festlegen, werden alle anderen Wiedergabeoptionen ignoriert.

Hängen Sie mithilfe der Google Cloud CLI Folgendes an Ihren Befehl connect-to-serial-port an, wobei N die Anzahl der Zeilen (oder Byte oder des absoluten Byteindex entsprechend der ausgewählten Wiederholungsoption) angibt:

--extra-args replay-lines=N

Wenn Sie einen Drittanbieter-SSH-Client verwenden, geben Sie diese Option im SSH-Befehl an:

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.replay-lines=N@ssh-serialport.googleapis.com

Sie können auch eine Kombination dieser Optionen verwenden. Beispiel:

replay-lines=N und replay-bytes=new
Gibt die angegebene Anzahl von Zeilen wieder aus ODER gibt alle Daten aus, die noch an keinen Client gesendet wurden, je nachdem, welcher Wert größer ist. Der erste Client, der eine Verbindung mit dieser Flag-Kombination herstellt, sieht die gesamten Daten, die an die serielle Schnittstelle gesendet wurden. Alle Clients, die danach eine Verbindung herstellen, sehen nur die letzten N-Zeilen. Beispiele:
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 und replay-bytes=M
Gibt die Zeilen bis zur genauen Anzahl von Zeilen oder Byte an, die durch diese Flags beschrieben werden, je nachdem, welcher Wert niedriger ist. Mit dieser Option werden nicht mehr als N oder M Byte nochmal ausgegeben.
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

Umgang mit verworfenen Ausgabedaten

Das jüngste 1 MiB an Ausgabedaten steht immer für jeden seriellen Port zur Verfügung und in der Regel sollte Ihr SSH-Client keine über den seriellen Port ausgegebenen Daten verpassen. Wenn jedoch Ihr SSH-Client aus irgendeinem Grund eine Zeit lang keine Ausgabedaten mehr annimmt, aber die Verbindung nicht trennt, und mehr als 1 MiB neuer Daten erzeugt werden, könnte Ihr SSH-Client Ausgabedaten verpassen. Wenn Ihr SSH-Client Ausgabedaten nicht schnell genug entgegennimmt, um mit der Ausgabegeschwindigkeit der Konsole des seriellen Ports mitzuhalten, können Sie mit dem Attribut on-dropped-output das Verhalten der Konsole festlegen.

Legen Sie eine der folgenden verfügbaren Optionen für dieses Attribut fest:

  • insert-stderr-note: Hinterlegt eine Notiz auf dem stderr des SSH-Clients, die darauf hinweist, dass die Ausgabedaten verworfen wurden. Dies ist die Standardoption.
  • ignore: Verwirft die Ausgabedaten im Hintergrund ohne weitere Aktion.
  • disconnect: Die Verbindung beenden.

Beispiel:

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

Funktion zum Trennen einer Verbindung durch die Befehle "exit" und "logout" aktivieren

Wenn Sie die Funktion zum Trennen einer Verbindung durch die Befehle "exit" und "logout" aktivieren möchten, legen Sie bei der Verbindung zur seriellen Konsole für das Attribut on-dtr-low den Wert disconnect fest.

Hängen Sie in der Google Cloud CLI das folgende Flag an Ihren connect-to-serial-port-Befehl an:

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

Wenn Sie einen Drittanbieter-SSH-Client verwenden, geben Sie diese Option im SSH-Befehl an:

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

Die Aktivierung der Option disconnect kann dazu führen, dass die Verbindung zur Instanz einmal oder mehrmals getrennt wird, wenn Sie die Instanz neu starten, da das Betriebssystem die seriellen Ports beim Neustart zurücksetzt.

Die Standardeinstellung für die Option on-dtr-low ist none. Wenn Sie die Standardeinstellung none verwenden, können Sie die Instanz neu starten, ohne von der seriellen Konsole getrennt zu werden, aber die Verbindung zur Konsole nicht mit normalen Methoden wie den Befehlen exit oder logout oder normalen Tastenkombinationen wie "Strg + D" trennen.

Nächste Schritte