ssh2_forward_listen — Funktion · PHP-Referenz

Signatur

ssh2_forward_listen(resource $session, int $port, string $host = null, int $max_connections = 16): resource|false

Beschreibung

ssh2_forward_listen() richtet auf dem entfernten SSH-Server einen TCP-Listener ein, der auf Verbindungen an einem bestimmten Port wartet. Dies entspricht dem Konzept des Remote Port Forwarding (vergleichbar mit ssh -R auf der Kommandozeile): Der entfernte Server lauscht auf dem angegebenen Port und leitet eingehende Verbindungen über den verschlüsselten SSH-Tunnel an den lokalen Client weiter.

Die Funktion gibt eine Listener-Ressource zurück, die anschließend mit ssh2_forward_accept() verwendet werden kann, um eingehende Verbindungen entgegenzunehmen und als Stream zu öffnen. Über diesen Stream kann dann wie bei einem normalen Socket-Stream kommuniziert werden.

Typische Einsatzgebiete sind das sichere Weiterleiten von Diensten, die nur auf dem entfernten Server erreichbar sind, oder das Erstellen von Tunnel-Verbindungen in gesicherten Netzwerken. Die Funktion benötigt eine bestehende, authentifizierte SSH2-Session, die zuvor mit ssh2_connect() und einer der Authentifizierungsfunktionen aufgebaut wurde.

Diese Funktion steht nur zur Verfügung, wenn die SSH2-PECL-Extension installiert ist (pecl install ssh2). Sie ist nicht Bestandteil der PHP-Standardinstallation.

Parameter

Name	Typ	Default	Beschreibung
$session Pflicht	resource		Eine aktive SSH2-Verbindungsressource, die zuvor mit `ssh2_connect()` erstellt und authentifiziert wurde.
$port Pflicht	int		Der Port auf dem entfernten Server, auf dem gelauscht werden soll. Bei Angabe von `0` wählt der Server automatisch einen freien Port.
$host	string		Optionale Angabe des Hostnamens oder der IP-Adresse auf dem entfernten Server, an die der Listener gebunden werden soll. Wird dieser Parameter weggelassen, lauscht der Server auf allen Interfaces.
$max_connections	int	16	Die maximale Anzahl gleichzeitig wartender Verbindungen in der Accept-Warteschlange des Listeners.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine SSH2-Listener-Ressource zurück, die mit ssh2_forward_accept() verwendet werden kann. Im Fehlerfall wird false zurückgegeben.

Beispiele

Remote Port Forwarding einrichten und eine Verbindung annehmen

<?php
// SSH-Verbindung aufbauen
$session = ssh2_connect('remote.example.com', 22);
if (!$session) {
    die('SSH-Verbindung fehlgeschlagen.');
}

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

// Listener auf Port 8080 des entfernten Servers binden
$listener = ssh2_forward_listen($session, 8080, '127.0.0.1', 10);
if (!$listener) {
    die('Listener konnte nicht eingerichtet werden.');
}

echo "Warte auf eingehende Verbindungen auf remote Port 8080..." . PHP_EOL;

// Eingehende Verbindung annehmen
$channel = ssh2_forward_accept($listener);
if ($channel) {
    // Daten lesen
    $data = fread($channel, 4096);
    echo "Empfangene Daten: " . $data . PHP_EOL;

    // Antwort senden
    fwrite($channel, "HTTP/1.0 200 OK\r\nContent-Length: 5\r\n\r\nHello");
    fclose($channel);
} else {
    echo "Keine Verbindung angenommen." . PHP_EOL;
}
?>

Warte auf eingehende Verbindungen auf remote Port 8080...

Automatischen Port vom Server zuweisen lassen

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

// Port 0 = Server wählt freien Port automatisch
$listener = ssh2_forward_listen($session, 0);
if ($listener) {
    echo "Listener erfolgreich erstellt." . PHP_EOL;
    // Mit ssh2_forward_accept() auf Verbindungen warten ...
} else {
    echo "Fehler beim Einrichten des Listeners." . PHP_EOL;
}
?>

Listener erfolgreich erstellt.

// Wichtig · Fallstricke

PECL-Abhängigkeit: Diese Funktion ist Teil der ssh2-PECL-Extension und nicht im PHP-Kern enthalten. Die Extension muss separat installiert werden (pecl install ssh2).

Blocking-Verhalten: ssh2_forward_accept() blockiert standardmäßig, bis eine Verbindung eingeht. In produktiven Anwendungen sollte ein Timeout oder eine nicht-blockierende Verarbeitungsschleife implementiert werden, um einen Deadlock zu vermeiden.

Sicherheit: Das Remote Port Forwarding erlaubt es, Dienste auf dem entfernten Server über den SSH-Tunnel zugänglich zu machen. Es sollte sichergestellt werden, dass nur vertrauenswürdige Verbindungen akzeptiert werden und der SSH-Server entsprechend konfiguriert ist (GatewayPorts in der sshd-Konfiguration).

Ressourcenverwaltung: Der Listener und alle davon abgeleiteten Channels sollten nach der Nutzung mit fclose() geschlossen werden, um Ressourcenlecks zu vermeiden.

Siehe auch

ssh2_connect ssh2_forward_accept ssh2_auth_password ssh2_auth_pubkey_file ssh2_tunnel