ssh2_shell — Funktion · PHP-Referenz

Signatur

ssh2_shell(resource $session, string $term_type = 'vanilla', array|null $env = null, int $width = 80, int $height = 25, int $width_height_type = SSH2_TERM_UNIT_CHARS): resource|false

Beschreibung

ssh2_shell() öffnet eine interaktive Shell-Sitzung über eine bestehende SSH-2-Verbindung. Die Funktion gibt einen Stream zurück, der sowohl zum Lesen (stdout/stderr) als auch zum Schreiben (stdin) verwendet werden kann. Damit lassen sich beliebige Befehle interaktiv an die Remote-Shell senden und deren Ausgaben empfangen.

Im Gegensatz zu ssh2_exec(), das einen einzelnen Befehl ausführt, bleibt die Shell-Sitzung dauerhaft geöffnet. Das ermöglicht zustandsbehaftete Interaktionen, bei denen das Ergebnis eines Befehls den Kontext für den nächsten beeinflusst (z. B. Verzeichniswechsel mit cd).

Der Parameter term_type legt den Terminaltyp fest (z. B. vt102, xterm, vanilla). Über env können Umgebungsvariablen als assoziatives Array gesetzt werden. Die Breite und Höhe des pseudo-TTY lassen sich per width/height und width_height_type konfigurieren – entweder in Zeichenanzahl (SSH2_TERM_UNIT_CHARS) oder Pixeln (SSH2_TERM_UNIT_PIXELS).

Die Funktion gehört zur PECL-Erweiterung ssh2 und muss vor der Verwendung installiert und aktiviert sein. Für produktive Anwendungen sollte statt eines interaktiven Shells in der Regel ssh2_exec() bevorzugt werden, da es einfacher zu kontrollieren ist.

Parameter

Name	Typ	Default	Beschreibung
$session Pflicht	resource		Eine aktive SSH-2-Verbindungsressource, die z. B. mit `ssh2_connect()` und anschließender Authentifizierung erzeugt wurde.
$term_type	string	vanilla	Der Terminaltyp des pseudo-TTY (z. B. `'xterm'`, `'vt102'`, `'vanilla'`). Der Server wählt auf Basis dieses Wertes passende Steuersequenzen.
$env	array\|null	null	Assoziatives Array von Umgebungsvariablen, die in der Remote-Shell gesetzt werden sollen. Viele SSH-Server beschränken, welche Variablen tatsächlich akzeptiert werden.
$width	int	80	Breite des virtuellen Terminals – je nach `width_height_type` in Zeichen oder Pixeln.
$height	int	25	Höhe des virtuellen Terminals – je nach `width_height_type` in Zeichen oder Pixeln.
$width_height_type	int	SSH2_TERM_UNIT_CHARS	Gibt die Einheit für `width` und `height` an. Mögliche Werte: `SSH2_TERM_UNIT_CHARS` (Standard) oder `SSH2_TERM_UNIT_PIXELS`.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine Stream-Ressource zurück, die als bidirektionaler Kanal zur interaktiven Shell dient. Bei einem Fehler (z. B. ungültige Sitzung oder Serverablehnug) wird false zurückgegeben.

Beispiele

Interaktive Shell öffnen und Befehle senden

<?php
// Verbindung herstellen
$connection = ssh2_connect('example.com', 22);
if (!$connection) {
    die('Verbindung fehlgeschlagen.');
}

// Authentifizierung
if (!ssh2_auth_password($connection, 'benutzer', 'geheimesPasswort')) {
    die('Authentifizierung fehlgeschlagen.');
}

// Interaktive Shell anfordern
$shell = ssh2_shell($connection, 'xterm', null, 200, 50, SSH2_TERM_UNIT_CHARS);
if (!$shell) {
    die('Shell konnte nicht geöffnet werden.');
}

// Befehl senden
fwrite($shell, "ls -la /var/www\n");
sleep(1); // Ausgabe abwarten

// Ausgabe lesen
stream_set_blocking($shell, false);
$output = stream_get_contents($shell);
echo $output;

// Shell schließen
fclose($shell);

Shell mit Umgebungsvariablen und mehreren Befehlen

<?php
$connection = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file(
    $connection,
    'benutzer',
    '/home/benutzer/.ssh/id_rsa.pub',
    '/home/benutzer/.ssh/id_rsa'
);

$env = [
    'LANG' => 'de_DE.UTF-8',
    'MY_VAR' => 'hello',
];

$shell = ssh2_shell($connection, 'vt102', $env, 120, 40);
if (!$shell) {
    die('Shell-Sitzung konnte nicht gestartet werden.');
}

// Mehrere Befehle sequenziell absetzen
$befehle = [
    "cd /var/log\n",
    "ls -lh\n",
    "tail -n 5 syslog\n",
];

foreach ($befehle as $cmd) {
    fwrite($shell, $cmd);
    sleep(1);
    stream_set_blocking($shell, false);
    echo stream_get_contents($shell);
}

fclose($shell);

// Wichtig · Fallstricke

Sicherheitshinweis: Übergeben Sie niemals vom Benutzer kontrollierte Daten ungefiltert als Befehle an die Shell. Auch über SSH kann eine Shell-Injektion auftreten, wenn Eingaben nicht korrekt escaped werden.

Synchronisation: Die Ausgabe auf dem Stream ist asynchron. Ein einfaches sleep() ist keine zuverlässige Methode, um auf die vollständige Ausgabe zu warten. Für produktive Szenarien empfiehlt sich das Warten auf ein bekanntes Prompt-Zeichen oder die Verwendung von ssh2_exec() für einzelne Befehle.

Für einfache Befehle: Wenn nur ein einzelner Befehl ausgeführt werden soll, ist ssh2_exec() in der Regel besser geeignet, da es einfacher handhabbare Streams für stdin, stdout und stderr liefert.

PECL-Erweiterung: ssh2_shell() erfordert die PECL-Erweiterung ssh2 (libssh2). Diese ist nicht Teil des PHP-Kerns und muss separat installiert werden (pecl install ssh2).

Siehe auch

ssh2_connect ssh2_exec ssh2_auth_password ssh2_auth_pubkey_file ssh2_fetch_stream