]>
Commit | Line | Data |
---|---|---|
020357e8 | 1 | .\" Copyright (c) 2013 by Michael Kerrisk <mtk.manpages@gmail.com> |
7a30282c | 2 | .\" and Copyright (c) 2012 by Eric W. Biederman <ebiederm@xmission.com> |
020357e8 | 3 | .\" |
c228b4b4 | 4 | .\" %%%LICENSE_START(VERBATIM) |
020357e8 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
c228b4b4 | 24 | .\" %%%LICENSE_END |
020357e8 MK |
25 | .\" |
26 | .\" | |
3df541c0 | 27 | .TH NAMESPACES 7 2016-07-17 "Linux" "Linux Programmer's Manual" |
020357e8 MK |
28 | .SH NAME |
29 | namespaces \- overview of Linux namespaces | |
30 | .SH DESCRIPTION | |
31 | A namespace wraps a global system resource in an abstraction that | |
32 | makes it appear to the processes within the namespace that they | |
33 | have their own isolated instance of the global resource. | |
34 | Changes to the global resource are visible to other processes | |
35 | that are members of the namespace, but are invisible to other processes. | |
36 | One use of namespaces is to implement containers. | |
37 | ||
0b497138 | 38 | Linux provides the following namespaces: |
0b497138 MK |
39 | .TS |
40 | lB lB lB | |
41 | l lB l. | |
42 | Namespace Constant Isolates | |
d4d37f0a | 43 | Cgroup CLONE_NEWCGROUP Cgroup root directory |
b23c9a79 | 44 | IPC CLONE_NEWIPC System V IPC, POSIX message queues |
0b497138 MK |
45 | Network CLONE_NEWNET Network devices, stacks, ports, etc. |
46 | Mount CLONE_NEWNS Mount points | |
47 | PID CLONE_NEWPID Process IDs | |
48 | User CLONE_NEWUSER User and group IDs | |
49 | UTS CLONE_NEWUTS Hostname and NIS domain name | |
50 | .TE | |
51 | ||
020357e8 MK |
52 | This page describes the various namespaces and the associated |
53 | .I /proc | |
54 | files, and summarizes the APIs for working with namespaces. | |
6be09bd8 MK |
55 | .\" |
56 | .\" ==================== The namespaces API ==================== | |
57 | .\" | |
020357e8 | 58 | .SS The namespaces API |
020357e8 MK |
59 | As well as various |
60 | .I /proc | |
61 | files described below, | |
291e9237 | 62 | the namespaces API includes the following system calls: |
020357e8 MK |
63 | .TP |
64 | .BR clone (2) | |
65 | The | |
66 | .BR clone (2) | |
67 | system call creates a new process. | |
68 | If the | |
69 | .I flags | |
70 | argument of the call specifies one or more of the | |
71 | .B CLONE_NEW* | |
72 | flags listed below, then new namespaces are created for each flag, | |
73 | and the child process is made a member of those namespaces. | |
74 | (This system call also implements a number of features | |
75 | unrelated to namespaces.) | |
020357e8 MK |
76 | .TP |
77 | .BR setns (2) | |
78 | The | |
79 | .BR setns (2) | |
80 | system call allows the calling process to join an existing namespace. | |
81 | The namespace to join is specified via a file descriptor that refers to | |
82 | one of the | |
83 | .IR /proc/[pid]/ns | |
84 | files described below. | |
020357e8 MK |
85 | .TP |
86 | .BR unshare (2) | |
87 | The | |
88 | .BR unshare (2) | |
89 | system call moves the calling process to a new namespace. | |
90 | If the | |
91 | .I flags | |
92 | argument of the call specifies one or more of the | |
93 | .B CLONE_NEW* | |
94 | flags listed below, then new namespaces are created for each flag, | |
95 | and the calling process is made a member of those namespaces. | |
96 | (This system call also implements a number of features | |
97 | unrelated to namespaces.) | |
3c7103af | 98 | .PP |
027a0716 MK |
99 | Creation of new namespaces using |
100 | .BR clone (2) | |
101 | and | |
102 | .BR unshare (2) | |
103 | in most cases requires the | |
104 | .BR CAP_SYS_ADMIN | |
105 | capability. | |
106 | User namespaces are the exception: since Linux 3.8, | |
2a4cbd77 | 107 | no privilege is required to create a user namespace. |
6be09bd8 MK |
108 | .\" |
109 | .\" ==================== The /proc/[pid]/ns/ directory ==================== | |
110 | .\" | |
cf8bfe6d | 111 | .SS The /proc/[pid]/ns/ directory |
f5d401dd | 112 | Each process has a |
cf8bfe6d MK |
113 | .IR /proc/[pid]/ns/ |
114 | .\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f | |
115 | subdirectory containing one entry for each namespace that | |
116 | supports being manipulated by | |
f2752f90 MK |
117 | .BR setns (2): |
118 | ||
119 | .in +4n | |
120 | .nf | |
121 | $ \fBls -l /proc/$$/ns\fP | |
122 | total 0 | |
d4d37f0a MK |
123 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 cgroup -> cgroup:[4026531835] |
124 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 ipc -> ipc:[4026531839] | |
125 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 mnt -> mnt:[4026531840] | |
126 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 net -> net:[4026531969] | |
127 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 pid -> pid:[4026531836] | |
128 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 user -> user:[4026531837] | |
129 | lrwxrwxrwx. 1 mtk mtk 0 Apr 28 12:46 uts -> uts:[4026531838] | |
f2752f90 MK |
130 | .fi |
131 | .in | |
cf8bfe6d MK |
132 | |
133 | Bind mounting (see | |
134 | .BR mount (2)) | |
135 | one of the files in this directory | |
ab3311aa | 136 | to somewhere else in the filesystem keeps |
cf8bfe6d MK |
137 | the corresponding namespace of the process specified by |
138 | .I pid | |
139 | alive even if all processes currently in the namespace terminate. | |
140 | ||
141 | Opening one of the files in this directory | |
142 | (or a file that is bind mounted to one of these files) | |
143 | returns a file handle for | |
144 | the corresponding namespace of the process specified by | |
145 | .IR pid . | |
146 | As long as this file descriptor remains open, | |
147 | the namespace will remain alive, | |
148 | even if all processes in the namespace terminate. | |
149 | The file descriptor can be passed to | |
150 | .BR setns (2). | |
151 | ||
152 | In Linux 3.7 and earlier, these files were visible as hard links. | |
1dc3d91d MK |
153 | Since Linux 3.8, |
154 | .\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 | |
155 | they appear as symbolic links. | |
cf8bfe6d MK |
156 | If two processes are in the same namespace, then the inode numbers of their |
157 | .IR /proc/[pid]/ns/xxx | |
158 | symbolic links will be the same; an application can check this using the | |
159 | .I stat.st_ino | |
160 | field returned by | |
161 | .BR stat (2). | |
162 | The content of this symbolic link is a string containing | |
163 | the namespace type and inode number as in the following example: | |
164 | ||
165 | .in +4n | |
166 | .nf | |
167 | $ \fBreadlink /proc/$$/ns/uts\fP | |
168 | uts:[4026531838] | |
169 | .fi | |
170 | .in | |
171 | ||
7575dbc5 | 172 | The symbolic links in this subdirectory are as follows: |
cf8bfe6d | 173 | .TP |
d4d37f0a MK |
174 | .IR /proc/[pid]/ns/cgroup " (since Linux 4.6)" |
175 | This file is a handle for the cgroup namespace of the process. | |
176 | .TP | |
cf8bfe6d MK |
177 | .IR /proc/[pid]/ns/ipc " (since Linux 3.0)" |
178 | This file is a handle for the IPC namespace of the process. | |
cf8bfe6d MK |
179 | .TP |
180 | .IR /proc/[pid]/ns/mnt " (since Linux 3.8)" | |
7eb8372d | 181 | .\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e |
cf8bfe6d | 182 | This file is a handle for the mount namespace of the process. |
cf8bfe6d MK |
183 | .TP |
184 | .IR /proc/[pid]/ns/net " (since Linux 3.0)" | |
185 | This file is a handle for the network namespace of the process. | |
cf8bfe6d MK |
186 | .TP |
187 | .IR /proc/[pid]/ns/pid " (since Linux 3.8)" | |
7eb8372d | 188 | .\" commit 57e8391d327609cbf12d843259c968b9e5c1838f |
cf8bfe6d | 189 | This file is a handle for the PID namespace of the process. |
cf8bfe6d MK |
190 | .TP |
191 | .IR /proc/[pid]/ns/user " (since Linux 3.8)" | |
7eb8372d | 192 | .\" commit cde1975bc242f3e1072bde623ef378e547b73f91 |
cf8bfe6d | 193 | This file is a handle for the user namespace of the process. |
cf8bfe6d MK |
194 | .TP |
195 | .IR /proc/[pid]/ns/uts " (since Linux 3.0)" | |
258e6b6c | 196 | This file is a handle for the UTS namespace of the process. |
33a1ab5d MK |
197 | .PP |
198 | Permission to dereference or read | |
199 | .RB ( readlink (2)) | |
200 | these symbolic links is governed by a ptrace access mode | |
201 | .B PTRACE_MODE_READ_FSCREDS | |
202 | check; see | |
203 | .BR ptrace (2). | |
6be09bd8 | 204 | .\" |
d4d37f0a MK |
205 | .\" ==================== Cgroup namespaces ==================== |
206 | .\" | |
207 | .SS Cgroup namespaces (CLONE_NEWCGROUP) | |
a2ee61a3 MK |
208 | See |
209 | .BR cgroup_namespaces (7). | |
d4d37f0a | 210 | .\" |
6be09bd8 MK |
211 | .\" ==================== IPC namespaces ==================== |
212 | .\" | |
020357e8 | 213 | .SS IPC namespaces (CLONE_NEWIPC) |
020357e8 MK |
214 | IPC namespaces isolate certain IPC resources, |
215 | namely, System V IPC objects (see | |
216 | .BR svipc (7)) | |
9343f8e7 MK |
217 | and (since Linux 2.6.30) |
218 | .\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f | |
219 | .\" https://lwn.net/Articles/312232/ | |
220 | POSIX message queues (see | |
f7611a00 | 221 | .BR mq_overview (7)). |
9343f8e7 | 222 | The common characteristic of these IPC mechanisms is that IPC |
ab3311aa | 223 | objects are identified by mechanisms other than filesystem |
9343f8e7 MK |
224 | pathnames. |
225 | ||
020357e8 | 226 | Each IPC namespace has its own set of System V IPC identifiers and |
ab3311aa | 227 | its own POSIX message queue filesystem. |
9343f8e7 MK |
228 | Objects created in an IPC namespace are visible to all other processes |
229 | that are members of that namespace, | |
230 | but are not visible to processes in other IPC namespaces. | |
231 | ||
f344e055 MK |
232 | The following |
233 | .I /proc | |
234 | interfaces are distinct in each IPC namespace: | |
235 | .IP * 3 | |
236 | The POSIX message queue interfaces in | |
237 | .IR /proc/sys/fs/mqueue . | |
238 | .IP * | |
beb9df9e | 239 | The System V IPC interfaces in |
f344e055 MK |
240 | .IR /proc/sys/kernel , |
241 | namely: | |
242 | .IR msgmax , | |
243 | .IR msgmnb , | |
244 | .IR msgmni , | |
245 | .IR sem , | |
246 | .IR shmall , | |
247 | .IR shmmax , | |
248 | .IR shmmni , | |
249 | and | |
250 | .IR shm_rmid_forced . | |
251 | .IP * | |
beb9df9e | 252 | The System V IPC interfaces in |
f344e055 MK |
253 | .IR /proc/sysvipc . |
254 | .PP | |
9343f8e7 MK |
255 | When an IPC namespace is destroyed |
256 | (i.e., when the last process that is a member of the namespace terminates), | |
257 | all IPC objects in the namespace are automatically destroyed. | |
258 | ||
259 | Use of IPC namespaces requires a kernel that is configured with the | |
260 | .B CONFIG_IPC_NS | |
261 | option. | |
6be09bd8 MK |
262 | .\" |
263 | .\" ==================== Network namespaces ==================== | |
264 | .\" | |
020357e8 | 265 | .SS Network namespaces (CLONE_NEWNET) |
020357e8 | 266 | Network namespaces provide isolation of the system resources associated |
7d8d64eb MK |
267 | with networking: network devices, IPv4 and IPv6 protocol stacks, |
268 | IP routing tables, firewalls, the | |
020357e8 | 269 | .I /proc/net |
f5d401dd MK |
270 | directory, the |
271 | .I /sys/class/net | |
c6d54e1f | 272 | directory, port numbers (sockets), and so on. |
73680728 MK |
273 | A physical network device can live in exactly one |
274 | network namespace. | |
275 | A virtual network device ("veth") pair provides a pipe-like abstraction | |
b237b37c | 276 | .\" FIXME . Add pointer to veth(4) page when it is eventually completed |
73680728 MK |
277 | that can be used to create tunnels between network namespaces, |
278 | and can be used to create a bridge to a physical network device | |
279 | in another namespace. | |
280 | ||
281 | When a network namespace is freed | |
282 | (i.e., when the last process in the namespace terminates), | |
283 | its physical network devices are moved back to the | |
284 | initial network namespace (not to the parent of the process). | |
285 | ||
286 | Use of network namespaces requires a kernel that is configured with the | |
287 | .B CONFIG_NET_NS | |
288 | option. | |
6be09bd8 MK |
289 | .\" |
290 | .\" ==================== Mount namespaces ==================== | |
291 | .\" | |
357002ec | 292 | .SS Mount namespaces (CLONE_NEWNS) |
da031af1 MK |
293 | See |
294 | .BR mount_namespaces (7). | |
6be09bd8 MK |
295 | .\" |
296 | .\" ==================== PID namespaces ==================== | |
297 | .\" | |
020357e8 | 298 | .SS PID namespaces (CLONE_NEWPID) |
024d6a84 MK |
299 | See |
300 | .BR pid_namespaces (7). | |
6be09bd8 MK |
301 | .\" |
302 | .\" ==================== User namespaces ==================== | |
303 | .\" | |
020357e8 | 304 | .SS User namespaces (CLONE_NEWUSER) |
67d1131f MK |
305 | See |
306 | .BR user_namespaces (7). | |
6be09bd8 MK |
307 | .\" |
308 | .\" ==================== UTS namespaces ==================== | |
309 | .\" | |
020357e8 | 310 | .SS UTS namespaces (CLONE_NEWUTS) |
020357e8 MK |
311 | UTS namespaces provide isolation of two system identifiers: |
312 | the hostname and the NIS domain name. | |
313 | These identifiers are set using | |
314 | .BR sethostname (2) | |
315 | and | |
316 | .BR setdomainname (2), | |
317 | and can be retrieved using | |
318 | .BR uname (2), | |
319 | .BR gethostname (2), | |
320 | and | |
321 | .BR getdomainname (2). | |
322 | ||
83d9e9b2 MK |
323 | Use of UTS namespaces requires a kernel that is configured with the |
324 | .B CONFIG_UTS_NS | |
325 | option. | |
020357e8 MK |
326 | .SH CONFORMING TO |
327 | Namespaces are a Linux-specific feature. | |
fa88d1a4 MK |
328 | .SH EXAMPLE |
329 | See | |
330 | .BR user_namespaces (7). | |
020357e8 | 331 | .SH SEE ALSO |
86499a6b | 332 | .BR nsenter (1), |
020357e8 | 333 | .BR readlink (1), |
86499a6b | 334 | .BR unshare (1), |
020357e8 MK |
335 | .BR clone (2), |
336 | .BR setns (2), | |
337 | .BR unshare (2), | |
338 | .BR proc (5), | |
029ae9e3 | 339 | .BR capabilities (7), |
a2ee61a3 | 340 | .BR cgroup_namespaces (7), |
35fae0aa | 341 | .BR cgroups (7), |
10f8f8cb | 342 | .BR credentials (7), |
024d6a84 | 343 | .BR pid_namespaces (7), |
67d1131f | 344 | .BR user_namespaces (7), |
8512495a | 345 | .BR lsns (8), |
029ae9e3 | 346 | .BR switch_root (8) |