posix_initgroups — Funktion · PHP-Referenz

Signatur

posix_initgroups(string $username, int $group): bool

Beschreibung

posix_initgroups() ruft die Funktion initgroups(3) des Betriebssystems auf, die die Gruppenzugriffsliste des aktuellen Prozesses auf alle Gruppen setzt, zu denen der angegebene Benutzer gehört. Dabei wird sowohl die primäre Gruppe (angegeben über $group) als auch alle in der Systemdatenbank (z. B. /etc/group) eingetragenen Zusatzgruppen berücksichtigt.

Diese Funktion ist typischerweise beim Wechsel der Prozessidentität sinnvoll – etwa wenn ein PHP-Prozess (z. B. ein Daemon oder CLI-Skript) mit Root-Rechten startet und anschließend zu einem anderen Benutzer wechselt. Mit posix_initgroups() wird sichergestellt, dass der Prozess nach dem Wechsel korrekte Gruppenberechtigungen besitzt.

Die Funktion steht nur auf Unix-ähnlichen Betriebssystemen (Linux, macOS, BSD) zur Verfügung und erfordert üblicherweise Root-Rechte (UID 0), da das Setzen von Gruppenlisten privilegierter Operationen bedarf.

Zu beachten ist, dass posix_initgroups() die Gruppen des aktuellen Prozesses setzt, nicht die Gruppen eines anderen Prozesses. Die Funktion gehört zur POSIX-Erweiterung und muss über --enable-posix aktiviert sein (in PHP als Teil der Standard-Extensions oft bereits vorhanden).

Parameter

Name	Typ	Default	Beschreibung
$username Pflicht	string		Der Anmeldename des Benutzers, dessen Gruppenzugehörigkeiten aus der Systemdatenbank gelesen werden (z. B. `'www-data'`).
$group Pflicht	int		Die numerische Gruppen-ID der primären Gruppe des Benutzers. Dieser Wert wird üblicherweise über `posix_getpwnam()` ermittelt (Feld `gid`).

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Gruppenzugriffsliste erfolgreich gesetzt wurde, andernfalls false. Im Fehlerfall kann über posix_get_last_error() und posix_strerror() der genaue Fehler ermittelt werden.

Beispiele

Prozess zu einem anderen Benutzer wechseln und Gruppen initialisieren

<?php
// Nur als Root (UID 0) ausführbar
$username = 'www-data';

// Benutzerinformationen aus der Systemdatenbank holen
$userInfo = posix_getpwnam($username);

if ($userInfo === false) {
    die("Benutzer '{$username}' nicht gefunden.\n");
}

$uid = $userInfo['uid'];
$gid = $userInfo['gid'];

// Gruppenzugriffsliste initialisieren
if (!posix_initgroups($username, $gid)) {
    $errNo  = posix_get_last_error();
    $errMsg = posix_strerror($errNo);
    die("posix_initgroups fehlgeschlagen: {$errMsg}\n");
}

// Primäre Gruppe setzen
posix_setgid($gid);

// Benutzeridentität wechseln
posix_setuid($uid);

echo "Prozess läuft jetzt als Benutzer '{$username}' (UID={$uid}, GID={$gid}).\n";

Prozess läuft jetzt als Benutzer 'www-data' (UID=33, GID=33).

Fehlerbehandlung bei fehlenden Rechten

<?php
// Dieser Aufruf schlägt fehl, wenn das Skript nicht als Root ausgeführt wird
$result = posix_initgroups('nobody', 65534);

if (!$result) {
    $errNo  = posix_get_last_error();
    $errMsg = posix_strerror($errNo);
    echo "Fehler ({$errNo}): {$errMsg}\n";
} else {
    echo "Gruppen erfolgreich initialisiert.\n";
}

Fehler (1): Operation not permitted

// Wichtig · Fallstricke

Sicherheitshinweis: posix_initgroups() erfordert in der Regel Root-Rechte. Wird die Funktion in einem Skript ohne ausreichende Privilegien aufgerufen, schlägt sie fehl und gibt false zurück. Prüfen Sie daher vor dem Aufruf mit posix_getuid() === 0, ob das Skript als Root läuft.

Reihenfolge beachten: Beim Wechsel der Prozessidentität sollte posix_initgroups() vor posix_setgid() und posix_setuid() aufgerufen werden, da nach dem Ablegen der Root-Rechte keine Gruppenänderungen mehr möglich sind.

Verfügbarkeit: Die Funktion steht nur auf Systemen zur Verfügung, die POSIX-kompatibel sind (Linux, macOS, BSD). Unter Windows ist sie nicht verfügbar. Prüfen Sie die Verfügbarkeit mit function_exists('posix_initgroups').

Siehe auch

posix_setuid posix_setgid posix_getpwnam posix_getgroups posix_get_last_error posix_strerror