]>
Commit | Line | Data |
---|---|---|
de0f3763 | 1 | .TH UNSHARE 1 "February 2016" "util-linux" "User Commands" |
4205f1fd | 2 | .SH NAME |
ef6acdb8 | 3 | unshare \- run program with some namespaces unshared from parent |
4205f1fd MG |
4 | .SH SYNOPSIS |
5 | .B unshare | |
cf8e0bae | 6 | [options] |
b5672517 KZ |
7 | .RI [ program |
8 | .RI [ arguments ]] | |
4205f1fd | 9 | .SH DESCRIPTION |
dde08a87 | 10 | Unshares the indicated namespaces from the parent process and then executes |
b5672517 KZ |
11 | the specified \fIprogram\fR. If \fIprogram\fR is not given, then ``${SHELL}'' is |
12 | run (default: /bin/sh). | |
0490a6ca | 13 | .PP |
de0f3763 BS |
14 | The namespaces can optionally be made persistent by bind mounting |
15 | /proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path and entered with | |
16 | .BR \%nsenter (1) | |
ca538975 KZ |
17 | even after the \fIprogram\fR terminates (except PID namespaces where |
18 | permanently running init process is required). | |
de0f3763 | 19 | Once a persistent \%namespace is no longer needed, it can be unpersisted with |
0490a6ca | 20 | .BR umount (8). |
bc281b09 | 21 | See the \fBEXAMPLE\fR section for more details. |
0490a6ca | 22 | .PP |
0d5260b6 | 23 | .B unshare |
24 | since util-linux version 2.36 uses /\fIproc/[pid]/ns/pid_for_children\fP and \fI/proc/[pid]/ns/time_for_children\fP | |
25 | files for persistent PID and TIME namespaces. This change requires Linux kernel 4.17 or newer. | |
26 | .PP | |
0490a6ca | 27 | The namespaces to be unshared are indicated via options. Unshareable namespaces are: |
4205f1fd | 28 | .TP |
0bb7e904 | 29 | .B mount namespace |
f85b9777 MK |
30 | Mounting and unmounting filesystems will not affect the rest of the system, |
31 | except for filesystems which are explicitly marked as | |
1c4c6024 BIG |
32 | shared (with \fBmount \-\-make-shared\fP; see \fI/proc/self/mountinfo\fP or |
33 | \fBfindmnt \-o+PROPAGATION\fP for the \fBshared\fP flags). | |
f85b9777 MK |
34 | For further details, see |
35 | .BR mount_namespaces (7) | |
36 | and the discussion of the | |
0bb7e904 | 37 | .B CLONE_NEWNS |
f85b9777 MK |
38 | flag in |
39 | .BR clone (2). | |
cf8e0bae | 40 | .sp |
f0f22e9c KZ |
41 | .B unshare |
42 | since util-linux version 2.27 automatically sets propagation to \fBprivate\fP | |
de0f3763 BS |
43 | in a new mount namespace to make sure that the new namespace is really |
44 | unshared. It's possible to disable this feature with option | |
45 | \fB\-\-propagation unchanged\fP. | |
f0f22e9c | 46 | Note that \fBprivate\fP is the kernel default. |
4205f1fd | 47 | .TP |
0bb7e904 | 48 | .B UTS namespace |
dde08a87 | 49 | Setting hostname or domainname will not affect the rest of the system. |
f85b9777 | 50 | For further details, see |
6b2388d3 | 51 | .BR uts_namespaces (7) |
f85b9777 | 52 | and the discussion of the |
0bb7e904 | 53 | .B CLONE_NEWUTS |
f85b9777 MK |
54 | flag in |
55 | .BR clone (2). | |
4205f1fd | 56 | .TP |
0bb7e904 | 57 | .B IPC namespace |
170a8e4a MK |
58 | The process will have an independent namespace for POSIX message queues |
59 | as well as System V \%message queues, | |
f85b9777 MK |
60 | semaphore sets and shared memory segments. |
61 | For further details, see | |
6b2388d3 | 62 | .BR ipc_namespaces (7) |
f85b9777 | 63 | and the discussion of the |
0bb7e904 | 64 | .B CLONE_NEWIPC |
f85b9777 MK |
65 | flag in |
66 | .BR clone (2). | |
4205f1fd | 67 | .TP |
0bb7e904 | 68 | .B network namespace |
dde08a87 BS |
69 | The process will have independent IPv4 and IPv6 stacks, IP routing tables, |
70 | firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees, | |
f85b9777 MK |
71 | sockets, etc. |
72 | For further details, see | |
6b2388d3 | 73 | .BR network_namespaces (7) |
f85b9777 | 74 | and the discussion of the |
0bb7e904 | 75 | .B CLONE_NEWNET |
f85b9777 MK |
76 | flag in |
77 | .BR clone (2). | |
4205f1fd | 78 | .TP |
0bb7e904 | 79 | .B PID namespace |
de0f3763 | 80 | Children will have a distinct set of PID-to-process mappings from their parent. |
f85b9777 MK |
81 | For further details, see |
82 | .BR pid_namespaces (7) | |
83 | and | |
84 | the discussion of the | |
0bb7e904 | 85 | .B CLONE_NEWPID |
f85b9777 MK |
86 | flag in |
87 | .BR clone (2). | |
bc7f9b95 | 88 | .TP |
0bb7e904 | 89 | .B cgroup namespace |
f9e7b66d SH |
90 | The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new |
91 | cgroup mounts will be rooted at the namespace cgroup root. | |
f85b9777 MK |
92 | For further details, see |
93 | .BR cgroup_namespaces (7) | |
94 | and the discussion of the | |
0bb7e904 | 95 | .B CLONE_NEWCGROUP |
f85b9777 MK |
96 | flag in |
97 | .BR clone (2). | |
f9e7b66d | 98 | .TP |
0bb7e904 | 99 | .B user namespace |
dde08a87 | 100 | The process will have a distinct set of UIDs, GIDs and capabilities. |
f85b9777 MK |
101 | For further details, see |
102 | .BR user_namespaces (7) | |
103 | and the discussion of the | |
0bb7e904 | 104 | .B CLONE_NEWUSER |
f85b9777 MK |
105 | flag in |
106 | .BR clone (2). | |
be7df01a AR |
107 | .TP |
108 | .B time namespace | |
109 | The process can have a distinct view of | |
110 | .B CLOCK_MONOTONIC | |
111 | and/or | |
112 | .B CLOCK_BOOTTIME | |
113 | which can be changed using \fI/proc/self/timens_offsets\fP. | |
c89aadb7 MK |
114 | For further details, see |
115 | .BR time_namespaces (7). | |
4205f1fd MG |
116 | .SH OPTIONS |
117 | .TP | |
de0f3763 BS |
118 | .BR \-i , " \-\-ipc" [ =\fIfile ] |
119 | Unshare the IPC namespace. If \fIfile\fP is specified, then a persistent | |
120 | namespace is created by a bind mount. | |
dde08a87 | 121 | .TP |
de0f3763 BS |
122 | .BR \-m , " \-\-mount" [ =\fIfile ] |
123 | Unshare the mount namespace. If \fIfile\fP is specified, then a persistent | |
124 | namespace is created by a bind mount. | |
125 | Note that \fIfile\fP has to be located on a filesystem with the propagation | |
1c4c6024 | 126 | flag set to \fBprivate\fP. Use the command \fBfindmnt \-o+PROPAGATION\fP |
de0f3763 | 127 | when not sure about the current setting. See also the examples below. |
4205f1fd | 128 | .TP |
de0f3763 BS |
129 | .BR \-n , " \-\-net" [ =\fIfile ] |
130 | Unshare the network namespace. If \fIfile\fP is specified, then a persistent | |
131 | namespace is created by a bind mount. | |
bc7f9b95 | 132 | .TP |
de0f3763 BS |
133 | .BR \-p , " \-\-pid" [ =\fIfile ] |
134 | Unshare the PID namespace. If \fIfile\fP is specified then persistent | |
1c4c6024 BIG |
135 | namespace is created by a bind mount. See also the \fB\-\-fork\fP and |
136 | \fB\-\-mount-proc\fP options. | |
bc7f9b95 | 137 | .TP |
de0f3763 BS |
138 | .BR \-u , " \-\-uts" [ =\fIfile ] |
139 | Unshare the UTS namespace. If \fIfile\fP is specified, then a persistent | |
140 | namespace is created by a bind mount. | |
dde08a87 | 141 | .TP |
de0f3763 BS |
142 | .BR \-U , " \-\-user" [ =\fIfile ] |
143 | Unshare the user namespace. If \fIfile\fP is specified, then a persistent | |
144 | namespace is created by a bind mount. | |
5088ec33 | 145 | .TP |
f9e7b66d SH |
146 | .BR \-C , " \-\-cgroup"[=\fIfile\fP] |
147 | Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created | |
148 | by bind mount. | |
149 | .TP | |
f218fd97 | 150 | .BR \-T , " \-\-time"[=\fIfile\fP] |
be7df01a AR |
151 | Unshare the time namespace. If \fIfile\fP is specified then a persistent |
152 | namespace is created by a bind mount. The \fB\-\-monotonic\fP and | |
153 | \fB\-\-boottime\fP options can be used to specify the corresponding | |
154 | offset in the time namespace. | |
155 | .TP | |
5088ec33 | 156 | .BR \-f , " \-\-fork" |
87ec43b6 | 157 | Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than |
de0f3763 | 158 | running it directly. This is useful when creating a new PID namespace. |
6728ca10 | 159 | .TP |
2fb684f0 | 160 | .B \-\-keep\-caps |
1c4c6024 | 161 | When the \fB\-\-user\fP option is given, ensure that capabilities granted |
cef4decf JP |
162 | in the user namespace are preserved in the child process. |
163 | .TP | |
8b39a17c NH |
164 | .BR \-\-kill\-child [ =\fIsigname ] |
165 | When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process. | |
1c4c6024 | 166 | Combined with \fB\-\-pid\fR this allows for an easy and reliable killing of the entire |
8e8f0fa5 | 167 | process tree below \fBunshare\fR. |
8b39a17c | 168 | If not given, \fIsigname\fP defaults to \fBSIGKILL\fR. |
1c4c6024 | 169 | This option implies \fB\-\-fork\fR. |
8e8f0fa5 | 170 | .TP |
de0f3763 | 171 | .BR \-\-mount\-proc [ =\fImountpoint ] |
cf8e0bae | 172 | Just before running the program, mount the proc filesystem at \fImountpoint\fP |
de0f3763 | 173 | (default is /proc). This is useful when creating a new PID namespace. It also |
6728ca10 | 174 | implies creating a new mount namespace since the /proc mount would otherwise |
cf8e0bae | 175 | mess up existing programs on the system. The new proc filesystem is explicitly |
de0f3763 | 176 | mounted as private (with MS_PRIVATE|MS_REC). |
4da21e37 | 177 | .TP |
c5178f27 | 178 | .BI \-\-map\-user= uid|name |
6e837b5a MHB |
179 | Run the program only after the current effective user ID has been mapped to \fIuid\fP. |
180 | If this option is specified multiple times, the last occurrence takes precedence. | |
181 | This option implies \fB\-\-user\fR. | |
182 | .TP | |
c5178f27 | 183 | .BI \-\-map\-group= gid|name |
6e837b5a MHB |
184 | Run the program only after the current effective group ID has been mapped to \fIgid\fP. |
185 | If this option is specified multiple times, the last occurrence takes precedence. | |
186 | This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR. | |
187 | .TP | |
b06c1ca6 | 188 | .BR \-r , " \-\-map\-root\-user" |
cf8e0bae BS |
189 | Run the program only after the current effective user and group IDs have been mapped to |
190 | the superuser UID and GID in the newly created user namespace. This makes it possible to | |
191 | conveniently gain capabilities needed to manage various aspects of the newly created | |
192 | namespaces (such as configuring interfaces in the network namespace or mounting filesystems in | |
193 | the mount namespace) even when run unprivileged. As a mere convenience feature, it does not support | |
4da21e37 | 194 | more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs. |
1c4c6024 | 195 | This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR. |
6e837b5a | 196 | This option is equivalent to \fB\-\-map-user=0 \-\-map-group=0\fR. |
4175f29e JP |
197 | .TP |
198 | .BR \-c , " \-\-map\-current\-user" | |
199 | Run the program only after the current effective user and group IDs have been mapped to | |
200 | the same UID and GID in the newly created user namespace. This option implies | |
1c4c6024 | 201 | \fB\-\-setgroups=deny\fR and \fB\-\-user\fR. |
6e837b5a | 202 | This option is equivalent to \fB\-\-map-user=$(id -ru) \-\-map-group=$(id -rg)\fR. |
fbceefde | 203 | .TP |
de0f3763 BS |
204 | .BR "\-\-propagation private" | shared | slave | unchanged |
205 | Recursively set the mount propagation flag in the new mount namespace. The default | |
206 | is to set the propagation to \fIprivate\fP. It is possible to disable this feature | |
207 | with the argument \fBunchanged\fR. The option is silently ignored when the mount | |
208 | namespace (\fB\-\-mount\fP) is not requested. | |
f0f22e9c | 209 | .TP |
de0f3763 BS |
210 | .BR "\-\-setgroups allow" | deny |
211 | Allow or deny the | |
fbceefde | 212 | .BR setgroups (2) |
3be5d977 | 213 | system call in a user namespace. |
afaf3103 BS |
214 | .sp |
215 | To be able to call | |
216 | .BR setgroups (2), | |
217 | the calling process must at least have CAP_SETGID. | |
218 | But since Linux 3.19 a further restriction applies: | |
219 | the kernel gives permission to call | |
220 | .BR \%setgroups (2) | |
221 | only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set. | |
222 | The GID map is writable by root when | |
223 | .BR \%setgroups (2) | |
eb024893 | 224 | is enabled (i.e., \fBallow\fR, the default), and |
afaf3103 BS |
225 | the GID map becomes writable by unprivileged processes when |
226 | .BR \%setgroups (2) | |
227 | is permanently disabled (with \fBdeny\fR). | |
5e43af7e | 228 | .TP |
bf8834d4 LV |
229 | .BR \-R, "\-\-root=\fIdir" |
230 | run the command with root directory set to \fIdir\fP. | |
231 | .TP | |
232 | .BR \-w, "\-\-wd=\fIdir" | |
233 | change working directory to \fIdir\fP. | |
234 | .TP | |
f0af42b5 LV |
235 | .BR \-S, "\-\-setuid \fIuid" |
236 | Set the user ID which will be used in the entered namespace. | |
237 | .TP | |
238 | .BR \-G, "\-\-setgid \fIgid" | |
239 | Set the group ID which will be used in the entered namespace and drop | |
240 | supplementary groups. | |
241 | .TP | |
c5178f27 | 242 | .BI \-\-monotonic " offset" |
be7df01a AR |
243 | Set the offset of |
244 | .B CLOCK_MONOTONIC | |
245 | which will be used in the entered time namespace. This option requires | |
246 | unsharing a time namespace with \fB\-\-time\fP. | |
247 | .TP | |
c5178f27 | 248 | .BI \-\-boottime " offset" |
be7df01a AR |
249 | Set the offset of |
250 | .B CLOCK_BOOTTIME | |
251 | which will be used in the entered time namespace. This option requires | |
252 | unsharing a time namespace with \fB\-\-time\fP. | |
253 | .TP | |
5e43af7e BS |
254 | .BR \-V , " \-\-version" |
255 | Display version information and exit. | |
256 | .TP | |
257 | .BR \-h , " \-\-help" | |
258 | Display help text and exit. | |
86b6d7f4 KZ |
259 | .SH NOTES |
260 | The proc and sysfs filesystems mounting as root in a user namespace have to be | |
261 | restricted so that a less privileged user can not get more access to sensitive | |
262 | files that a more privileged user made unavailable. In short the rule for proc | |
263 | and sysfs is as close to a bind mount as possible. | |
bc281b09 | 264 | .SH EXAMPLE |
69a7761b | 265 | .TP |
1c4c6024 | 266 | .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self |
69a7761b LR |
267 | .TQ |
268 | 1 | |
269 | .br | |
de0f3763 | 270 | Establish a PID namespace, ensure we're PID 1 in it against a newly mounted |
69a7761b LR |
271 | procfs instance. |
272 | .TP | |
1c4c6024 | 273 | .B $ unshare \-\-map-root-user \-\-user sh \-c whoami |
69a7761b LR |
274 | .TQ |
275 | root | |
276 | .br | |
277 | Establish a user namespace as an unprivileged user with a root user within it. | |
0490a6ca | 278 | .TP |
0490a6ca KZ |
279 | .B # touch /root/uts-ns |
280 | .TQ | |
1c4c6024 | 281 | .B # unshare \-\-uts=/root/uts-ns hostname FOO |
0490a6ca | 282 | .TQ |
1c4c6024 | 283 | .B # nsenter \-\-uts=/root/uts-ns hostname |
0490a6ca KZ |
284 | .TQ |
285 | FOO | |
286 | .TQ | |
287 | .B # umount /root/uts-ns | |
288 | .br | |
de0f3763 BS |
289 | Establish a persistent UTS namespace, and modify the hostname. The namespace |
290 | is then entered with \fBnsenter\fR. The namespace is destroyed by unmounting | |
291 | the bind reference. | |
249fc8fe | 292 | .TP |
1c4c6024 | 293 | .B # mount \-\-bind /root/namespaces /root/namespaces |
249fc8fe | 294 | .TQ |
1c4c6024 | 295 | .B # mount \-\-make-private /root/namespaces |
249fc8fe | 296 | .TQ |
de0f3763 | 297 | .B # touch /root/namespaces/mnt |
249fc8fe | 298 | .TQ |
1c4c6024 | 299 | .B # unshare \-\-mount=/root/namespaces/mnt |
249fc8fe KZ |
300 | .br |
301 | Establish a persistent mount namespace referenced by the bind mount | |
de0f3763 BS |
302 | /root/namespaces/mnt. This example shows a portable solution, because it |
303 | makes sure that the bind mount is created on a shared filesystem. | |
8e8f0fa5 | 304 | .TP |
1c4c6024 | 305 | .B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" & |
8e8f0fa5 NH |
306 | .TQ |
307 | .B # pid=$! | |
308 | .TQ | |
309 | .B # kill $pid | |
310 | .br | |
311 | Reliable killing of subprocesses of the \fIprogram\fR. | |
312 | When \fBunshare\fR gets killed, everything below it gets killed as well. | |
313 | Without it, the children of \fIprogram\fR would have orphaned and | |
314 | been re-parented to PID 1. | |
be7df01a AR |
315 | .TP |
316 | .B # unshare \-\-fork \-\-time \-\-boottime 100000000 uptime | |
317 | .TQ | |
318 | 10:58:48 up 1158 days, 6:05, 1 user, load average: 0.00, 0.00, 0.00 | |
249fc8fe | 319 | |
0490a6ca KZ |
320 | .SH AUTHORS |
321 | .UR dottedmag@dottedmag.net | |
322 | Mikhail Gusarov | |
323 | .UE | |
324 | .br | |
325 | .UR kzak@redhat.com | |
326 | Karel Zak | |
327 | .UE | |
ade04bb8 MK |
328 | .SH SEE ALSO |
329 | .BR clone (2), | |
330 | .BR unshare (2), | |
331 | .BR namespaces (7), | |
332 | .BR mount (8) | |
4205f1fd | 333 | .SH AVAILABILITY |
601d12fb | 334 | The unshare command is part of the util-linux package and is available from |
d673b74e | 335 | https://www.kernel.org/pub/linux/utils/util-linux/. |