summaryrefslogtreecommitdiffstats
path: root/man7/namespaces.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/namespaces.7')
-rw-r--r--man7/namespaces.7417
1 files changed, 0 insertions, 417 deletions
diff --git a/man7/namespaces.7 b/man7/namespaces.7
deleted file mode 100644
index 5fdca2e..0000000
--- a/man7/namespaces.7
+++ /dev/null
@@ -1,417 +0,0 @@
-'\" t
-.\" Copyright (c) 2013, 2016, 2017 by Michael Kerrisk <mtk.manpages@gmail.com>
-.\" and Copyright (c) 2012 by Eric W. Biederman <ebiederm@xmission.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.\"
-.TH namespaces 7 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-namespaces \- overview of Linux namespaces
-.SH DESCRIPTION
-A namespace wraps a global system resource in an abstraction that
-makes it appear to the processes within the namespace that they
-have their own isolated instance of the global resource.
-Changes to the global resource are visible to other processes
-that are members of the namespace, but are invisible to other processes.
-One use of namespaces is to implement containers.
-.P
-This page provides pointers to information on the various namespace types,
-describes the associated
-.I /proc
-files, and summarizes the APIs for working with namespaces.
-.\"
-.SS Namespace types
-The following table shows the namespace types available on Linux.
-The second column of the table shows the flag value that is used to specify
-the namespace type in various APIs.
-The third column identifies the manual page that provides details
-on the namespace type.
-The last column is a summary of the resources that are isolated by
-the namespace type.
-.TS
-lB lB lB lB
-l1 lB1 l1 l.
-Namespace Flag Page Isolates
-Cgroup CLONE_NEWCGROUP \fBcgroup_namespaces\fP(7) T{
-Cgroup root directory
-T}
-IPC CLONE_NEWIPC \fBipc_namespaces\fP(7) T{
-System V IPC,
-POSIX message queues
-T}
-Network CLONE_NEWNET \fBnetwork_namespaces\fP(7) T{
-Network devices,
-stacks, ports, etc.
-T}
-Mount CLONE_NEWNS \fBmount_namespaces\fP(7) Mount points
-PID CLONE_NEWPID \fBpid_namespaces\fP(7) Process IDs
-Time CLONE_NEWTIME \fBtime_namespaces\fP(7) T{
-Boot and monotonic
-clocks
-T}
-User CLONE_NEWUSER \fBuser_namespaces\fP(7) T{
-User and group IDs
-T}
-UTS CLONE_NEWUTS \fButs_namespaces\fP(7) T{
-Hostname and NIS
-domain name
-T}
-.TE
-.\"
-.\" ==================== The namespaces API ====================
-.\"
-.SS The namespaces API
-As well as various
-.I /proc
-files described below,
-the namespaces API includes the following system calls:
-.TP
-.BR clone (2)
-The
-.BR clone (2)
-system call creates a new process.
-If the
-.I flags
-argument of the call specifies one or more of the
-.B CLONE_NEW*
-flags listed above, then new namespaces are created for each flag,
-and the child process is made a member of those namespaces.
-(This system call also implements a number of features
-unrelated to namespaces.)
-.TP
-.BR setns (2)
-The
-.BR setns (2)
-system call allows the calling process to join an existing namespace.
-The namespace to join is specified via a file descriptor that refers to
-one of the
-.IR /proc/ pid /ns
-files described below.
-.TP
-.BR unshare (2)
-The
-.BR unshare (2)
-system call moves the calling process to a new namespace.
-If the
-.I flags
-argument of the call specifies one or more of the
-.B CLONE_NEW*
-flags listed above, then new namespaces are created for each flag,
-and the calling process is made a member of those namespaces.
-(This system call also implements a number of features
-unrelated to namespaces.)
-.TP
-.BR ioctl (2)
-Various
-.BR ioctl (2)
-operations can be used to discover information about namespaces.
-These operations are described in
-.BR ioctl_ns (2).
-.P
-Creation of new namespaces using
-.BR clone (2)
-and
-.BR unshare (2)
-in most cases requires the
-.B CAP_SYS_ADMIN
-capability, since, in the new namespace,
-the creator will have the power to change global resources
-that are visible to other processes that are subsequently created in,
-or join the namespace.
-User namespaces are the exception: since Linux 3.8,
-no privilege is required to create a user namespace.
-.\"
-.\" ==================== The /proc/[pid]/ns/ directory ====================
-.\"
-.SS The \fI/proc/\fPpid\fI/ns/\fP directory
-Each process has a
-.IR /proc/ pid /ns/
-.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
-subdirectory containing one entry for each namespace that
-supports being manipulated by
-.BR setns (2):
-.P
-.in +4n
-.EX
-$ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP
-total 0
-lrwxrwxrwx. cgroup \-> cgroup:[4026531835]
-lrwxrwxrwx. ipc \-> ipc:[4026531839]
-lrwxrwxrwx. mnt \-> mnt:[4026531840]
-lrwxrwxrwx. net \-> net:[4026531969]
-lrwxrwxrwx. pid \-> pid:[4026531836]
-lrwxrwxrwx. pid_for_children \-> pid:[4026531834]
-lrwxrwxrwx. time \-> time:[4026531834]
-lrwxrwxrwx. time_for_children \-> time:[4026531834]
-lrwxrwxrwx. user \-> user:[4026531837]
-lrwxrwxrwx. uts \-> uts:[4026531838]
-.EE
-.in
-.P
-Bind mounting (see
-.BR mount (2))
-one of the files in this directory
-to somewhere else in the filesystem keeps
-the corresponding namespace of the process specified by
-.I pid
-alive even if all processes currently in the namespace terminate.
-.P
-Opening one of the files in this directory
-(or a file that is bind mounted to one of these files)
-returns a file handle for
-the corresponding namespace of the process specified by
-.IR pid .
-As long as this file descriptor remains open,
-the namespace will remain alive,
-even if all processes in the namespace terminate.
-The file descriptor can be passed to
-.BR setns (2).
-.P
-In Linux 3.7 and earlier, these files were visible as hard links.
-Since Linux 3.8,
-.\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5
-they appear as symbolic links.
-If two processes are in the same namespace,
-then the device IDs and inode numbers of their
-.IR /proc/ pid /ns/ xxx
-symbolic links will be the same; an application can check this using the
-.I stat.st_dev
-.\" Eric Biederman: "I reserve the right for st_dev to be significant
-.\" when comparing namespaces."
-.\" https://lore.kernel.org/lkml/87poky5ca9.fsf@xmission.com/
-.\" Re: Documenting the ioctl interfaces to discover relationships...
-.\" Date: Mon, 12 Dec 2016 11:30:38 +1300
-and
-.I stat.st_ino
-fields returned by
-.BR stat (2).
-The content of this symbolic link is a string containing
-the namespace type and inode number as in the following example:
-.P
-.in +4n
-.EX
-$ \fBreadlink /proc/$$/ns/uts\fP
-uts:[4026531838]
-.EE
-.in
-.P
-The symbolic links in this subdirectory are as follows:
-.TP
-.IR /proc/ pid /ns/cgroup " (since Linux 4.6)"
-This file is a handle for the cgroup namespace of the process.
-.TP
-.IR /proc/ pid /ns/ipc " (since Linux 3.0)"
-This file is a handle for the IPC namespace of the process.
-.TP
-.IR /proc/ pid /ns/mnt " (since Linux 3.8)"
-.\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e
-This file is a handle for the mount namespace of the process.
-.TP
-.IR /proc/ pid /ns/net " (since Linux 3.0)"
-This file is a handle for the network namespace of the process.
-.TP
-.IR /proc/ pid /ns/pid " (since Linux 3.8)"
-.\" commit 57e8391d327609cbf12d843259c968b9e5c1838f
-This file is a handle for the PID namespace of the process.
-This handle is permanent for the lifetime of the process
-(i.e., a process's PID namespace membership never changes).
-.TP
-.IR /proc/ pid /ns/pid_for_children " (since Linux 4.12)"
-.\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08
-This file is a handle for the PID namespace of
-child processes created by this process.
-This can change as a consequence of calls to
-.BR unshare (2)
-and
-.BR setns (2)
-(see
-.BR pid_namespaces (7)),
-so the file may differ from
-.IR /proc/ pid /ns/pid .
-The symbolic link gains a value only after the first child process
-is created in the namespace.
-(Beforehand,
-.BR readlink (2)
-of the symbolic link will return an empty buffer.)
-.TP
-.IR /proc/ pid /ns/time " (since Linux 5.6)"
-This file is a handle for the time namespace of the process.
-.TP
-.IR /proc/ pid /ns/time_for_children " (since Linux 5.6)"
-This file is a handle for the time namespace of
-child processes created by this process.
-This can change as a consequence of calls to
-.BR unshare (2)
-and
-.BR setns (2)
-(see
-.BR time_namespaces (7)),
-so the file may differ from
-.IR /proc/ pid /ns/time .
-.TP
-.IR /proc/ pid /ns/user " (since Linux 3.8)"
-.\" commit cde1975bc242f3e1072bde623ef378e547b73f91
-This file is a handle for the user namespace of the process.
-.TP
-.IR /proc/ pid /ns/uts " (since Linux 3.0)"
-This file is a handle for the UTS namespace of the process.
-.P
-Permission to dereference or read
-.RB ( readlink (2))
-these symbolic links is governed by a ptrace access mode
-.B PTRACE_MODE_READ_FSCREDS
-check; see
-.BR ptrace (2).
-.\"
-.\" ==================== The /proc/sys/user directory ====================
-.\"
-.SS The \fI/proc/sys/user\fP directory
-The files in the
-.I /proc/sys/user
-directory (which is present since Linux 4.9) expose limits
-on the number of namespaces of various types that can be created.
-The files are as follows:
-.TP
-.I max_cgroup_namespaces
-The value in this file defines a per-user limit on the number of
-cgroup namespaces that may be created in the user namespace.
-.TP
-.I max_ipc_namespaces
-The value in this file defines a per-user limit on the number of
-ipc namespaces that may be created in the user namespace.
-.TP
-.I max_mnt_namespaces
-The value in this file defines a per-user limit on the number of
-mount namespaces that may be created in the user namespace.
-.TP
-.I max_net_namespaces
-The value in this file defines a per-user limit on the number of
-network namespaces that may be created in the user namespace.
-.TP
-.I max_pid_namespaces
-The value in this file defines a per-user limit on the number of
-PID namespaces that may be created in the user namespace.
-.TP
-.IR max_time_namespaces " (since Linux 5.7)"
-.\" commit eeec26d5da8248ea4e240b8795bb4364213d3247
-The value in this file defines a per-user limit on the number of
-time namespaces that may be created in the user namespace.
-.TP
-.I max_user_namespaces
-The value in this file defines a per-user limit on the number of
-user namespaces that may be created in the user namespace.
-.TP
-.I max_uts_namespaces
-The value in this file defines a per-user limit on the number of
-uts namespaces that may be created in the user namespace.
-.P
-Note the following details about these files:
-.IP \[bu] 3
-The values in these files are modifiable by privileged processes.
-.IP \[bu]
-The values exposed by these files are the limits for the user namespace
-in which the opening process resides.
-.IP \[bu]
-The limits are per-user.
-Each user in the same user namespace
-can create namespaces up to the defined limit.
-.IP \[bu]
-The limits apply to all users, including UID 0.
-.IP \[bu]
-These limits apply in addition to any other per-namespace
-limits (such as those for PID and user namespaces) that may be enforced.
-.IP \[bu]
-Upon encountering these limits,
-.BR clone (2)
-and
-.BR unshare (2)
-fail with the error
-.BR ENOSPC .
-.IP \[bu]
-For the initial user namespace,
-the default value in each of these files is half the limit on the number
-of threads that may be created
-.RI ( /proc/sys/kernel/threads\-max ).
-In all descendant user namespaces, the default value in each file is
-.BR MAXINT .
-.IP \[bu]
-When a namespace is created, the object is also accounted
-against ancestor namespaces.
-More precisely:
-.RS
-.IP \[bu] 3
-Each user namespace has a creator UID.
-.IP \[bu]
-When a namespace is created,
-it is accounted against the creator UIDs in each of the
-ancestor user namespaces,
-and the kernel ensures that the corresponding namespace limit
-for the creator UID in the ancestor namespace is not exceeded.
-.IP \[bu]
-The aforementioned point ensures that creating a new user namespace
-cannot be used as a means to escape the limits in force
-in the current user namespace.
-.RE
-.\"
-.SS Namespace lifetime
-Absent any other factors,
-a namespace is automatically torn down when the last process in
-the namespace terminates or leaves the namespace.
-However, there are a number of other factors that may pin
-a namespace into existence even though it has no member processes.
-These factors include the following:
-.IP \[bu] 3
-An open file descriptor or a bind mount exists for the corresponding
-.IR /proc/ pid /ns/*
-file.
-.IP \[bu]
-The namespace is hierarchical (i.e., a PID or user namespace),
-and has a child namespace.
-.IP \[bu]
-It is a user namespace that owns one or more nonuser namespaces.
-.IP \[bu]
-It is a PID namespace,
-and there is a process that refers to the namespace via a
-.IR /proc/ pid /ns/pid_for_children
-symbolic link.
-.IP \[bu]
-It is a time namespace,
-and there is a process that refers to the namespace via a
-.IR /proc/ pid /ns/time_for_children
-symbolic link.
-.IP \[bu]
-It is an IPC namespace, and a corresponding mount of an
-.I mqueue
-filesystem (see
-.BR mq_overview (7))
-refers to this namespace.
-.IP \[bu]
-It is a PID namespace, and a corresponding mount of a
-.BR proc (5)
-filesystem refers to this namespace.
-.SH EXAMPLES
-See
-.BR clone (2)
-and
-.BR user_namespaces (7).
-.SH SEE ALSO
-.BR nsenter (1),
-.BR readlink (1),
-.BR unshare (1),
-.BR clone (2),
-.BR ioctl_ns (2),
-.BR setns (2),
-.BR unshare (2),
-.BR proc (5),
-.BR capabilities (7),
-.BR cgroup_namespaces (7),
-.BR cgroups (7),
-.BR credentials (7),
-.BR ipc_namespaces (7),
-.BR network_namespaces (7),
-.BR pid_namespaces (7),
-.BR user_namespaces (7),
-.BR uts_namespaces (7),
-.BR lsns (8),
-.BR switch_root (8)