setns(2) System Calls Manual setns(2)
NOM
setns - Réassocier un thread avec un espace de noms
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#define _GNU_SOURCE /* Consultez feature_test_macros(7) */
#include <sched.h>
int setns(int fd, int nstype);
DESCRIPTION
L'appel système setns() permet au thread appelant de se déplacer dans
divers espaces de noms. Le paramètre fd est un des suivants :
• un descripteur de fichier renvoyant à un des liens magiques du ré-
pertoire /proc/pid/ns/ (ou un montage en boucle vers un tel lien) ;
• un descripteur de fichier de PID (pidfd_open(2)).
La paramètre nstype est interprété différemment dans chaque cas.
fd renvoie à un lien /proc/[pid]/ns/
Si fd renvoie à un /proc/pid/ns/, setns() ré-associe le thread appelant
à l'espace de noms associé à ce lien, dans les contraintes posées par
le paramètre nstype. Dans cet utilisation, l'appel setns() ne change
qu'un des membres de l'espace de noms de l'appelant.
L'argument nstype indique les types d'espaces de noms auxquels le
thread appelant peut être réassocié. Cet argument peut prendre une des
valeurs suivantes :
0 fd peut faire référence à n'importe quel type d'espace de noms.
CLONE_NEWCGROUP (depuis Linux 4.6)
fd doit faire référence à un espace de noms cgroup.
CLONE_NEWIPC (à partir de Linux 3.0)
fd doit faire référence à un espace de noms IPC.
CLONE_NEWNET (à partir de Linux 3.0)
fd doit faire référence à un espace de noms réseau.
CLONE_NEWNS (à partir de Linux 3.8)
fd doit faire référence à un espace de noms de montage.
CLONE_NEWPID (depuis Linux 3.8)
fd doit faire référence à un espace de noms de PID descendant.
CLONE_NEWIPC (depuis Linux 5.8)
fd doit faire référence à un espace de noms de temps.
CLONE_NEWUSER (depuis Linux 3.8)
fd doit faire référence à un espace de noms utilisateur.
CLONE_NEWUTS (à partir de Linux 3.0)
fd doit faire référence à un espace de noms UTS.
Définir la valeur de nstype à zéro est suffisant si le thread appelant
connaît (ou n'a pas besoin de connaître) le type d'espace de noms au-
quel fd fait référence. Définir nstype à une valeur non nulle est utile
si l'appelant ne connaît pas le type de l'espace de noms référencé par
fd et veut s'assurer que l'espace de noms est du type souhaité. L'appe-
lant pourrait ne pas connaître le type de l'espace de noms auquel fd
fait référence si le descripteur de fichiers a été ouvert par un autre
processus et qu'il a, par exemple, été passé à l'appelant par un socket
UNIX.
fd est un descripteur de fichier de PID
Depuis Linux 5.8, fd peut renvoyer à un descripteur de fichier de PID
qu'on récupère avec pidfd_open(2) ou clone(2). Dans cette utilisation,
setns() déplace de manière atomique le thread appelant dans un ou plu-
sieurs espaces de noms en tant que thread auquel fd renvoie.
Le paramètre nstype est un masque de bits indiqué par une liaison et
une ou plusieurs des constantes d'espace de noms CLONE_NEW* listées
ci-dessus. L'appelant est déplacé dans chacun des espaces de nom du
thread cible indiqué dans nstype ; l'appartenance de l'appelant aux
autres espaces de noms demeure inchangée.
Par exemple, le code suivant déplace l'appelant dans les mêmes espace
de noms utilisateur, réseau et UTS sous le PID 1234, mais les autres
appartenances à l'espace de noms de l'appelant ne changent pas :
int fd = pidfd_open(1234, 0);
setns(fd, CLONE_NEWUSER | CLONE_NEWNET | CLONE_NEWUTS);
Détails sur des types d'espace de noms spécifiques
Notez les détails et les restrictions suivantes lors de la ré-associa-
tion à certains types d'espace de noms spécifiques :
Espaces de nom utilisateur
Un processus qui se ré-associe à un espace de noms utilisateur
doit disposer de la capacité CAP_SYS_ADMIN dans l'espace de noms
utilisateur cible (donc, nécesairement, il n'est possible d'at-
teindre qu'un espace de noms descendant). Lorsque le déplacement
réussit, un processus se voit accorder toutes les capacités de
cet espace de noms, quels que soient ses IDentifiants d'utilisa-
teur et de groupe.
Un processus de plusieurs threads ne peut pas changer d'espace
de noms utilisateur avec setns().
Il n'est pas permis d'utiliser setns() pour revenir dans l'es-
pace de noms utilisateur de l'appelant. Cela empêche un appelant
n'ayant plus ces capacités de les retrouver à l'aide d'un appel
à setns().
Pour des raisons de sécurité, un processus ne peut pas atteindre
un nouvel espace de noms utilisateur s'il partage des attributs
liés à un système de fichiers (dont le partage est contrôlé avec
le drapeau CLONE_FS de clone(2)) avec un autre processus.
Pour obtenir plus d'informations sur les espaces de noms utili-
sateur, consultez user_namespaces(7).
Espaces de noms montage
Pour pouvoir changer d'espace de noms de montage, l'appelant
doit disposer des capacités CAP_SYS_CHROOT et CAP_SYS_ADMIN dans
son propre espace de noms utilisateur, et de la capacité
CAP_SYS_ADMIN dans l'espace de noms de montage cible.
Un processus ne peut pas atteindre un nouvel espace de noms de
montage s'il partage des attributs relatifs à un système de fi-
chiers (dont le partage est contrôlé par le drapeau CLONE_FS de
clone(2)) avec un autre processus.
Voir user_namespaces(7) pour des détails sur l'interaction entre
les espaces de noms utilisateur et de montage.
Espaces de noms PID
Pour se ré-associer à un nouvel espace de noms PID, l'appelant
doit avoir la capacité CAP_SYS_ADMIN dans son espace de noms
utilisateur et dans celui auquel appartient l'espace de noms PID
cible.
Réassocier l'espace de noms d'un PID a un comportement différent
des autres types d'espace de noms. La ré-association du thread
appelant avec un espace de noms de PID change seulement l'espace
de noms de PID dans lequel les processus enfants de l'appelant
seront créés ; cela ne change pas l'espace de noms PID de l'ap-
pelant.
La ré-association à un espace de noms PID n'est autorisée que si
l'espace de noms PID cible est un descendant (l'enfant, le pe-
tit-enfant, etc) ou est le même que celui de l'appelant.
Pour plus d'informations sur les espaces de noms des PIDs, re-
portez vous à namespaces(7).
Espaces de noms cgroup
Pour se ré-associer à un nouvel espace de noms cgroup, l'appe-
lant doit avoir la capacité CAP_SYS_ADMIN dans son propre espace
de noms utilisateur et dans celui auquel appartient l'espace de
noms cgroup cible.
L'utilisation de setns() pour changer d'espace de noms cgroup ne
change pas l'appartenance cgroup de l'appelant.
Espaces de noms réseau, IPC, de temps et UTS
Pour se ré-associer à un nouvel espace de noms réseau, IPC, de
temps ou UTS, l'appelant doit disposer des capacités CAP_SYS_AD-
MIN dans son propre espace de noms utilisateur et dans l'espace
de noms utilisateur qui possède l'espace de noms cible.
VALEUR RENVOYÉE
S'il réussit, setns() renvoie 0, sinon il renvoie -1 et errno est posi-
tionné pour indiquer l'erreur.
ERREURS
EBADF fd n'est pas un descripteur de fichier valable.
EINVAL fd fait référence à un espace de noms dont le type ne correspond
pas à celui indiqué dans nstype.
EINVAL Il y a un problème pour ré-associer le thread avec l'espace de
noms indiqué.
EINVAL L'appelant a essayé d'atteindre un espace de noms PID ancêtre
(parent, grand-parent, etc).
EINVAL L'appelant a tenté d'intégrer un espace de noms utilisateur dont
il est déjà membre.
EINVAL L'appelant partage un état de système de fichiers (CLONE_FS),
notamment le répertoire racine, avec d'autres processus et a
tenté d'intégrer un nouvel espace de noms.
EINVAL L'appelant est multi-threadé et a tenté d'intégrer un nouvel es-
pace de noms utilisateur.
EINVAL fd est un descripteur de fichier de PID et nstype n'est pas va-
lable (il vaut par exemple 0).
ENOMEM Impossible d'allouer suffisamment de mémoire pour changer l'es-
pace de noms indiqué.
EPERM Le processus appelant n'avait pas la capacité appropriée pour
effectuer cette opération.
ESRCH fd est un descripteur de fichier PID mais le processus auquel il
renvoie n'existe plus (c'est-à-dire qu'il s'est terminé et at-
tend).
VERSIONS
L'appel système setns() est apparu dans Linux 3.0 ; sa prise en charge
a été ajoutée dans la glibc 2.14.
STANDARDS
L'appel système setns() est spécifique à Linux.
NOTES
Pour obtenir plus d'informations sur les liens magiques /proc/pid/ns/,
consultez namespaces(7).
Certains des attributs qui peuvent être partagés avec un nouveau thread
créé avec clone(2) ne peuvent pas être modifiés en utilisant setns().
EXEMPLES
Le programme ci-dessous attend au moins deux arguments. Le premier pré-
cise le chemin d'un fichier d'espace de noms dans un répertoire
/proc/pid/ns/ qui doit exister préalablement. Les arguments suivants
précisent une commande et ses arguments. Le programme ouvre le fichier
d'espace de noms, s'associe à l'espace de noms en utilisant setns(), et
exécute la commande indiquée dans cet espace de noms.
La session d'invite de commandes suivante présente l'utilisation du
programme (compilé en un binaire appelé ns_exec) en lien avec le pro-
gramme CLONE_NEWUTS donné en exemple dans la page de manuel clone(2)
(compilé en un binaire appelé newuts).
Nous commençons par exécuter le programme donné à titre d'exemple dans
clone(2) en tâche de fond. Ce programme crée un processus enfant dans
un espace de noms UTS distinct. Le processus enfant change le nom
d'hôte dans son espace de noms, puis les deux processus affichent leur
noms d'hôte dans leurs espaces de noms UTS respectifs, de façon à bien
montrer leur différence.
$ su # Privilèges nécessaires aux opérations sur l'espace de noms
Mot de passe :
# ./newuts bizarro &
[1] 3549
clone() a renvoyé 3550
uts.nodename dans l'enfant : bizarro
uts.nodename dans le parent : antero
# uname -n # Vérifier le nom d'hôte dans l'invite de commande
antero
Nous appelons alors le programme présenté ci-dessous afin de lancer une
invite de commande. Dans cette invite, on vérifie que le nom d'hôte est
bien celui défini par le processus enfant créé dans le premier pro-
gramme :
# ./ns_exec /proc/3550/ns/uts /bin/bash
# uname -n # Exécuté dans l'invite lancée par ns_exec
bizarro
Source du programme
#define _GNU_SOURCE
#include <err.h>
#include <fcntl.h>
#include <sched.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{
int fd;
if (argc < 3) {
fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\n", argv[0]);
exit(EXIT_FAILURE);
}
/* Récupérer le descripteur de fichier de l'espace de noms ; le descripteur
de fichier est ouvert avec O_CLOEXEC pour garantir qu'il n'est pas
récupéré par le programme exécuté en dernier. */
fd = open(argv[1], O_RDONLY | O_CLOEXEC);
if (fd == -1)
err(EXIT_FAILURE, "open");
if (setns(fd, 0) == -1) /* Rejoindre cet espace de noms */
err(EXIT_FAILURE, "setns");
execvp(argv[2], &argv[2]); /* Exécuter une commande dans l'espace de noms */
err(EXIT_FAILURE, "execvp");
}
VOIR AUSSI
nsenter(1), clone(2), fork(2), unshare(2), vfork(2), namespaces(7),
unix(7)
TRADUCTION
La traduction française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, Fran-
çois Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Gué-
rard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.org>, David Prévot <david@tilapin.org>, Cédric Boutillier <ce-
dric.boutillier@gmail.com>, Frédéric Hantrais <fhantrais@gmail.com> et
Jean-Philippe MENGUAL <jpmengual@debian.org>
Cette traduction est une documentation libre ; veuillez vous reporter à
la GNU General Public License version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les conditions
de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à ⟨debian-l10n-french@lists.debian.org⟩.
Pages du manuel de Linux 6.03 5 février 2023 setns(2)
Generated by dwww version 1.15 on Sat Jun 29 01:43:16 CEST 2024.