Mit der seriellen Konsole interagieren

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 verfügt über vier virtuelle serielle Schnittstellen. 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 Befehle an die serielle Konsole senden zu wollen, können Sie die Methode getSerialPortOutput aufrufen oder Stackdriver verwenden, um Informationen zu lesen, die Ihre Instanz an ihren 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.

Vorbereitung

Erforderliche Berechtigungen für diese Aufgabe

Zum Ausführen dieser Aufgabe benötigen Sie die folgenden Berechtigungen.

  • compute.instances.setMetadata für die Instanz, wenn Sie den interaktiven Zugriff auf einer bestimmten Instanz aktivieren
  • compute.projects.setCommonInstanceMetadata für das Projekt, wenn Sie den interaktiven Zugriff projektweit aktivieren

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 explizit deaktivieren, indem Sie den serial-port-enable-Schlüssel auf 0 statt auf 1 setzen. In jedem Fall überschreibt jede Einstellung pro Instanz die Einstellung auf Projektebene oder die Standardeinstellung.

Konsole

  1. Öffnen Sie die Seite Metadaten.
  2. Klicken Sie auf Bearbeiten, um Metadateneinträge zu bearbeiten.
  3. Fügen Sie einen neuen Eintrag mit dem Schlüssel serial-port-enable und dem Wert 1 hinzu. Screenshot zum Hinzufügen des Metadatenschlüssels der seriellen Konsole
  4. Speichern Sie die Änderungen.

gcloud

Verwenden Sie den Befehl project-info add-metadata. Beispiel:

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

API

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 1 an:

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

Zugriff für eine VM-Instanz aktivieren

Aktivieren Sie den interaktiven seriellen Konsolenzugriff für eine bestimmte Instanz. Eine Einstellung pro Instanz überschreibt 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 0 statt auf 1 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.

Konsole

  1. Gehen Sie zur Seite "VM-Instanzen".

    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. Aktivieren Sie im Abschnitt Remotezugriff das Kästchen Verbindung zu seriellen Ports aktivieren.
  5. Speichern Sie die Änderungen.

gcloud

Führen Sie über das gcloud-Befehlszeilentool den Befehl instances add-metadata aus:

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

API

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

Verbindung zu einer seriellen Konsole herstellen

Nach der Aktivierung des interaktiven Zugriffs auf die serielle Konsole einer Instanz können Sie beispielsweise über die Google Cloud Platform Console, das Befehlszeilentool gcloud oder den SSH-Client eines Drittanbieters eine Verbindung zur seriellen Konsole herstellen.

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. Das Tool gcloud und die Google Cloud Platform Console fügen dem Projekt automatisch SSH-Schlüssel für Sie hinzu. Wenn Sie einen Drittanbieter-Client verwenden, müssen Sie den SSH-Schlüssel manuell hinzufügen.

Konsole

  1. Gehen Sie zur Seite "VM-Instanzen".

    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 Verbindung zur seriellen Konsole herstellen und ändern Sie die Portnummer entsprechend.
  5. Öffnen Sie bei Windows-Instanzen das Drop-down-Menü neben der Schaltfläche und verbinden Sie sich mit Port 2, um auf die serielle Konsole zuzugreifen.

gcloud

Verwenden Sie den Unterbefehl gcloud compute connect-to-serial-port, um eine Verbindung mithilfe des Befehlszeilentools gcloud herzustellen. Beispiel:

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

Hierbei steht [INSTANCE_NAME] für den Namen der Instanz, auf deren serielle Konsole Sie zugreifen möchten.

Der Befehl connect-to-serial-port stellt standardmäßig eine Verbindung zum Port 1 der seriellen Konsole her. Wenn Sie eine Verbindung zu einer Windows-VM-Instanz herstellen, müssen Sie stattdessen Port 2 ansteuern:

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

Wenn Sie eine Verbindung zu einem anderen Port herstellen möchten, geben Sie mithilfe des Flag --port eine andere Portnummer an. Sie können eine Portnummer von 1 bis einschließlich 4 eingeben. Wenn Sie mehr über Portnummern erfahren möchten, lesen Sie die 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:

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 Folgendes:

  • [PROJECT_ID] ist die Projekt-ID für diese Instanz.
  • [ZONE] ist die Zone der Instanz.
  • [INSTANCE_NAME] ist der Name der Instanz.
  • [USERNAME] ist der Benutzername, den Sie zur Verbindung mit Ihrer Instanz verwenden. Normalerweise ist dies der Benutzername auf dem lokalen Rechner.
  • [OPTIONS] sind zusätzliche Optionen, die Sie für diese Verbindung angeben. Zum Beispiel können Sie einen bestimmten seriellen Port und eine der nachstehenden erweiterten Optionen angeben. Es kann eine Portnummer von 1 bis einschließlich 4 angegeben werden. Wenn Sie mehr über Portnummern erfahren möchten, lesen Sie die 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

Wenn bei der Verbindung über den SSH-Client eines Drittanbieters Probleme auftreten, können Sie gcloud compute connect-to-serial-port mit der Befehlszeilenoption --dry-run ausführen, um den SSH-Befehl zu sehen, den er für Sie ausgeführt hätte, und die Optionen mit den Befehlen vergleichen, die Sie verwenden.

Eine sichere Verbindung einrichten

Wenn Sie statt dem Befehlszeilentool gcloud den SSH-Client eines Drittanbieters verwenden, können Sie sich vor Identitätsdiebstahl oder Mittelsmannangriffen schützen, indem Sie den SSH-Schlüssel des Serial Port Servers von Google prüfen. Befolgen Sie diese Anweisungen, um Ihr System so einzurichten, dass es den Server-SSH-Schlüssel prüft:

  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 in ~/.ssh/known_hosts die folgende Zeile eingetragen sein:

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

Aus Sicherheitsgründen kann Google gelegentlich den SSH-Schlüssel des Google Serial Port Servers ändern. Wenn im Client die Server-Schlüssel-Authentifizierung fehlschlägt, brechen Sie sofort den Verbindungsversuch ab und folgen Sie den oben genannten Anweisungen, um einen neuen SSH-Schlüssel vom Google Serial Port Server herunterzuladen.

Wenn Sie auch nach der Aktualisierung des Host-Schlüssels weiterhin einen Host-Authentifizierungsfehler von Ihrem Client erhalten, unternehmen Sie keine weiteren Verbindungsversuche mehr 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. Das funktioniert nicht, weil die serielle Konsole keine Tastenkombinationen der PC-Tastatur erkennt.

  • Die Befehle exit oder logout funktionieren nicht, da dem Gast keine Netzwerk- oder Modemverbindungen bekannt sind. 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 Instanz beheben möchten, die vollständig gestartet wurde, oder versuchen, ein Problem zu beheben, das erst nach dem Starten der Instanz über den Einzelbenutzermodus hinaus auftritt, können Sie beim Zugriff auf die serielle Konsole zur Eingabe von Anmeldeinformationen aufgefordert werden.

Von Google bereitgestellte System-Images sind standardmäßig so konfiguriert, dass sie eine passwortbasierte Anmeldung für lokale Nutzer nicht zulassen. Betreibt Ihre Instanz ein Image mit vorkonfigurierten Anmeldekonten für serielle Ports, ist das Festlegen eines lokalen Passworts auf der Instanz der virtuellen Maschine erforderlich, damit Sie sich an der seriellen Konsole anmelden können, wenn Sie dazu aufgefordert werden.

Lokales Passwort einrichten

Die folgenden Anweisungen beschreiben das Einrichten eines lokalen Passworts für einen Nutzer auf einer Instanz einer virtuellen Maschine, sodass dieser Nutzer sich mit dem angegebenen Passwort an der seriellen Konsole dieser Instanz anmelden kann.

  1. Stellen Sie eine Verbindung zu der Instanz her:

    gcloud compute ssh [INSTANCE_NAME]
    
  2. Erstellen Sie auf der Instanz 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, sobald 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. Alternativ können Sie die Anmeldeaufforderung auf einem anderen Port aktivieren, zum Beispiel auf Port 2 (ttyS1), indem Sie auf der Instanz einen der folgenden Befehle ausführen. Eine Liste der verfügbaren Ports einer Instanz 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 Nicht zutreffend

Mit den folgenden Schritten aktivieren Sie Anmeldeaufforderungen an weiteren seriellen Ports.

systemd

Für Linux-Betriebssysteme, die systemd verwenden:

  • Aktivieren des Dienstes vorübergehend 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 durch Kopieren und Modifizieren einer bestehenden Datei ttyS0.conf, in der ttyS1 berücksichtigt wurde. 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, die folgenden Befehle aus:

 sudo sed -i~ -e 's/^#T\([01]\)/T\1/' /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

Die Funktion Magische S-Abf-Taste ermöglicht Ihnen das Ausführen von Aufgaben auf einer niedrigen Ebene unabhängig vom Systemstatus. Zum Beispiel können Sie mithilfe der Funktion der Magischen S-Abf-Taste Dateisysteme synchronisieren, die Instanz neu starten, Prozesse beenden, die Bereitstellung von Dateisystemen aufheben und so weiter.

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 gewünschten Befehl für die Magische S-Abf-Taste 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. Gehen Sie zur Seite "Logs" in der GCP Console.

    Zur Seite "Logs"

  2. Erweitern Sie das Drop-down-Menü und wählen Sie GCE VM Instance.
  3. Geben Sie in der Suchleiste ssh-serialport.googleapis.com ein und drücken Sie die Eingabetaste.
  4. Es wird eine Liste der Audit-Logs angezeigt, aus denen die hergestellten und getrennten Verbindungen zu einer seriellen Konsole hervorgehen. Sie können jeden der Einträge erweitern, um zusätzliche Informationen zu erhalten:

    Screenshot von Audit-Logs für die serielle Konsole

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

  1. Erweitern 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-Log-Attribute für verschiedene Log-Typen. Beispielsweise weisen Audit-Logs bezüglich hergestellter Verbindungen einige Attribute auf, die für diesen Log-Typ spezifisch sind, während Audit-Logs getrennter Verbindungen ihre eigenen Attribute haben. Es gibt bestimmte Attribute von Audit-Logs, die bei beiden Log-Typen vorkommen.

Alle Logs serieller Konsolen

Attribut Wert
requestMetadata.callerIp Die IP-Adresse und Portnummer, von der die Verbindung stammt.
serviceName ssh-serialport.googleapis.com
resourceName Eine Zeichenfolge, die 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 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 Eine ID-Zeichenfolge zur eindeutigen Identifikation dieser Sitzung, die Sie verwenden können, um einen Eintrag einer getrennten Verbindung dem entsprechenden Eintrag zur hergestellten Verbindung zuzuordnen.
operation.producer ssh-serialport.googleapis.com

Logs hergestellter Verbindungen

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 und zeigt damit an, dass der Vorgang fehlerfrei durchgeführt wurde. Da der ENUM-Wert für dieses Attribut 0 ist, wird in diesem Fall das Attribut status.code 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

Attribut Wert
methodName google.ssh-serialport.v1.disconnect
response.duration Die Sitzungsdauer 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.

Deaktivieren der interaktiven seriellen Konsole auf einer bestimmten Instanz oder einem Projekt

Projektinhaber und -editoren sowie Nutzer, denen die compute.instanceAdmin.v1-Rolle zugeteilt wurde, können den Zugriff auf die serielle Konsole deaktivieren, indem sie die Metadaten auf der jeweiligen Instanz oder dem Projekt ändern. Legen Sie ähnlich wie beim Aktivieren des Zugriffs auf die serielle Konsole die Metadaten für serial-port-enable auf 0 fest:

serial-port-enable=0

Mit dem gcloud-Befehlszeilentool können Sie diese Metadaten beispielsweise auf eine bestimmte Instanz anwenden:

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

Auf ein Projekt wenden Sie die Metadaten wie folgt an:

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

Deaktivieren des interaktiven seriellen Konsolenzugriffs über die Organisationsrichtlinie

Wenn Sie die Rolle orgpolicy.policyAdmin für die Organisation erhalten haben, können Sie eine Organisationsrichtlinie festlegen, die den interaktiven Zugriff auf die serielle Konsole verhindert, auch wenn auf dem Metadatenserver der interaktive Zugriff auf die serielle Konsole aktiviert ist. Wenn diese festgelegt ist, überschreibt die Richtlinie den serial-port-enable-Metadatenschlüssel effektiv und kein Nutzer der Organisation oder des Projekts kann den interaktiven Zugriff auf die serielle Konsole aktivieren. Diese Einschränkung ist standardmäßig auf "false" gesetzt.

Die Einschränkung für das Deaktivieren des interaktiven seriellen Konsolenzugriffs ist:

compute.disableSerialPortAccess

Die folgenden Anweisungen beschreiben, 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 gcloud-Befehlszeilentool legen Sie die Richtlinie über den resource-manager enable-enforce-Befehl fest:

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

Dabei ist [ORGANIZATION_ID] die numerische Organisations-ID. Zum Beispiel 1759840282.

API

Stellen Sie eine POST-Anfrage an folgende URL, um eine Richtlinie in der API festzulegen:

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

Dabei ist [ORGANIZATION_NAME] der Name der Organisation. Zum Beispiel organizations/1759840282.

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 alpha resource-manager org-policies disable-enforce --organization [ORGANIZATION_ID] \
    compute.disableSerialPortAccess

Alternativ können Sie eine API-Anfrage stellen, bei dem 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:

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

Dabei ist [PROJECT_ID] die Projekt-ID für diese Anfrage, z. B. my-example-project.

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

API

Stellen Sie in der API eine POST-Anfrage an folgende URL, um den seriellen Zugriff auf die Konsole für das Projekt zu aktivieren:

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

Dabei ist [PROJECT_NAME] die Projekt-ID.

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 Betriebssystem-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 ist es beispielsweise erforderlich, dass stty icrnl der Konsole die richtige Vorgabe bezüglich der Verarbeitung der Eingabetaste sendet (also CR bzw. ^M). Die Bash-Shell kann darüber hinweg täuschen, bis Sie versuchen, ein Passwort festzulegen, und sich fragen, warum nach der Eingabeaufforderung password: keine Reaktion mehr erfolgt.

  • Bei einigen Betriebssystem-Images sind manche Job-Steuertasten standardmäßig deaktiviert, wenn Sie eine Shell auf bestimmte Art mit einem Port verknüpfen. Zu diesen Tasten gehören beispielsweise ^Z und ^C. Der Befehl setsid kann dieses Problem beheben. Andernfalls müssen Sie, wenn die Nachricht job control is disabled in this shell angezeigt wird, darauf achten, keine Befehle auszuführen, die Sie gegebenenfalls unterbrechen müssten.

  • Es kann hilfreich sein, dem System die Größe des Fensters mitzuteilen, das Sie verwenden, damit Bash und Bearbeitungsprogramme es richtig verwalten können. Andernfalls kann es zu ungewöhnlichem Anzeigeverhalten kommen, wenn Bash oder Bearbeitungsprogramme versuchen, die Anzeige basierend auf falschen Annahmen bezüglich der Anzahl der verfügbaren Zeilen und Spalten anzupassen. Verwenden Sie die Befehle stty rows Y cols X und stty -a, um die aktuellen Einstellungen anzuzeigen. Beispiel: stty rows 60 cols 120 (wenn Ihr Fenster 120 Zeichen in 60 Zeilen aufweist).

  • Wenn Sie über SSH eine Verbindung von Computer A zu Computer B und dann zu Computer C (und so weiter) herstellen, wodurch eine verschachtelte SSH-Sitzung entsteht, und Sie Befehle mit ~ verwenden möchten, um beispielsweise die Verbindung zu trennen oder eine Port-Unterbrechung zu senden, müssen Sie dem Befehl genügend zusätzliche ~-Zeichen hinzufügen, damit der Befehl den richtigen SSH-Client erreicht. Ein Befehl, der auf ein einzelnes ~-Zeichen folgt, wird vom SSH-Client auf Computer A ausgeführt. Geben Sie zwei ~ hintereinander ein (ENTER~~), wird der Befehl von Computer B ausgeführt, und so weiter. Sie müssen die ENTER-Taste nur einmal drücken, da diese Eingabe bis zum innersten SSH-Ziel weitergeleitet wird. Dies trifft auf die Nutzung sämtlicher SSH-Clients zu, die die Escape-Funktion mit dem ~-Zeichen bieten.

    Wenn Sie nicht mehr genau wissen, wie viele ~-Zeichen Sie eingeben müssen, drücken Sie die Taste ENTER und geben Sie einzelne ~-Zeichen ein, bist die Instanz das ~-Zeichen zurückgibt. Dies zeigt an, dass Sie das Ende der Kette erreicht haben, sodass Sie nun wissen, dass Sie zum Erreichen des am tiefsten verschachtelten SSH-Clients mit dem ~-Befehl ein ~-Zeichen weniger eingeben müssen, als gerade eben eingegeben wurde.

Erweiterte Optionen

Max. Verbindungsanzahl steuern

Sie können das Attribut max-connections festlegen, um zu steuern, 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 erneut 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 nochmal 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 des gcloud-Befehlszeilentools 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 in Ihrem 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 Ausgabedaten nicht mehr entgegen nimmt, ohne die Verbindung zu trennen, und mehr als 1 MiB neuer Daten erzeugt werden, könnte Ihr SSH-Client Ausgabedaten verpassen. In Situationen, in denen Ihr SSH-Client Ausgabedaten nicht schnell genug entgegen nimmt, 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: Trennt die Verbindung.

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.

Fügen Sie im Befehlszeilentool gcloud Folgendes zu Ihrem Befehl connect-to-serial-port hinzu:

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

Wenn Sie einen Drittanbieter-SSH-Client verwenden, geben Sie diese Option in Ihrem 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 dieser Option kann dazu führen, dass die Verbindung zu Ihrer 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 diese Option ist none, durch die nichts weiter passiert, wenn die DTR-Zeile sich ändert. Wenn Sie diesen Wert in "none" ändern, können Sie Ihre 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.

Weitere Informationen

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Compute Engine-Dokumentation