pcntl_setns — Funktion · PHP-Referenz

Signatur

pcntl_setns(int $fd, int $nstype = 0): bool

Beschreibung

pcntl_setns() ist ein dünner Wrapper um den Linux-Systemaufruf setns(2). Damit kann ein laufender Prozess einem bestehenden Linux-Namespace (z. B. PID-, Netzwerk-, Mount- oder UTS-Namespace) beitreten, der einem anderen Prozess gehört. Der Namespace wird über einen offenen Dateideskriptor identifiziert, der typischerweise durch Öffnen eines symbolischen Links unter /proc/[pid]/ns/ mit fopen() oder dem Low-Level-Pendant erzeugt wurde.

Die Funktion ist besonders nützlich beim Bau von Container-Management-Tools, Sandboxen oder Orchestrierungssoftware direkt in PHP. Sie ermöglicht es, einzelne Threads oder Prozesse gezielt in einen anderen Kontext zu versetzen – etwa um Netzwerkoperationen innerhalb eines bestimmten Netzwerk-Namespaces auszuführen, ohne den gesamten Prozessbaum zu verändern.

Der Parameter nstype entspricht den CLONE_NEW*-Konstanten des Kernels (z. B. CLONE_NEWNET, CLONE_NEWPID, CLONE_NEWUTS) und erlaubt es, den übergebenen Dateideskriptor gegen einen konkreten Namespace-Typ zu validieren. Wird 0 übergeben, entfällt diese Prüfung.

Hinweis: Diese Funktion steht nur auf Linux-Systemen zur Verfügung und erfordert in der Regel erhöhte Berechtigungen (CAP_SYS_ADMIN). Sie ist Teil der pcntl-Erweiterung, die explizit kompiliert werden muss.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	int		Ein offener Dateideskriptor, der auf eine Namespace-Datei unter `/proc/[pid]/ns/` zeigt. Kann z. B. mit `fopen()` und anschließendem `fileno()`-Äquivalent oder direkt über Low-Level-Funktionen erzeugt werden.
$nstype	int	0	Ein optionaler Namespace-Typ zur Validierung des Dateideskriptors. Gültige Werte sind Kernel-Konstanten wie `CLONE_NEWNET`, `CLONE_NEWPID`, `CLONE_NEWUTS` etc. Bei `0` (Standard) wird keine Typprüfung durchgeführt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück. Bei einem Fehler (z. B. fehlende Berechtigungen, ungültiger Dateideskriptor oder Namespace-Typ-Konflikt) wird false zurückgegeben.

Beispiele

In den Netzwerk-Namespace eines anderen Prozesses wechseln

<?php
// PID des Prozesses, dessen Netzwerk-Namespace wir betreten wollen
$targetPid = 1234;
$nsFile = "/proc/{$targetPid}/ns/net";

if (!file_exists($nsFile)) {
    die("Namespace-Datei nicht gefunden: {$nsFile}\n");
}

// Dateideskriptor öffnen
$fh = fopen($nsFile, 'r');
if ($fh === false) {
    die("Konnte Namespace-Datei nicht öffnen.\n");
}

$fd = (int) $fh; // Rohwert – in der Praxis wird fileno()-Äquivalent benötigt
// Hinweis: PHP bietet kein direktes fileno(); für echten Einsatz
// muss der FD über FFI oder eine C-Extension ermittelt werden.

// CLONE_NEWNET = 0x40000000 (Linux-Konstante)
$result = pcntl_setns((int)$fd, 0x40000000);

if ($result) {
    echo "Erfolgreich in den Netzwerk-Namespace von PID {$targetPid} gewechselt.\n";
} else {
    echo "Fehler beim Wechsel in den Namespace.\n";
}

fclose($fh);

Erfolgreich in den Netzwerk-Namespace von PID 1234 gewechselt.

Namespace-Typ-Validierung mit nstype = 0 überspringen

<?php
// Ohne Typ-Validierung – nützlich, wenn der Namespace-Typ im Voraus bekannt ist
$targetPid = getenv('TARGET_PID') ?: 1;
$nsFile = "/proc/{$targetPid}/ns/uts";

$fh = fopen($nsFile, 'r');
if ($fh === false) {
    die("Namespace nicht zugänglich.\n");
}

// nstype = 0: keine Typvalidierung
if (pcntl_setns((int)$fh, 0)) {
    echo "UTS-Namespace betreten (kein Typcheck).\n";
} else {
    echo "Fehler: Namespace konnte nicht betreten werden.\n";
}

fclose($fh);

UTS-Namespace betreten (kein Typcheck).

// Wichtig · Fallstricke

Plattform: pcntl_setns() ist ausschließlich auf Linux verfügbar und steht nicht unter Windows oder macOS zur Verfügung. Auf anderen Plattformen führt der Aufruf zu einem fatalen Fehler oder ist nicht kompiliert.

Berechtigungen: Der aufrufende Prozess benötigt in der Regel die Linux-Capability CAP_SYS_ADMIN, um Namespaces betreten zu dürfen. Ohne diese Berechtigung schlägt der Aufruf mit einem Fehler fehl. PHP-Skripte sollten daher nie dauerhaft mit Root-Rechten betrieben werden – nutze stattdessen gezielte Capabilities via setcap.

Dateideskriptor: PHP bietet keine direkte fileno()-Funktion. Für den produktiven Einsatz muss der Integer-Dateideskriptor einer geöffneten Ressource z. B. über PHP-FFI oder eine Native-Extension ermittelt werden.

Sicherheit: Das Wechseln in fremde Namespaces kann bei falscher Anwendung zu Sicherheitsproblemen führen, insbesondere wenn dadurch Netzwerkisolation oder Dateisystem-Isolierung umgangen wird. Verwende diese Funktion nur in kontrollierten, privilegierten Umgebungen.

Siehe auch

pcntl_unshare pcntl_fork pcntl_exec posix_getpid