]>
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] |
dde08a87 | 7 | .I program |
4205f1fd MG |
8 | .RI [ arguments ] |
9 | .SH DESCRIPTION | |
dde08a87 | 10 | Unshares the indicated namespaces from the parent process and then executes |
0490a6ca KZ |
11 | the specified \fIprogram\fR. |
12 | .PP | |
de0f3763 BS |
13 | The namespaces can optionally be made persistent by bind mounting |
14 | /proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path and entered with | |
15 | .BR \%nsenter (1) | |
16 | even after the \fIprogram\fR terminates. | |
17 | Once a persistent \%namespace is no longer needed, it can be unpersisted with | |
0490a6ca | 18 | .BR umount (8). |
de0f3763 | 19 | See the \fBEXAMPLES\fR section for more details. |
0490a6ca KZ |
20 | .PP |
21 | The namespaces to be unshared are indicated via options. Unshareable namespaces are: | |
4205f1fd MG |
22 | .TP |
23 | .BR "mount namespace" | |
dde08a87 | 24 | Mounting and unmounting filesystems will not affect the rest of the system |
bc87f885 | 25 | (\fBCLONE_NEWNS\fP flag), except for filesystems which are explicitly marked as |
f0f22e9c KZ |
26 | shared (with \fBmount --make-shared\fP; see \fI/proc/self/mountinfo\fP or |
27 | \fBfindmnt -o+PROPAGATION\fP for the \fBshared\fP flags). | |
cf8e0bae | 28 | .sp |
f0f22e9c KZ |
29 | .B unshare |
30 | since util-linux version 2.27 automatically sets propagation to \fBprivate\fP | |
de0f3763 BS |
31 | in a new mount namespace to make sure that the new namespace is really |
32 | unshared. It's possible to disable this feature with option | |
33 | \fB\-\-propagation unchanged\fP. | |
f0f22e9c | 34 | Note that \fBprivate\fP is the kernel default. |
4205f1fd MG |
35 | .TP |
36 | .BR "UTS namespace" | |
dde08a87 BS |
37 | Setting hostname or domainname will not affect the rest of the system. |
38 | (\fBCLONE_NEWUTS\fP flag) | |
4205f1fd MG |
39 | .TP |
40 | .BR "IPC namespace" | |
de0f3763 | 41 | The process will have an independent namespace for System V \%message queues, |
dde08a87 | 42 | semaphore sets and shared memory segments. (\fBCLONE_NEWIPC\fP flag) |
4205f1fd MG |
43 | .TP |
44 | .BR "network namespace" | |
dde08a87 BS |
45 | The process will have independent IPv4 and IPv6 stacks, IP routing tables, |
46 | firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees, | |
47 | sockets, etc. (\fBCLONE_NEWNET\fP flag) | |
4205f1fd | 48 | .TP |
bc7f9b95 | 49 | .BR "pid namespace" |
de0f3763 | 50 | Children will have a distinct set of PID-to-process mappings from their parent. |
dde08a87 | 51 | (\fBCLONE_NEWPID\fP flag) |
bc7f9b95 | 52 | .TP |
f9e7b66d SH |
53 | .BR "cgroup namespace" |
54 | The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new | |
55 | cgroup mounts will be rooted at the namespace cgroup root. | |
56 | (\fBCLONE_NEWCGROUP\fP flag) | |
57 | .TP | |
bc7f9b95 | 58 | .BR "user namespace" |
dde08a87 BS |
59 | The process will have a distinct set of UIDs, GIDs and capabilities. |
60 | (\fBCLONE_NEWUSER\fP flag) | |
e41e0f95 | 61 | .PP |
dde08a87 | 62 | See \fBclone\fR(2) for the exact semantics of the flags. |
4205f1fd MG |
63 | .SH OPTIONS |
64 | .TP | |
de0f3763 BS |
65 | .BR \-i , " \-\-ipc" [ =\fIfile ] |
66 | Unshare the IPC namespace. If \fIfile\fP is specified, then a persistent | |
67 | namespace is created by a bind mount. | |
dde08a87 | 68 | .TP |
de0f3763 BS |
69 | .BR \-m , " \-\-mount" [ =\fIfile ] |
70 | Unshare the mount namespace. If \fIfile\fP is specified, then a persistent | |
71 | namespace is created by a bind mount. | |
72 | Note that \fIfile\fP has to be located on a filesystem with the propagation | |
73 | flag set to \fBprivate\fP. Use the command \fBfindmnt -o+PROPAGATION\fP | |
74 | when not sure about the current setting. See also the examples below. | |
4205f1fd | 75 | .TP |
de0f3763 BS |
76 | .BR \-n , " \-\-net" [ =\fIfile ] |
77 | Unshare the network namespace. If \fIfile\fP is specified, then a persistent | |
78 | namespace is created by a bind mount. | |
bc7f9b95 | 79 | .TP |
de0f3763 BS |
80 | .BR \-p , " \-\-pid" [ =\fIfile ] |
81 | Unshare the PID namespace. If \fIfile\fP is specified then persistent | |
82 | namespace is created by a bind mount. See also the \fB--fork\fP and | |
83 | \fB--mount-proc\fP options. | |
bc7f9b95 | 84 | .TP |
de0f3763 BS |
85 | .BR \-u , " \-\-uts" [ =\fIfile ] |
86 | Unshare the UTS namespace. If \fIfile\fP is specified, then a persistent | |
87 | namespace is created by a bind mount. | |
dde08a87 | 88 | .TP |
de0f3763 BS |
89 | .BR \-U , " \-\-user" [ =\fIfile ] |
90 | Unshare the user namespace. If \fIfile\fP is specified, then a persistent | |
91 | namespace is created by a bind mount. | |
5088ec33 | 92 | .TP |
f9e7b66d SH |
93 | .BR \-C , " \-\-cgroup"[=\fIfile\fP] |
94 | Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created | |
95 | by bind mount. | |
96 | .TP | |
5088ec33 | 97 | .BR \-f , " \-\-fork" |
87ec43b6 | 98 | Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than |
de0f3763 | 99 | running it directly. This is useful when creating a new PID namespace. |
6728ca10 | 100 | .TP |
de0f3763 | 101 | .BR \-\-mount\-proc [ =\fImountpoint ] |
cf8e0bae | 102 | Just before running the program, mount the proc filesystem at \fImountpoint\fP |
de0f3763 | 103 | (default is /proc). This is useful when creating a new PID namespace. It also |
6728ca10 | 104 | implies creating a new mount namespace since the /proc mount would otherwise |
cf8e0bae | 105 | mess up existing programs on the system. The new proc filesystem is explicitly |
de0f3763 | 106 | mounted as private (with MS_PRIVATE|MS_REC). |
4da21e37 | 107 | .TP |
b06c1ca6 | 108 | .BR \-r , " \-\-map\-root\-user" |
cf8e0bae BS |
109 | Run the program only after the current effective user and group IDs have been mapped to |
110 | the superuser UID and GID in the newly created user namespace. This makes it possible to | |
111 | conveniently gain capabilities needed to manage various aspects of the newly created | |
112 | namespaces (such as configuring interfaces in the network namespace or mounting filesystems in | |
113 | the mount namespace) even when run unprivileged. As a mere convenience feature, it does not support | |
4da21e37 | 114 | more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs. |
de0f3763 | 115 | This option implies \fB--setgroups=deny\fR. |
fbceefde | 116 | .TP |
de0f3763 BS |
117 | .BR "\-\-propagation private" | shared | slave | unchanged |
118 | Recursively set the mount propagation flag in the new mount namespace. The default | |
119 | is to set the propagation to \fIprivate\fP. It is possible to disable this feature | |
120 | with the argument \fBunchanged\fR. The option is silently ignored when the mount | |
121 | namespace (\fB\-\-mount\fP) is not requested. | |
f0f22e9c | 122 | .TP |
de0f3763 BS |
123 | .BR "\-\-setgroups allow" | deny |
124 | Allow or deny the | |
fbceefde | 125 | .BR setgroups (2) |
afaf3103 BS |
126 | syscall in a user namespace. |
127 | .sp | |
128 | To be able to call | |
129 | .BR setgroups (2), | |
130 | the calling process must at least have CAP_SETGID. | |
131 | But since Linux 3.19 a further restriction applies: | |
132 | the kernel gives permission to call | |
133 | .BR \%setgroups (2) | |
134 | only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set. | |
135 | The GID map is writable by root when | |
136 | .BR \%setgroups (2) | |
137 | is enabled (i.e. \fBallow\fR, the default), and | |
138 | the GID map becomes writable by unprivileged processes when | |
139 | .BR \%setgroups (2) | |
140 | is permanently disabled (with \fBdeny\fR). | |
5e43af7e BS |
141 | .TP |
142 | .BR \-V , " \-\-version" | |
143 | Display version information and exit. | |
144 | .TP | |
145 | .BR \-h , " \-\-help" | |
146 | Display help text and exit. | |
69a7761b LR |
147 | .SH EXAMPLES |
148 | .TP | |
149 | .B # unshare --fork --pid --mount-proc readlink /proc/self | |
150 | .TQ | |
151 | 1 | |
152 | .br | |
de0f3763 | 153 | Establish a PID namespace, ensure we're PID 1 in it against a newly mounted |
69a7761b LR |
154 | procfs instance. |
155 | .TP | |
156 | .B $ unshare --map-root-user --user sh -c whoami | |
157 | .TQ | |
158 | root | |
159 | .br | |
160 | Establish a user namespace as an unprivileged user with a root user within it. | |
0490a6ca | 161 | .TP |
0490a6ca KZ |
162 | .B # touch /root/uts-ns |
163 | .TQ | |
100a3ab5 | 164 | .B # unshare --uts=/root/uts-ns hostname FOO |
0490a6ca KZ |
165 | .TQ |
166 | .B # nsenter --uts=/root/uts-ns hostname | |
167 | .TQ | |
168 | FOO | |
169 | .TQ | |
170 | .B # umount /root/uts-ns | |
171 | .br | |
de0f3763 BS |
172 | Establish a persistent UTS namespace, and modify the hostname. The namespace |
173 | is then entered with \fBnsenter\fR. The namespace is destroyed by unmounting | |
174 | the bind reference. | |
249fc8fe | 175 | .TP |
249fc8fe KZ |
176 | .B # mount --bind /root/namespaces /root/namespaces |
177 | .TQ | |
de0f3763 | 178 | .B # mount --make-private /root/namespaces |
249fc8fe | 179 | .TQ |
de0f3763 | 180 | .B # touch /root/namespaces/mnt |
249fc8fe | 181 | .TQ |
99b3fb9e | 182 | .B # unshare --mount=/root/namespaces/mnt |
249fc8fe KZ |
183 | .br |
184 | Establish a persistent mount namespace referenced by the bind mount | |
de0f3763 BS |
185 | /root/namespaces/mnt. This example shows a portable solution, because it |
186 | makes sure that the bind mount is created on a shared filesystem. | |
249fc8fe | 187 | |
4205f1fd | 188 | .SH SEE ALSO |
c07f86e7 | 189 | .BR clone (2), |
f053ff1e | 190 | .BR unshare (2), |
c07f86e7 | 191 | .BR mount (8) |
0490a6ca KZ |
192 | .SH AUTHORS |
193 | .UR dottedmag@dottedmag.net | |
194 | Mikhail Gusarov | |
195 | .UE | |
196 | .br | |
197 | .UR kzak@redhat.com | |
198 | Karel Zak | |
199 | .UE | |
4205f1fd | 200 | .SH AVAILABILITY |
601d12fb KZ |
201 | The unshare command is part of the util-linux package and is available from |
202 | ftp://ftp.kernel.org/pub/linux/utils/util-linux/. |