]>
Commit | Line | Data |
---|---|---|
020357e8 MK |
1 | .\" Copyright (c) 2013 by Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
19 | .\" | |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" | |
24 | .TH NAMESPACES 7 2013-01-14 "Linux" "Linux Programmer's Manual" | |
25 | .SH NAME | |
26 | namespaces \- overview of Linux namespaces | |
27 | .SH DESCRIPTION | |
28 | A namespace wraps a global system resource in an abstraction that | |
29 | makes it appear to the processes within the namespace that they | |
30 | have their own isolated instance of the global resource. | |
31 | Changes to the global resource are visible to other processes | |
32 | that are members of the namespace, but are invisible to other processes. | |
33 | One use of namespaces is to implement containers. | |
34 | ||
35 | This page describes the various namespaces and the associated | |
36 | .I /proc | |
37 | files, and summarizes the APIs for working with namespaces. | |
38 | ||
39 | .SS The namespaces API | |
40 | ||
41 | As well as various | |
42 | .I /proc | |
43 | files described below, | |
44 | the namespaces API comprises the following system calls: | |
45 | ||
46 | .TP | |
47 | .BR clone (2) | |
48 | The | |
49 | .BR clone (2) | |
50 | system call creates a new process. | |
51 | If the | |
52 | .I flags | |
53 | argument of the call specifies one or more of the | |
54 | .B CLONE_NEW* | |
55 | flags listed below, then new namespaces are created for each flag, | |
56 | and the child process is made a member of those namespaces. | |
57 | (This system call also implements a number of features | |
58 | unrelated to namespaces.) | |
59 | ||
60 | .TP | |
61 | .BR setns (2) | |
62 | The | |
63 | .BR setns (2) | |
64 | system call allows the calling process to join an existing namespace. | |
65 | The namespace to join is specified via a file descriptor that refers to | |
66 | one of the | |
67 | .IR /proc/[pid]/ns | |
68 | files described below. | |
69 | ||
70 | .TP | |
71 | .BR unshare (2) | |
72 | The | |
73 | .BR unshare (2) | |
74 | system call moves the calling process to a new namespace. | |
75 | If the | |
76 | .I flags | |
77 | argument of the call specifies one or more of the | |
78 | .B CLONE_NEW* | |
79 | flags listed below, then new namespaces are created for each flag, | |
80 | and the calling process is made a member of those namespaces. | |
81 | (This system call also implements a number of features | |
82 | unrelated to namespaces.) | |
83 | ||
84 | Leaving aside the other effects of the | |
85 | .BR clone (2) | |
86 | system call, the following call: | |
87 | ||
88 | clone(..., CLONE_NEWXXX, ...); | |
89 | ||
90 | is equivalent in namespace terms to: | |
91 | ||
92 | if (fork() == 0) /* if child */ | |
93 | unshare(CLONE_NEWXXX); | |
94 | ||
020357e8 MK |
95 | .SS IPC namespaces (CLONE_NEWIPC) |
96 | ||
97 | IPC namespaces isolate certain IPC resources, | |
98 | namely, System V IPC objects (see | |
99 | .BR svipc (7)) | |
100 | and (since Linux 2.6.30) POSIX message queues (see | |
101 | .BR mq_overview (7). | |
102 | Each IPC namespace has its own set of System V IPC identifiers and | |
103 | its own POSIX message queue file system. | |
104 | ||
105 | .SS Network namespaces (CLONE_NEWNET) | |
106 | ||
107 | Network namespaces provide isolation of the system resources associated | |
108 | with networking: network devices, IP addresses, IP routing tables, | |
109 | .I /proc/net | |
110 | directory, | |
111 | .I /sys/class/net | |
112 | directory, port numbers, and so on. | |
113 | ||
357002ec MK |
114 | .SS Mount namespaces (CLONE_NEWNS) |
115 | ||
116 | Mount namespaces isolate the set of file system mount points, | |
117 | meaning that processes in different mount namespaces can | |
118 | have different views of the file system hierarchy. | |
119 | The set of mounts in a mount namespace is modified using | |
120 | .BR mount (2) | |
121 | and | |
122 | .BR umount (2). | |
123 | ||
124 | The | |
125 | .IR /proc/[pid]/mounts | |
126 | file (present since Linux 2.4.19) | |
127 | lists all the file systems currently mounted in the | |
128 | process's mount namespace. | |
129 | The format of this file is documented in | |
130 | .BR fstab (5). | |
131 | Since kernel version 2.6.15, this file is pollable: | |
132 | after opening the file for reading, a change in this file | |
133 | (i.e., a file system mount or unmount) causes | |
134 | .BR select (2) | |
135 | to mark the file descriptor as readable, and | |
136 | .BR poll (2) | |
137 | and | |
138 | .BR epoll_wait (2) | |
139 | mark the file as having an error condition. | |
140 | ||
4716a1dd MK |
141 | The |
142 | .IR /proc/[pid]/mountstats | |
143 | file (present since Linux 2.6.17) | |
144 | exports information (statistics, configuration information) | |
145 | about the mount points in the process's mount namespace. | |
146 | This file is only readable by the owner of the process. | |
147 | Lines in this file have the form: | |
148 | .RS | |
149 | .in 12 | |
150 | .nf | |
151 | ||
152 | device /dev/sda7 mounted on /home with fstype ext3 [statistics] | |
153 | ( 1 ) ( 2 ) (3 ) (4) | |
154 | .fi | |
155 | .in | |
156 | ||
157 | The fields in each line are: | |
158 | .TP 5 | |
159 | (1) | |
160 | The name of the mounted device | |
161 | (or "nodevice" if there is no corresponding device). | |
162 | .TP | |
163 | (2) | |
164 | The mount point within the file system tree. | |
165 | .TP | |
166 | (3) | |
167 | The file system type. | |
168 | .TP | |
169 | (4) | |
170 | Optional statistics and configuration information. | |
171 | Currently (as at Linux 2.6.26), only NFS file systems export | |
172 | information via this field. | |
173 | .RE | |
174 | ||
020357e8 MK |
175 | .SS PID namespaces (CLONE_NEWPID) |
176 | ||
177 | PID namespaces isolate the process ID number space, | |
178 | meaning that processes in different PID namespaces can have the same PID. | |
179 | PID namespaces allow containers to migrate to a new hosts | |
180 | while the processes inside the container maintain the same PIDs. | |
181 | Each PID namespace has its own init (PID 1, see | |
182 | .BR init (1)), | |
183 | the "ancestor of all processes" that | |
184 | manages various system initialization tasks and | |
185 | reaps orphaned child processes when they terminate. | |
186 | ||
187 | From the point of view of a particular PID namespace instance, | |
188 | a process has two PIDs: the PID inside the namespace, | |
189 | and the PID outside the namespace on the host system. | |
190 | PID namespaces can be nested: | |
191 | a process will have one PID for each of the layers of the hierarchy | |
192 | starting from the PID namespace in which it resides | |
193 | through to the root PID namespace. | |
194 | A process can see (e.g., send signals with | |
195 | .BR kill(2)) | |
196 | only processes contained in its own PID namespace | |
197 | and the namespaces nested below that PID namespace. | |
198 | ||
199 | .SS User namespaces (CLONE_NEWUSER) | |
200 | ||
201 | User namespaces isolate the user and group ID number spaces. | |
202 | In other words, a process's user and group IDs can be different | |
203 | inside and outside a user namespace. | |
204 | A process can have a normal unprivileged user ID outside a user namespace | |
205 | while at the same time having a user ID of 0 inside the namespace; | |
206 | in other words, | |
207 | the process has full privileges for operations inside the user namespace, | |
208 | but is unprivileged for operations outside the namespace. | |
209 | ||
210 | Starting in Linux 3.8, unprivileged processes can create user namespaces. | |
211 | ||
212 | .SS UTS namespaces (CLONE_NEWUTS) | |
213 | ||
214 | UTS namespaces provide isolation of two system identifiers: | |
215 | the hostname and the NIS domain name. | |
216 | These identifiers are set using | |
217 | .BR sethostname (2) | |
218 | and | |
219 | .BR setdomainname (2), | |
220 | and can be retrieved using | |
221 | .BR uname (2), | |
222 | .BR gethostname (2), | |
223 | and | |
224 | .BR getdomainname (2). | |
225 | ||
226 | .SH CONFORMING TO | |
227 | Namespaces are a Linux-specific feature. | |
228 | .SH SEE ALSO | |
229 | .BR readlink (1), | |
230 | .BR clone (2), | |
231 | .BR setns (2), | |
232 | .BR unshare (2), | |
233 | .BR proc (5), | |
234 | .BR credentials (7), | |
235 | .BR capabilities (7) |