{ "content": [ { "type": "text", "text": "# namespaces (man)\n\n## NAME\n\nnamespaces - overview of Linux namespaces\n\n## DESCRIPTION\n\nA namespace wraps a global system resource in an abstraction that makes it appear to the pro‐\ncesses within the namespace that they have their own isolated instance of the global re‐\nsource. Changes to the global resource are visible to other processes that are members of\nthe namespace, but are invisible to other processes. One use of namespaces is to implement\ncontainers.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (6 subsections)\n- **EXAMPLES**\n- **SEE ALSO**\n- **COLOPHON**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "namespaces", "section": "", "mode": "man", "summary": "namespaces - overview of Linux namespaces", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "See clone(2) and usernamespaces(7)." ], "see_also": [ { "name": "nsenter", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/nsenter/1/json" }, { "name": "readlink", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/readlink/1/json" }, { "name": "unshare", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/unshare/1/json" }, { "name": "clone", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/clone/2/json" }, { "name": "ioctlns", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/ioctlns/2/json" }, { "name": "setns", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/setns/2/json" }, { "name": "unshare", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/unshare/2/json" }, { "name": "proc", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/proc/5/json" }, { "name": "capabilities", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/capabilities/7/json" }, { "name": "cgroupnamespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/cgroupnamespaces/7/json" }, { "name": "cgroups", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/cgroups/7/json" }, { "name": "credentials", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/credentials/7/json" }, { "name": "ipcnamespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ipcnamespaces/7/json" }, { "name": "worknamespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/worknamespaces/7/json" }, { "name": "pidnamespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/pidnamespaces/7/json" }, { "name": "usernamespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/usernamespaces/7/json" }, { "name": "utsnamespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/utsnamespaces/7/json" }, { "name": "lsns", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lsns/8/json" }, { "name": "pamnamespace", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/pamnamespace/8/json" }, { "name": "switchroot", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/switchroot/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 9, "subsections": [ { "name": "Namespace types", "lines": 5 }, { "name": "Namespace Flag Page Isolates", "lines": 13 }, { "name": "The namespaces API", "lines": 31 }, { "name": "The /proc/[pid]/ns/ directory", "lines": 78 }, { "name": "The /proc/sys/user directory", "lines": 68 }, { "name": "Namespace lifetime", "lines": 24 } ] }, { "name": "EXAMPLES", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "namespaces - overview of Linux namespaces\n", "subsections": [] }, "DESCRIPTION": { "content": "A namespace wraps a global system resource in an abstraction that makes it appear to the pro‐\ncesses within the namespace that they have their own isolated instance of the global re‐\nsource. Changes to the global resource are visible to other processes that are members of\nthe namespace, but are invisible to other processes. One use of namespaces is to implement\ncontainers.\n\nThis page provides pointers to information on the various namespace types, describes the as‐\nsociated /proc files, and summarizes the APIs for working with namespaces.\n", "subsections": [ { "name": "Namespace types", "content": "The following table shows the namespace types available on Linux. The second column of the\ntable shows the flag value that is used to specify the namespace type in various APIs. The\nthird column identifies the manual page that provides details on the namespace type. The\nlast column is a summary of the resources that are isolated by the namespace type.\n" }, { "name": "Namespace Flag Page Isolates", "content": "Cgroup CLONENEWCGROUP cgroupnamespaces(7) Cgroup root directory\nIPC CLONENEWIPC ipcnamespaces(7) System V IPC,\nPOSIX message queues\nNetwork CLONENEWNET networknamespaces(7) Network devices,\nstacks, ports, etc.\nMount CLONENEWNS mountnamespaces(7) Mount points\nPID CLONENEWPID pidnamespaces(7) Process IDs\nTime CLONENEWTIME timenamespaces(7) Boot and monotonic\nclocks\nUser CLONENEWUSER usernamespaces(7) User and group IDs\nUTS CLONENEWUTS utsnamespaces(7) Hostname and NIS\ndomain name\n" }, { "name": "The namespaces API", "content": "As well as various /proc files described below, the namespaces API includes the following\nsystem calls:\n\nclone(2)\nThe clone(2) system call creates a new process. If the flags argument of the call\nspecifies one or more of the CLONENEW* flags listed below, then new namespaces are\ncreated for each flag, and the child process is made a member of those namespaces.\n(This system call also implements a number of features unrelated to namespaces.)\n\nsetns(2)\nThe setns(2) system call allows the calling process to join an existing namespace.\nThe namespace to join is specified via a file descriptor that refers to one of the\n/proc/[pid]/ns files described below.\n\nunshare(2)\nThe unshare(2) system call moves the calling process to a new namespace. If the flags\nargument of the call specifies one or more of the CLONENEW* flags listed below, then\nnew namespaces are created for each flag, and the calling process is made a member of\nthose namespaces. (This system call also implements a number of features unrelated to\nnamespaces.)\n\nioctl(2)\nVarious ioctl(2) operations can be used to discover information about namespaces.\nThese operations are described in ioctlns(2).\n\nCreation of new namespaces using clone(2) and unshare(2) in most cases requires the\nCAPSYSADMIN capability, since, in the new namespace, the creator will have the power to\nchange global resources that are visible to other processes that are subsequently created in,\nor join the namespace. User namespaces are the exception: since Linux 3.8, no privilege is\nrequired to create a user namespace.\n" }, { "name": "The /proc/[pid]/ns/ directory", "content": "Each process has a /proc/[pid]/ns/ subdirectory containing one entry for each namespace that\nsupports being manipulated by setns(2):\n\n$ ls -l /proc/$$/ns | awk '{print $1, $9, $10, $11}'\ntotal 0\nlrwxrwxrwx. cgroup -> cgroup:[4026531835]\nlrwxrwxrwx. ipc -> ipc:[4026531839]\nlrwxrwxrwx. mnt -> mnt:[4026531840]\nlrwxrwxrwx. net -> net:[4026531969]\nlrwxrwxrwx. pid -> pid:[4026531836]\nlrwxrwxrwx. pidforchildren -> pid:[4026531834]\nlrwxrwxrwx. time -> time:[4026531834]\nlrwxrwxrwx. timeforchildren -> time:[4026531834]\nlrwxrwxrwx. user -> user:[4026531837]\nlrwxrwxrwx. uts -> uts:[4026531838]\n\nBind mounting (see mount(2)) one of the files in this directory to somewhere else in the\nfilesystem keeps the corresponding namespace of the process specified by pid alive even if\nall processes currently in the namespace terminate.\n\nOpening one of the files in this directory (or a file that is bind mounted to one of these\nfiles) returns a file handle for the corresponding namespace of the process specified by pid.\nAs long as this file descriptor remains open, the namespace will remain alive, even if all\nprocesses in the namespace terminate. The file descriptor can be passed to setns(2).\n\nIn Linux 3.7 and earlier, these files were visible as hard links. Since Linux 3.8, they ap‐\npear as symbolic links. If two processes are in the same namespace, then the device IDs and\ninode numbers of their /proc/[pid]/ns/xxx symbolic links will be the same; an application can\ncheck this using the stat.stdev and stat.stino fields returned by stat(2). The content of\nthis symbolic link is a string containing the namespace type and inode number as in the fol‐\nlowing example:\n\n$ readlink /proc/$$/ns/uts\nuts:[4026531838]\n\nThe symbolic links in this subdirectory are as follows:\n\n/proc/[pid]/ns/cgroup (since Linux 4.6)\nThis file is a handle for the cgroup namespace of the process.\n\n/proc/[pid]/ns/ipc (since Linux 3.0)\nThis file is a handle for the IPC namespace of the process.\n\n/proc/[pid]/ns/mnt (since Linux 3.8)\nThis file is a handle for the mount namespace of the process.\n\n/proc/[pid]/ns/net (since Linux 3.0)\nThis file is a handle for the network namespace of the process.\n\n/proc/[pid]/ns/pid (since Linux 3.8)\nThis file is a handle for the PID namespace of the process. This handle is permanent\nfor the lifetime of the process (i.e., a process's PID namespace membership never\nchanges).\n\n/proc/[pid]/ns/pidforchildren (since Linux 4.12)\nThis file is a handle for the PID namespace of child processes created by this\nprocess. This can change as a consequence of calls to unshare(2) and setns(2) (see\npidnamespaces(7)), so the file may differ from /proc/[pid]/ns/pid. The symbolic link\ngains a value only after the first child process is created in the namespace. (Be‐\nforehand, readlink(2) of the symbolic link will return an empty buffer.)\n\n/proc/[pid]/ns/time (since Linux 5.6)\nThis file is a handle for the time namespace of the process.\n\n/proc/[pid]/ns/timeforchildren (since Linux 5.6)\nThis file is a handle for the time namespace of child processes created by this\nprocess. This can change as a consequence of calls to unshare(2) and setns(2) (see\ntimenamespaces(7)), so the file may differ from /proc/[pid]/ns/time.\n\n/proc/[pid]/ns/user (since Linux 3.8)\nThis file is a handle for the user namespace of the process.\n\n/proc/[pid]/ns/uts (since Linux 3.0)\nThis file is a handle for the UTS namespace of the process.\n\nPermission to dereference or read (readlink(2)) these symbolic links is governed by a ptrace\naccess mode PTRACEMODEREADFSCREDS check; see ptrace(2).\n" }, { "name": "The /proc/sys/user directory", "content": "The files in the /proc/sys/user directory (which is present since Linux 4.9) expose limits on\nthe number of namespaces of various types that can be created. The files are as follows:\n\nmaxcgroupnamespaces\nThe value in this file defines a per-user limit on the number of cgroup namespaces\nthat may be created in the user namespace.\n\nmaxipcnamespaces\nThe value in this file defines a per-user limit on the number of ipc namespaces that\nmay be created in the user namespace.\n\nmaxmntnamespaces\nThe value in this file defines a per-user limit on the number of mount namespaces that\nmay be created in the user namespace.\n\nmaxnetnamespaces\nThe value in this file defines a per-user limit on the number of network namespaces\nthat may be created in the user namespace.\n\nmaxpidnamespaces\nThe value in this file defines a per-user limit on the number of PID namespaces that\nmay be created in the user namespace.\n\nmaxtimenamespaces (since Linux 5.7)\nThe value in this file defines a per-user limit on the number of time namespaces that\nmay be created in the user namespace.\n\nmaxusernamespaces\nThe value in this file defines a per-user limit on the number of user namespaces that\nmay be created in the user namespace.\n\nmaxutsnamespaces\nThe value in this file defines a per-user limit on the number of uts namespaces that\nmay be created in the user namespace.\n\nNote the following details about these files:\n\n* The values in these files are modifiable by privileged processes.\n\n* The values exposed by these files are the limits for the user namespace in which the open‐\ning process resides.\n\n* The limits are per-user. Each user in the same user namespace can create namespaces up to\nthe defined limit.\n\n* The limits apply to all users, including UID 0.\n\n* These limits apply in addition to any other per-namespace limits (such as those for PID\nand user namespaces) that may be enforced.\n\n* Upon encountering these limits, clone(2) and unshare(2) fail with the error ENOSPC.\n\n* For the initial user namespace, the default value in each of these files is half the limit\non the number of threads that may be created (/proc/sys/kernel/threads-max). In all de‐\nscendant user namespaces, the default value in each file is MAXINT.\n\n* When a namespace is created, the object is also accounted against ancestor namespaces.\nMore precisely:\n\n+ Each user namespace has a creator UID.\n\n+ When a namespace is created, it is accounted against the creator UIDs in each of the\nancestor user namespaces, and the kernel ensures that the corresponding namespace limit\nfor the creator UID in the ancestor namespace is not exceeded.\n\n+ The aforementioned point ensures that creating a new user namespace cannot be used as a\nmeans to escape the limits in force in the current user namespace.\n" }, { "name": "Namespace lifetime", "content": "Absent any other factors, a namespace is automatically torn down when the last process in the\nnamespace terminates or leaves the namespace. However, there are a number of other factors\nthat may pin a namespace into existence even though it has no member processes. These fac‐\ntors include the following:\n\n* An open file descriptor or a bind mount exists for the corresponding /proc/[pid]/ns/*\nfile.\n\n* The namespace is hierarchical (i.e., a PID or user namespace), and has a child namespace.\n\n* It is a user namespace that owns one or more nonuser namespaces.\n\n* It is a PID namespace, and there is a process that refers to the namespace via a\n/proc/[pid]/ns/pidforchildren symbolic link.\n\n* It is a time namespace, and there is a process that refers to the namespace via a\n/proc/[pid]/ns/timeforchildren symbolic link.\n\n* It is an IPC namespace, and a corresponding mount of an mqueue filesystem (see mqover‐‐\nview(7)) refers to this namespace.\n\n* It is a PID namespace, and a corresponding mount of a proc(5) filesystem refers to this\nnamespace.\n" } ] }, "EXAMPLES": { "content": "See clone(2) and usernamespaces(7).\n", "subsections": [] }, "SEE ALSO": { "content": "nsenter(1), readlink(1), unshare(1), clone(2), ioctlns(2), setns(2), unshare(2), proc(5),\ncapabilities(7), cgroupnamespaces(7), cgroups(7), credentials(7), ipcnamespaces(7), net‐‐\nworknamespaces(7), pidnamespaces(7), usernamespaces(7), utsnamespaces(7), lsns(8),\npamnamespace(8), switchroot(8)\n", "subsections": [] }, "COLOPHON": { "content": "This page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2020-11-01 NAMESPACES(7)", "subsections": [] } } } }