1UNSHARE(1) User Commands UNSHARE(1)
2
6 unshare - run program in new namespaces
7
9 unshare [options] [program [arguments]]
10
12 The unshare command creates new namespaces (as specified by the com‐
13 mand-line options described below) and then executes the specified pro‐
14 gram. If program is not given, then ``${SHELL}'' is run (default:
15 /bin/sh).
16 By default, a new namespace persists only as long as it has member pro‐
18 cesses. A new namespace can be made persistent even when it has no
19 member processes by bind mounting /proc/pid/ns/type files to a filesys‐
20 tem path. A namespace that has been made persistent in this way can
21 subsequently be entered with nsenter(1) even after the program termi‐
22 nates (except PID namespaces where a permanently running init process
23 is required). Once a persistent namespace is no longer needed, it can
24 be unpersisted by using umount(8) to remove the bind mount. See the
25 EXAMPLES section for more details.
26 unshare since util-linux version 2.36 uses /proc/[pid]/ns/pid_for_chil‐
28 dren and /proc/[pid]/ns/time_for_children files for persistent PID and
29 TIME namespaces. This change requires Linux kernel 4.17 or newer.
30 The following types of namespaces can be created with unshare:
32 mount namespace
34 Mounting and unmounting filesystems will not affect the rest of
35 the system, except for filesystems which are explicitly marked
36 as shared (with mount --make-shared; see /proc/self/mountinfo or
37 findmnt -o+PROPAGATION for the shared flags). For further
38 details, see mount_namespaces(7).
39 unshare since util-linux version 2.27 automatically sets propa‐
41 gation to private in a new mount namespace to make sure that the
42 new namespace is really unshared. It's possible to disable this
43 feature with option --propagation unchanged. Note that private
44 is the kernel default.
45 UTS namespace
47 Setting hostname or domainname will not affect the rest of the
48 system. For further details, see uts_namespaces(7).
49 IPC namespace
51 The process will have an independent namespace for POSIX message
52 queues as well as System V message queues, semaphore sets and
53 shared memory segments. For further details, see ipc_names‐
54 paces(7).
55 network namespace
57 The process will have independent IPv4 and IPv6 stacks, IP rout‐
58 ing tables, firewall rules, the /proc/net and /sys/class/net
59 directory trees, sockets, etc. For further details, see net‐
60 work_namespaces(7).
61 PID namespace
63 Children will have a distinct set of PID-to-process mappings
64 from their parent. For further details, see pid_namespaces(7).
65 cgroup namespace
67 The process will have a virtualized view of /proc/self/cgroup,
68 and new cgroup mounts will be rooted at the namespace cgroup
69 root. For further details, see cgroup_namespaces(7).
70 user namespace
72 The process will have a distinct set of UIDs, GIDs and capabili‐
73 ties. For further details, see user_namespaces(7).
74 time namespace
76 The process can have a distinct view of CLOCK_MONOTONIC and/or
77 CLOCK_BOOTTIME which can be changed using /proc/self/timens_off‐
78 sets. For further details, see time_namespaces(7).
79
81 -i, --ipc[=file]
82 Unshare the IPC namespace. If file is specified, then a persis‐
83 tent namespace is created by a bind mount.
84 -m, --mount[=file]
86 Unshare the mount namespace. If file is specified, then a per‐
87 sistent namespace is created by a bind mount. Note that file
88 must be located on a mount whose propagation type is not shared
89 (or an error results). Use the command findmnt -o+PROPAGATION
90 when not sure about the current setting. See also the examples
91 below.
92 -n, --net[=file]
94 Unshare the network namespace. If file is specified, then a
95 persistent namespace is created by a bind mount.
96 -p, --pid[=file]
98 Unshare the PID namespace. If file is specified, then a persis‐
99 tent namespace is created by a bind mount. (Creation of a per‐
100 sistent PID namespace will fail if the --fork option is not also
101 specified.)
102 See also the --fork and --mount-proc options.
104 -u, --uts[=file]
106 Unshare the UTS namespace. If file is specified, then a persis‐
107 tent namespace is created by a bind mount.
108 -U, --user[=file]
110 Unshare the user namespace. If file is specified, then a per‐
111 sistent namespace is created by a bind mount.
112 -C, --cgroup[=file]
114 Unshare the cgroup namespace. If file is specified then persis‐
115 tent namespace is created by bind mount.
116 -T, --time[=file]
118 Unshare the time namespace. If file is specified then a persis‐
119 tent namespace is created by a bind mount. The --monotonic and
120 --boottime options can be used to specify the corresponding off‐
121 set in the time namespace.
122 -f, --fork
124 Fork the specified program as a child process of unshare rather
125 than running it directly. This is useful when creating a new
126 PID namespace. Note that when unshare is waiting for the child
127 process, then it ignores SIGINT and SIGTERM and does not forward
128 any signals to the child. It is necessary to send signals to
129 the child process.
130 --keep-caps
132 When the --user option is given, ensure that capabilities
133 granted in the user namespace are preserved in the child
134 process.
135 --kill-child[=signame]
137 When unshare terminates, have signame be sent to the forked
138 child process. Combined with --pid this allows for an easy and
139 reliable killing of the entire process tree below unshare. If
140 not given, signame defaults to SIGKILL. This option implies
141 --fork.
142 --mount-proc[=mountpoint]
144 Just before running the program, mount the proc filesystem at
145 mountpoint (default is /proc). This is useful when creating a
146 new PID namespace. It also implies creating a new mount names‐
147 pace since the /proc mount would otherwise mess up existing pro‐
148 grams on the system. The new proc filesystem is explicitly
149 mounted as private (with MS_PRIVATE|MS_REC).
150 --map-user=uid|name
152 Run the program only after the current effective user ID has
153 been mapped to uid. If this option is specified multiple times,
154 the last occurrence takes precedence. This option implies
155 --user.
156 --map-group=gid|name
158 Run the program only after the current effective group ID has
159 been mapped to gid. If this option is specified multiple times,
160 the last occurrence takes precedence. This option implies
161 --setgroups=deny and --user.
162 -r, --map-root-user
164 Run the program only after the current effective user and group
165 IDs have been mapped to the superuser UID and GID in the newly
166 created user namespace. This makes it possible to conveniently
167 gain capabilities needed to manage various aspects of the newly
168 created namespaces (such as configuring interfaces in the net‐
169 work namespace or mounting filesystems in the mount namespace)
170 even when run unprivileged. As a mere convenience feature, it
171 does not support more sophisticated use cases, such as mapping
172 multiple ranges of UIDs and GIDs. This option implies --set‐
173 groups=deny and --user. This option is equivalent to --map-
174 user=0 --map-group=0.
175 -c, --map-current-user
177 Run the program only after the current effective user and group
178 IDs have been mapped to the same UID and GID in the newly cre‐
179 ated user namespace. This option implies --setgroups=deny and
180 --user. This option is equivalent to --map-user=$(id -ru)
181 --map-group=$(id -rg).
182 --propagation private|shared|slave|unchanged
184 Recursively set the mount propagation flag in the new mount
185 namespace. The default is to set the propagation to private.
186 It is possible to disable this feature with the argument
187 unchanged. The option is silently ignored when the mount names‐
188 pace (--mount) is not requested.
189 --setgroups allow|deny
191 Allow or deny the setgroups(2) system call in a user namespace.
192 To be able to call setgroups(2), the calling process must at
194 least have CAP_SETGID. But since Linux 3.19 a further restric‐
195 tion applies: the kernel gives permission to call setgroups(2)
196 only after the GID map (/proc/pid/gid_map) has been set. The
197 GID map is writable by root when setgroups(2) is enabled (i.e.,
198 allow, the default), and the GID map becomes writable by unpriv‐
199 ileged processes when setgroups(2) is permanently disabled (with
200 deny).
201 -R, --root=dir
203 run the command with root directory set to dir.
204 -w, --wd=dir
206 change working directory to dir.
207 -S, --setuid uid
209 Set the user ID which will be used in the entered namespace.
210 -G, --setgid gid
212 Set the group ID which will be used in the entered namespace and
213 drop supplementary groups.
214 --monotonic offset
216 Set the offset of CLOCK_MONOTONIC which will be used in the
217 entered time namespace. This option requires unsharing a time
218 namespace with --time.
219 --boottime offset
221 Set the offset of CLOCK_BOOTTIME which will be used in the
222 entered time namespace. This option requires unsharing a time
223 namespace with --time.
224 -V, --version
226 Display version information and exit.
227 -h, --help
229 Display help text and exit.
230
232 The proc and sysfs filesystems mounting as root in a user namespace
233 have to be restricted so that a less privileged user can not get more
234 access to sensitive files that a more privileged user made unavailable.
235 In short the rule for proc and sysfs is as close to a bind mount as
236 possible.
237
239 The following command creates a PID namespace, using --fork to ensure
240 that the executed command is performed in a child process that (being
241 the first process in the namespace) has PID 1. The --mount-proc option
242 ensures that a new mount namespace is also simultaneously created and
243 that a new proc(5) filesystem is mounted that contains information cor‐
244 responding to the new PID namespace. When the readlink command termi‐
245 nates, the new namespaces are automatically torn down.
246 # unshare --fork --pid --mount-proc readlink /proc/self
248 1
249 As an unprivileged user, create a new user namespace where the user's
251 credentials are mapped to the root IDs inside the namespace:
252 $ id -u; id -g
254 1000
255 1000
256 $ unshare --user --map-root-user \
257 sh -c 'whoami; cat /proc/self/uid_map /proc/self/gid_map'
258 root
259 0 1000 1
260 0 1000 1
261 The first of the following commands creates a new persistent UTS names‐
263 pace and modifies the hostname as seen in that namespace. The names‐
264 pace is then entered with nsenter(1) in order to display the modified
265 hostname; this step demonstrates that the UTS namespace continues to
266 exist even though the namespace had no member processes after the
267 unshare command terminated. The namespace is then destroyed by remov‐
268 ing the bind mount.
269 # touch /root/uts-ns
271 # unshare --uts=/root/uts-ns hostname FOO
272 # nsenter --uts=/root/uts-ns hostname
273 FOO
274 # umount /root/uts-ns
275 The following commands establish a persistent mount namespace refer‐
277 enced by the bind mount /root/namespaces/mnt. In order to ensure that
278 the creation of that bind mount succeeds, the parent directory
279 (/root/namespaces) is made a bind mount whose propagation type is not
280 shared.
281 # mount --bind /root/namespaces /root/namespaces
283 # mount --make-private /root/namespaces
284 # touch /root/namespaces/mnt
285 # unshare --mount=/root/namespaces/mnt
286 The following commands demonstrate the use of the --kill-child option
288 when creating a PID namespace, in order to ensure that when unshare is
289 killed, all of the processes within the PID namespace are killed.
290 # set +m # Don't print job status messages
292 # unshare --pid --fork --mount-proc --kill-child -- \
293 bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' &
294 [1] 53456
295 # PID TTY STAT TIME COMMAND
296 1 pts/3 S+ 0:00 sleep 999
297 3 pts/3 S+ 0:00 sleep 555
298 5 pts/3 R+ 0:00 ps a
299 # ps h -o 'comm' $! # Show that background job is unshare(1)
301 unshare
302 # kill $! # Kill unshare(1)
303 # pidof sleep
304 The pidof command prints no output, because the sleep processes have
306 been killed. More precisely, when the sleep process that has PID 1 in
307 the namespace (i.e., the namespace's init process) was killed, this
308 caused all other processes in the namespace to be killed. By contrast,
309 a similar series of commands where the --kill-child option is not used
310 shows that when unshare terminates, the processes in the PID namespace
311 are not killed:
312 # unshare --pid --fork --mount-proc -- \
314 bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' &
315 [1] 53479
316 # PID TTY STAT TIME COMMAND
317 1 pts/3 S+ 0:00 sleep 999
318 3 pts/3 S+ 0:00 sleep 555
319 5 pts/3 R+ 0:00 ps a
320 # kill $!
322 # pidof sleep
323 53482 53480
324 The following example demonstrates the creation of a time namespace
326 where the boottime clock is set to a point several years in the past:
327 # uptime -p # Show uptime in initial time namespace
329 up 21 hours, 30 minutes
330 # unshare --time --fork --boottime 300000000 uptime -p
331 up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes
332
334 Mikhail Gusarov ⟨dottedmag@dottedmag.net⟩
335 Karel Zak ⟨kzak@redhat.com⟩
336
338 clone(2), unshare(2), namespaces(7), mount(8)
339
341 The unshare command is part of the util-linux package and is available
342 from https://www.kernel.org/pub/linux/utils/util-linux/.
343util-linux February 2016 UNSHARE(1)