Signatur
Beschreibung
ssh2_scp_recv() überträgt eine Datei vom entfernten SSH-Server auf das lokale System mittels des SCP-Protokolls (Secure Copy Protocol). Die Funktion ist Teil der SSH2-Erweiterung (PECL ssh2) und setzt eine bestehende, authentifizierte SSH-Verbindung voraus, wie sie z. B. von ssh2_connect() und ssh2_auth_password() geliefert wird.
SCP ist ein einfaches, sicheres Dateiübertragungsprotokoll, das SSH als Transport nutzt. Im Gegensatz zu SFTP bietet SCP keine Verzeichnisoperationen oder Dateiattribut-Verwaltung, ist aber für einfache Dateiübertragungen schnell und unkompliziert einzusetzen.
Der Pfad remote_file muss den vollständigen, absoluten Pfad der Quelldatei auf dem Server angeben. Der Pfad local_file gibt an, wohin die Datei auf dem lokalen System gespeichert werden soll – das Verzeichnis muss beschreibbar sein. Existiert die Zieldatei bereits, wird sie überschrieben.
Sinnvoll eingesetzt wird diese Funktion etwa beim automatisierten Abrufen von Log-Dateien, Backups oder Konfigurationsdateien von entfernten Servern in PHP-Skripten oder CLI-Tools.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $session Pflicht | resource | Eine aktive SSH2-Verbindungsressource, die zuvor mit ssh2_connect() erstellt und authentifiziert wurde. |
|
| $remote_file Pflicht | string | Absoluter Pfad zur Quelldatei auf dem entfernten SSH-Server, z. B. /var/log/app.log. |
|
| $local_file Pflicht | string | Lokaler Dateipfad, unter dem die heruntergeladene Datei gespeichert wird, z. B. /tmp/app.log. Das Zielverzeichnis muss existieren und beschreibbar sein. |
Rückgabewert
true zurück, wenn die Datei erfolgreich übertragen wurde. Bei einem Fehler (z. B. Datei nicht vorhanden, fehlende Berechtigungen, Verbindungsprobleme) wird false zurückgegeben.Beispiele
Log-Datei vom Server herunterladen
<?php
// SSH-Verbindung herstellen
$connection = ssh2_connect('example.com', 22);
if (!$connection) {
die('Verbindung zum Server fehlgeschlagen.');
}
// Authentifizierung mit Benutzername und Passwort
if (!ssh2_auth_password($connection, 'deploy', 'geheimesPasswort')) {
die('Authentifizierung fehlgeschlagen.');
}
// Datei per SCP herunterladen
$remote = '/var/log/app/error.log';
$local = '/tmp/error.log';
if (ssh2_scp_recv($connection, $remote, $local)) {
echo "Datei erfolgreich heruntergeladen nach: $local" . PHP_EOL;
} else {
echo "Fehler beim Herunterladen der Datei." . PHP_EOL;
}
?>SCP-Download mit Schlüssel-Authentifizierung
<?php
$connection = ssh2_connect('backup.example.com', 22);
if (!$connection) {
die('Verbindung fehlgeschlagen.');
}
// Public-Key-Authentifizierung
if (!ssh2_auth_pubkey_file(
$connection,
'backup-user',
'/home/www/.ssh/id_rsa.pub',
'/home/www/.ssh/id_rsa'
)) {
die('SSH-Schlüsselauthentifizierung fehlgeschlagen.');
}
$remoteBackup = '/backups/db_2024-01-15.sql.gz';
$localTarget = '/var/www/restores/db_2024-01-15.sql.gz';
if (ssh2_scp_recv($connection, $remoteBackup, $localTarget)) {
echo 'Backup erfolgreich abgerufen.' . PHP_EOL;
echo 'Dateigröße: ' . filesize($localTarget) . ' Bytes' . PHP_EOL;
} else {
echo 'SCP-Übertragung fehlgeschlagen.' . PHP_EOL;
}
?>// Wichtig · Fallstricke
Voraussetzung: Die PECL-Erweiterung ssh2 muss installiert und in der php.ini geladen sein (extension=ssh2.so). Sie ist nicht standardmäßig in PHP enthalten.
Sicherheitshinweis: Speichere Passwörter und private Schlüssel niemals hartcodiert im Quellcode. Verwende Umgebungsvariablen oder sichere Konfigurationsdateien außerhalb des Web-Roots.
Pfade prüfen: Stelle sicher, dass local_file auf ein beschreibbares Verzeichnis zeigt und der PHP-Prozess entsprechende Dateisystemrechte besitzt. Ein relativer Pfad kann zu unerwarteten Speicherorten führen.
Alternativen: Für komplexere Szenarien (Verzeichnislisting, Attribute, partielle Übertragungen) sollte ssh2_sftp() in Kombination mit den SFTP-Funktionen verwendet werden. Für einfache Skripte kann auch der CLI-Befehl scp über exec() aufgerufen werden, was jedoch eigene Sicherheitsrisiken birgt.