chroot — Funktion · PHP-Referenz

Signatur

chroot(string $directory): bool

Beschreibung

chroot() ändert das Wurzelverzeichnis (root directory) des aktuellen PHP-Prozesses auf das angegebene Verzeichnis. Nach einem erfolgreichen chroot()-Aufruf ist für den Prozess kein Zugriff mehr auf Dateien außerhalb dieses neuen Wurzelverzeichnisses möglich – die Verzeichnisstruktur ist aus Sicht des Prozesses auf den neuen Wurzelpfad beschränkt.

Dies ist ein klassisches Sicherheitskonzept (chroot jail), das häufig in Serverdaemon-Umgebungen eingesetzt wird, um den Zugriff eines Prozesses auf das Dateisystem zu isolieren. Wenn ein Angreifer den eingesperrten Prozess kompromittiert, kann er nur auf Dateien innerhalb der Chroot-Umgebung zugreifen.

Wichtig: Die Funktion erfordert Root-Privilegien (unter Unix/Linux) und steht nur auf Unix-ähnlichen Systemen zur Verfügung. Unter Windows ist sie nicht verfügbar. Zusätzlich muss nach chroot() häufig ein chdir('/') ausgeführt werden, da das aktuelle Arbeitsverzeichnis möglicherweise außerhalb des neuen Wurzels liegt.

Für eine sichere Chroot-Umgebung müssen alle benötigten Bibliotheken, Konfigurationsdateien und ausführbaren Dateien in das neue Wurzelverzeichnis kopiert werden, da der Prozess sonst keinen Zugriff auf systemweite Ressourcen hat.

Parameter

Name	Typ	Default	Beschreibung
$directory Pflicht	string		Der absolute Pfad des Verzeichnisses, das als neues Wurzelverzeichnis (root) des Prozesses gesetzt werden soll.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Wurzelverzeichnis erfolgreich gewechselt wurde, andernfalls false. Bei fehlenden Rechten oder nicht vorhandenem Verzeichnis wird false zurückgegeben und eine Warnung ausgegeben.

Beispiele

Grundlegende Verwendung von chroot()

<?php
// Nur als Root (POSIX) ausführbar
if (posix_getuid() !== 0) {
    die('Dieses Skript muss als Root ausgeführt werden.' . PHP_EOL);
}

$jail = '/var/chroot/meine_app';

if (!chroot($jail)) {
    die('chroot() fehlgeschlagen.' . PHP_EOL);
}

// Arbeitsverzeichnis auf neues Wurzelverzeichnis setzen
chdir('/');

echo 'Wurzelverzeichnis erfolgreich auf ' . $jail . ' gesetzt.' . PHP_EOL;
echo 'Aktuelles Verzeichnis: ' . getcwd() . PHP_EOL;
// Ausgabe: Aktuelles Verzeichnis: /

Wurzelverzeichnis erfolgreich auf /var/chroot/meine_app gesetzt. Aktuelles Verzeichnis: /

chroot() in einem Serverdaemon-Szenario

<?php
// Beispiel: Daemon, der sich nach dem Start in eine Chroot-Umgebung einsperrt
function daemonize(string $chrootDir): void
{
    if (posix_getuid() !== 0) {
        throw new RuntimeException('Root-Rechte erforderlich.');
    }

    // Notwendige Ressourcen müssen bereits in $chrootDir vorhanden sein
    if (!is_dir($chrootDir)) {
        throw new RuntimeException('Chroot-Verzeichnis existiert nicht: ' . $chrootDir);
    }

    if (!chroot($chrootDir)) {
        throw new RuntimeException('chroot() fehlgeschlagen für: ' . $chrootDir);
    }

    chdir('/');

    // Jetzt Rechte auf unprivilegierten Benutzer herabsetzen
    posix_setgid(1000);
    posix_setuid(1000);

    echo 'Daemon läuft in Chroot-Umgebung: ' . $chrootDir . PHP_EOL;
}

try {
    daemonize('/var/chroot/daemon');
} catch (RuntimeException $e) {
    echo 'Fehler: ' . $e->getMessage() . PHP_EOL;
}

// Wichtig · Fallstricke

Sicherheitshinweise:

Eine Chroot-Umgebung ist kein vollständiger Sicherheitsmechanismus. Mit Root-Rechten innerhalb der Chroot kann ein Angreifer aus ihr ausbrechen. Deshalb sollten nach chroot() die Prozessrechte mittels posix_setuid() und posix_setgid() auf einen unprivilegierten Benutzer herabgesetzt werden.
Die Funktion ist nur auf Unix/Linux-Systemen verfügbar und steht unter Windows nicht zur Verfügung.
Nach chroot() sollte immer chdir('/') aufgerufen werden, um sicherzustellen, dass das aktuelle Arbeitsverzeichnis innerhalb der neuen Wurzel liegt.
Alle Bibliotheken (.so-Dateien), Gerätedateien und Konfigurationsdateien, die der Prozess benötigt, müssen in die Chroot-Umgebung kopiert werden.
In PHP-CLI-Skripten und Webserver-Kontexten (z. B. PHP-FPM) kann chroot() das Verhalten von Dateioperationen und Include-Pfaden grundlegend verändern.

Siehe auch

chdir getcwd posix_setuid posix_setgid posix_getuid