diff options
Diffstat (limited to 'man2/setns.2')
| -rw-r--r-- | man2/setns.2 | 419 |
1 files changed, 0 insertions, 419 deletions
diff --git a/man2/setns.2 b/man2/setns.2 deleted file mode 100644 index 5bd3385..0000000 --- a/man2/setns.2 +++ /dev/null @@ -1,419 +0,0 @@ -.\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com> -.\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: GPL-2.0-only -.\" -.TH setns 2 2023-10-31 "Linux man-pages 6.7" -.SH NAME -setns \- reassociate thread with a namespace -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" -.B #include <sched.h> -.P -.BI "int setns(int " fd ", int " nstype ); -.fi -.SH DESCRIPTION -The -.BR setns () -system call allows the calling thread to move into different namespaces. -The -.I fd -argument is one of the following: -.IP \[bu] 3 -a file descriptor referring to one of the magic links in a -.IR /proc/ pid /ns/ -directory (or a bind mount to such a link); -.IP \[bu] -a PID file descriptor (see -.BR pidfd_open (2)). -.P -The -.I nstype -argument is interpreted differently in each case. -.\" -.SS fd refers to a \fI/proc/\fPpid\fI/ns/\fP link -If -.I fd -refers to a -.IR /proc/ pid /ns/ -link, then -.BR setns () -reassociates the calling thread with the namespace associated with that link, -subject to any constraints imposed by the -.I nstype -argument. -In this usage, each call to -.BR setns () -changes just one of the caller's namespace memberships. -.P -The -.I nstype -argument specifies which type of namespace -the calling thread may be reassociated with. -This argument can have -.I one -of the following values: -.TP -.B 0 -Allow any type of namespace to be joined. -.TP -.BR CLONE_NEWCGROUP " (since Linux 4.6)" -.I fd -must refer to a cgroup namespace. -.TP -.BR CLONE_NEWIPC " (since Linux 3.0)" -.I fd -must refer to an IPC namespace. -.TP -.BR CLONE_NEWNET " (since Linux 3.0)" -.I fd -must refer to a network namespace. -.TP -.BR CLONE_NEWNS " (since Linux 3.8)" -.I fd -must refer to a mount namespace. -.TP -.BR CLONE_NEWPID " (since Linux 3.8)" -.I fd -must refer to a descendant PID namespace. -.TP -.BR CLONE_NEWTIME " (since Linux 5.8)" -.\" commit 76c12881a38aaa83e1eb4ce2fada36c3a732bad4 -.I fd -must refer to a time namespace. -.TP -.BR CLONE_NEWUSER " (since Linux 3.8)" -.I fd -must refer to a user namespace. -.TP -.BR CLONE_NEWUTS " (since Linux 3.0)" -.I fd -must refer to a UTS namespace. -.P -Specifying -.I nstype -as 0 suffices if the caller knows (or does not care) -what type of namespace is referred to by -.IR fd . -Specifying a nonzero value for -.I nstype -is useful if the caller does not know what type of namespace is referred to by -.I fd -and wants to ensure that the namespace is of a particular type. -(The caller might not know the type of the namespace referred to by -.I fd -if the file descriptor was opened by another process and, for example, -passed to the caller via a UNIX domain socket.) -.\" -.SS fd is a PID file descriptor -Since Linux 5.8, -.I fd -may refer to a PID file descriptor obtained from -.BR pidfd_open (2) -or -.BR clone (2). -In this usage, -.BR setns () -atomically moves the calling thread into one or more of the same namespaces -as the thread referred to by -.IR fd . -.P -The -.I nstype -argument is a bit mask specified by ORing together -.I "one or more" -of the -.B CLONE_NEW* -namespace constants listed above. -The caller is moved into each of the target thread's namespaces -that is specified in -.IR nstype ; -the caller's memberships in the remaining namespaces are left unchanged. -.P -For example, the following code would move the caller into the -same user, network, and UTS namespaces as PID 1234, -but would leave the caller's other namespace memberships unchanged: -.P -.in +4n -.EX -int fd = pidfd_open(1234, 0); -setns(fd, CLONE_NEWUSER | CLONE_NEWNET | CLONE_NEWUTS); -.EE -.in -.\" -.SS Details for specific namespace types -Note the following details and restrictions when reassociating with -specific namespace types: -.TP -User namespaces -A process reassociating itself with a user namespace must have the -.B CAP_SYS_ADMIN -.\" See kernel/user_namespace.c:userns_install() [3.8 source] -capability in the target user namespace. -(This necessarily implies that it is only possible to join -a descendant user namespace.) -Upon successfully joining a user namespace, -a process is granted all capabilities in that namespace, -regardless of its user and group IDs. -.IP -A multithreaded process may not change user namespace with -.BR setns (). -.IP -It is not permitted to use -.BR setns () -to reenter the caller's current user namespace. -This prevents a caller that has dropped capabilities from regaining -those capabilities via a call to -.BR setns (). -.IP -For security reasons, -.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 -.\" https://lwn.net/Articles/543273/ -a process can't join a new user namespace if it is sharing -filesystem-related attributes -(the attributes whose sharing is controlled by the -.BR clone (2) -.B CLONE_FS -flag) with another process. -.IP -For further details on user namespaces, see -.BR user_namespaces (7). -.TP -Mount namespaces -Changing the mount namespace requires that the caller possess both -.B CAP_SYS_CHROOT -and -.B CAP_SYS_ADMIN -capabilities in its own user namespace and -.B CAP_SYS_ADMIN -in the user namespace that owns the target mount namespace. -.IP -A process can't join a new mount namespace if it is sharing -filesystem-related attributes -(the attributes whose sharing is controlled by the -.BR clone (2) -.B CLONE_FS -flag) with another process. -.\" Above check is in fs/namespace.c:mntns_install() [3.8 source] -.IP -See -.BR user_namespaces (7) -for details on the interaction of user namespaces and mount namespaces. -.TP -PID namespaces -In order to reassociate itself with a new PID namespace, -the caller must have the -.B CAP_SYS_ADMIN -capability both in its own user namespace and in the user namespace -that owns the target PID namespace. -.IP -Reassociating the PID namespace has somewhat different -from other namespace types. -Reassociating the calling thread with a PID namespace changes only -the PID namespace that subsequently created child processes of -the caller will be placed in; -it does not change the PID namespace of the caller itself. -.IP -Reassociating with a PID namespace is allowed only if the target -PID namespace is a descendant (child, grandchild, etc.) -of, or is the same as, the current PID namespace of the caller. -.IP -For further details on PID namespaces, see -.BR pid_namespaces (7). -.TP -Cgroup namespaces -In order to reassociate itself with a new cgroup namespace, -the caller must have the -.B CAP_SYS_ADMIN -capability both in its own user namespace and in the user namespace -that owns the target cgroup namespace. -.IP -Using -.BR setns () -to change the caller's cgroup namespace does not change -the caller's cgroup memberships. -.TP -Network, IPC, time, and UTS namespaces -In order to reassociate itself with a new network, IPC, time, or UTS namespace, -the caller must have the -.B CAP_SYS_ADMIN -capability both in its own user namespace and in the user namespace -that owns the target namespace. -.SH RETURN VALUE -On success, -.BR setns () -returns 0. -On failure, \-1 is returned and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EBADF -.I fd -is not a valid file descriptor. -.TP -.B EINVAL -.I fd -refers to a namespace whose type does not match that specified in -.IR nstype . -.TP -.B EINVAL -There is problem with reassociating -the thread with the specified namespace. -.TP -.\" See kernel/pid_namespace.c::pidns_install() [kernel 3.18 sources] -.B EINVAL -The caller tried to join an ancestor (parent, grandparent, and so on) -PID namespace. -.TP -.B EINVAL -The caller attempted to join the user namespace -in which it is already a member. -.TP -.B EINVAL -.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 -The caller shares filesystem -.RB ( CLONE_FS ) -state (in particular, the root directory) -with other processes and tried to join a new user namespace. -.TP -.B EINVAL -.\" See kernel/user_namespace.c::userns_install() [kernel 3.15 sources] -The caller is multithreaded and tried to join a new user namespace. -.TP -.B EINVAL -.I fd -is a PID file descriptor and -.I nstype -is invalid (e.g., it is 0). -.TP -.B ENOMEM -Cannot allocate sufficient memory to change the specified namespace. -.TP -.B EPERM -The calling thread did not have the required capability -for this operation. -.TP -.B ESRCH -.I fd -is a PID file descriptor but the process it refers to no longer exists -(i.e., it has terminated and been waited on). -.SH STANDARDS -Linux. -.SH VERSIONS -Linux 3.0, -glibc 2.14. -.SH NOTES -For further information on the -.IR /proc/ pid /ns/ -magic links, see -.BR namespaces (7). -.P -Not all of the attributes that can be shared when -a new thread is created using -.BR clone (2) -can be changed using -.BR setns (). -.SH EXAMPLES -The program below takes two or more arguments. -The first argument specifies the pathname of a namespace file in an existing -.IR /proc/ pid /ns/ -directory. -The remaining arguments specify a command and its arguments. -The program opens the namespace file, joins that namespace using -.BR setns (), -and executes the specified command inside that namespace. -.P -The following shell session demonstrates the use of this program -(compiled as a binary named -.IR ns_exec ) -in conjunction with the -.B CLONE_NEWUTS -example program in the -.BR clone (2) -man page (complied as a binary named -.IR newuts ). -.P -We begin by executing the example program in -.BR clone (2) -in the background. -That program creates a child in a separate UTS namespace. -The child changes the hostname in its namespace, -and then both processes display the hostnames in their UTS namespaces, -so that we can see that they are different. -.P -.in +4n -.EX -$ \fBsu\fP # Need privilege for namespace operations -Password: -# \fB./newuts bizarro &\fP -[1] 3549 -clone() returned 3550 -uts.nodename in child: bizarro -uts.nodename in parent: antero -# \fBuname \-n\fP # Verify hostname in the shell -antero -.EE -.in -.P -We then run the program shown below, -using it to execute a shell. -Inside that shell, we verify that the hostname is the one -set by the child created by the first program: -.P -.in +4n -.EX -# \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP -# \fBuname \-n\fP # Executed in shell started by ns_exec -bizarro -.EE -.in -.SS Program source -.\" SRC BEGIN (setns.c) -.EX -#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...\en", argv[0]); - exit(EXIT_FAILURE); - } -\& - /* Get file descriptor for namespace; the file descriptor is opened - with O_CLOEXEC so as to ensure that it is not inherited by the - program that is later executed. */ -\& - fd = open(argv[1], O_RDONLY | O_CLOEXEC); - if (fd == \-1) - err(EXIT_FAILURE, "open"); -\& - if (setns(fd, 0) == \-1) /* Join that namespace */ - err(EXIT_FAILURE, "setns"); -\& - execvp(argv[2], &argv[2]); /* Execute a command in namespace */ - err(EXIT_FAILURE, "execvp"); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR nsenter (1), -.BR clone (2), -.BR fork (2), -.BR unshare (2), -.BR vfork (2), -.BR namespaces (7), -.BR unix (7) |