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