File: unshare.1

package info (click to toggle)
util-linux 2.34-0.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 46,508 kB
  • sloc: ansic: 129,594; sh: 15,590; yacc: 1,170; makefile: 397; xml: 369; python: 316; csh: 37; sed: 16; perl: 15
file content (279 lines) | stat: -rw-r--r-- 9,460 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
.TH UNSHARE 1 "February 2016" "util-linux" "User Commands"
.SH NAME
unshare \- run program with some namespaces unshared from parent
.SH SYNOPSIS
.B unshare
[options]
.RI [ program
.RI [ arguments ]]
.SH DESCRIPTION
Unshares the indicated namespaces from the parent process and then executes
the specified \fIprogram\fR. If \fIprogram\fR is not given, then ``${SHELL}'' is
run (default: /bin/sh).
.PP
The namespaces can optionally be made persistent by bind mounting
/proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path and entered with
.BR \%nsenter (1)
even after the \fIprogram\fR terminates (except PID namespaces where
permanently running init process is required).
Once a persistent \%namespace is no longer needed, it can be unpersisted with
.BR umount (8).
See the \fBEXAMPLES\fR section for more details.
.PP
The namespaces to be unshared are indicated via options.  Unshareable namespaces are:
.TP
.B mount namespace
Mounting and unmounting filesystems will not affect the rest of the system,
except for filesystems which are explicitly marked as
shared (with \fBmount --make-shared\fP; see \fI/proc/self/mountinfo\fP or
\fBfindmnt -o+PROPAGATION\fP for the \fBshared\fP flags).
For further details, see
.BR mount_namespaces (7)
and the discussion of the
.B CLONE_NEWNS
flag in
.BR clone (2).
.sp
.B unshare
since util-linux version 2.27 automatically sets propagation to \fBprivate\fP
in a new mount namespace to make sure that the new namespace is really
unshared.  It's possible to disable this feature with option
\fB\-\-propagation unchanged\fP.
Note that \fBprivate\fP is the kernel default.
.TP
.B UTS namespace
Setting hostname or domainname will not affect the rest of the system.
For further details, see
.BR namespaces (7)
and the discussion of the
.B CLONE_NEWUTS
flag in
.BR clone (2).
.TP
.B IPC namespace
The process will have an independent namespace for POSIX message queues
as well as System V \%message queues,
semaphore sets and shared memory segments.
For further details, see
.BR namespaces (7)
and the discussion of the
.B CLONE_NEWIPC
flag in
.BR clone (2).
.TP
.B network namespace
The process will have independent IPv4 and IPv6 stacks, IP routing tables,
firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
sockets, etc.
For further details, see
.BR namespaces (7)
and the discussion of the
.B CLONE_NEWNET
flag in
.BR clone (2).
.TP
.B PID namespace
Children will have a distinct set of PID-to-process mappings from their parent.
For further details, see
.BR pid_namespaces (7)
and
the discussion of the
.B CLONE_NEWPID
flag in
.BR clone (2).
.TP
.B cgroup namespace
The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new
cgroup mounts will be rooted at the namespace cgroup root.
For further details, see
.BR cgroup_namespaces (7)
and the discussion of the
.B CLONE_NEWCGROUP
flag in
.BR clone (2).
.TP
.B user namespace
The process will have a distinct set of UIDs, GIDs and capabilities.
For further details, see
.BR user_namespaces (7)
and the discussion of the
.B CLONE_NEWUSER
flag in
.BR clone (2).
.SH OPTIONS
.TP
.BR \-i , " \-\-ipc" [ =\fIfile ]
Unshare the IPC namespace.  If \fIfile\fP is specified, then a persistent
namespace is created by a bind mount.
.TP
.BR \-m , " \-\-mount" [ =\fIfile ]
Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
namespace is created by a bind mount.
Note that \fIfile\fP has to be located on a filesystem with the propagation
flag set to \fBprivate\fP.  Use the command \fBfindmnt -o+PROPAGATION\fP
when not sure about the current setting.  See also the examples below.
.TP
.BR \-n , " \-\-net" [ =\fIfile ]
Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
namespace is created by a bind mount.
.TP
.BR \-p , " \-\-pid" [ =\fIfile ]
Unshare the PID namespace.  If \fIfile\fP is specified then persistent
namespace is created by a bind mount.  See also the \fB--fork\fP and
\fB--mount-proc\fP options.
.TP
.BR \-u , " \-\-uts" [ =\fIfile ]
Unshare the UTS namespace.  If \fIfile\fP is specified, then a persistent
namespace is created by a bind mount.
.TP
.BR \-U , " \-\-user" [ =\fIfile ]
Unshare the user namespace.  If \fIfile\fP is specified, then a persistent
namespace is created by a bind mount.
.TP
.BR \-C , " \-\-cgroup"[=\fIfile\fP]
Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created
by bind mount.
.TP
.BR \-f , " \-\-fork"
Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
running it directly.  This is useful when creating a new PID namespace.
.TP
.BR \-\-kill\-child [ =\fIsigname ]
When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process.
Combined with \fB--pid\fR this allows for an easy and reliable killing of the entire
process tree below \fBunshare\fR.
If not given, \fIsigname\fP defaults to \fBSIGKILL\fR.
This option implies \fB--fork\fR.
.TP
.BR \-\-mount\-proc [ =\fImountpoint ]
Just before running the program, mount the proc filesystem at \fImountpoint\fP
(default is /proc).  This is useful when creating a new PID namespace.  It also
implies creating a new mount namespace since the /proc mount would otherwise
mess up existing programs on the system.  The new proc filesystem is explicitly
mounted as private (with MS_PRIVATE|MS_REC).
.TP
.BR \-r , " \-\-map\-root\-user"
Run the program only after the current effective user and group IDs have been mapped to
the superuser UID and GID in the newly created user namespace.  This makes it possible to
conveniently gain capabilities needed to manage various aspects of the newly created
namespaces (such as configuring interfaces in the network namespace or mounting filesystems in
the mount namespace) even when run unprivileged.  As a mere convenience feature, it does not support
more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs.
This option implies \fB--setgroups=deny\fR.
.TP
.BR "\-\-propagation private" | shared | slave | unchanged
Recursively set the mount propagation flag in the new mount namespace.  The default
is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
with the argument \fBunchanged\fR.  The option is silently ignored when the mount
namespace (\fB\-\-mount\fP) is not requested.
.TP
.BR "\-\-setgroups allow" | deny
Allow or deny the
.BR setgroups (2)
system call in a user namespace.
.sp
To be able to call
.BR setgroups (2),
the calling process must at least have CAP_SETGID.
But since Linux 3.19 a further restriction applies:
the kernel gives permission to call
.BR \%setgroups (2)
only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
The GID map is writable by root when
.BR \%setgroups (2)
is enabled (i.e. \fBallow\fR, the default), and
the GID map becomes writable by unprivileged processes when
.BR \%setgroups (2)
is permanently disabled (with \fBdeny\fR).
.TP
.BR \-R, "\-\-root=\fIdir"
run the command with root directory set to \fIdir\fP.
.TP
.BR \-w, "\-\-wd=\fIdir"
change working directory to \fIdir\fP.
.TP
.BR \-S, "\-\-setuid \fIuid"
Set the user ID which will be used in the entered namespace.
.TP
.BR \-G, "\-\-setgid \fIgid"
Set the group ID which will be used in the entered namespace and drop
supplementary groups.
.TP
.BR \-V , " \-\-version"
Display version information and exit.
.TP
.BR \-h , " \-\-help"
Display help text and exit.
.SH NOTES
The proc and sysfs filesystems mounting as root in a user namespace have to be
restricted so that a less privileged user can not get more access to sensitive
files that a more privileged user made unavailable. In short the rule for proc
and sysfs is as close to a bind mount as possible.
.SH EXAMPLES
.TP
.B # unshare --fork --pid --mount-proc readlink /proc/self
.TQ
1
.br
Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
procfs instance.
.TP
.B $ unshare --map-root-user --user sh -c whoami
.TQ
root
.br
Establish a user namespace as an unprivileged user with a root user within it.
.TP
.B # touch /root/uts-ns
.TQ
.B # unshare --uts=/root/uts-ns hostname FOO
.TQ
.B # nsenter --uts=/root/uts-ns hostname
.TQ
FOO
.TQ
.B # umount /root/uts-ns
.br
Establish a persistent UTS namespace, and modify the hostname.  The namespace
is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
the bind reference.
.TP
.B # mount --bind /root/namespaces /root/namespaces
.TQ
.B # mount --make-private /root/namespaces
.TQ
.B # touch /root/namespaces/mnt
.TQ
.B # unshare --mount=/root/namespaces/mnt
.br
Establish a persistent mount namespace referenced by the bind mount
/root/namespaces/mnt.  This example shows a portable solution, because it
makes sure that the bind mount is created on a shared filesystem.
.TP
.B # unshare -pf --kill-child -- bash -c "(sleep 999 &) && sleep 1000" &
.TQ
.B # pid=$!
.TQ
.B # kill $pid
.br
Reliable killing of subprocesses of the \fIprogram\fR.
When \fBunshare\fR gets killed, everything below it gets killed as well.
Without it, the children of \fIprogram\fR would have orphaned and
been re-parented to PID 1.

.SH SEE ALSO
.BR clone (2),
.BR unshare (2),
.BR namespaces (7),
.BR mount (8)
.SH AUTHORS
.UR dottedmag@dottedmag.net
Mikhail Gusarov
.UE
.br
.UR kzak@redhat.com
Karel Zak
.UE
.SH AVAILABILITY
The unshare command is part of the util-linux package and is available from
https://www.kernel.org/pub/linux/utils/util-linux/.