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
13 command-line options described below) and then executes the specified
14 program. 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
18 processes. 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
20 filesystem path. A namespace that has been made persistent in this way
21 can subsequently be entered with nsenter(1) even after the program
22 terminates (except PID namespaces where a permanently running init
23 process is required). Once a persistent namespace is no longer needed,
24 it can be unpersisted by using umount(8) to remove the bind mount. See
25 the EXAMPLES section for more details.
26 unshare since util-linux version 2.36 uses
28 /proc/[pid]/ns/pid_for_children and /proc/[pid]/ns/time_for_children
29 files for persistent PID and TIME namespaces. This change requires
30 Linux kernel 4.17 or newer.
31 The following types of namespaces can be created with unshare:
33 mount namespace
35 Mounting and unmounting filesystems will not affect the rest of the
36 system, except for filesystems which are explicitly marked as
37 shared (with mount --make-shared; see /proc/self/mountinfo or
38 findmnt -o+PROPAGATION for the shared flags). For further details,
39 see mount_namespaces(7).
40 unshare since util-linux version 2.27 automatically sets
42 propagation to private in a new mount namespace to make sure that
43 the new namespace is really unshared. It’s possible to disable this
44 feature with option --propagation unchanged. Note that private is
45 the kernel default.
46 UTS namespace
48 Setting hostname or domainname will not affect the rest of the
49 system. For further details, see uts_namespaces(7).
50 IPC namespace
52 The process will have an independent namespace for POSIX message
53 queues as well as System V message queues, semaphore sets and
54 shared memory segments. For further details, see ipc_namespaces(7).
55 network namespace
57 The process will have independent IPv4 and IPv6 stacks, IP routing
58 tables, firewall rules, the /proc/net and /sys/class/net directory
59 trees, sockets, etc. For further details, see
60 network_namespaces(7).
61 PID namespace
63 Children will have a distinct set of PID-to-process mappings from
64 their parent. For further details, see pid_namespaces(7).
65 cgroup namespace
67 The process will have a virtualized view of /proc/self/cgroup, and
68 new cgroup mounts will be rooted at the namespace cgroup root. For
69 further details, see cgroup_namespaces(7).
70 user namespace
72 The process will have a distinct set of UIDs, GIDs and
73 capabilities. 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
78 /proc/self/timens_offsets. For further details, see
79 time_namespaces(7).
80
82 -i, --ipc[=file]
83 Unshare the IPC namespace. If file is specified, then a persistent
84 namespace is created by a bind mount.
85 -m, --mount[=file]
87 Unshare the mount namespace. If file is specified, then a
88 persistent namespace is created by a bind mount. Note that file
89 must be located on a mount whose propagation type is not shared (or
90 an error results). Use the command findmnt -o+PROPAGATION when not
91 sure about the current setting. See also the examples 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 persistent
99 namespace is created by a bind mount. (Creation of a persistent PID
100 namespace will fail if the --fork option is not also specified.)
101 See also the --fork and --mount-proc options.
103 -u, --uts[=file]
105 Unshare the UTS namespace. If file is specified, then a persistent
106 namespace is created by a bind mount.
107 -U, --user[=file]
109 Unshare the user namespace. If file is specified, then a persistent
110 namespace is created by a bind mount.
111 -C, --cgroup[=file]
113 Unshare the cgroup namespace. If file is specified, then persistent
114 namespace is created by bind mount.
115 -T, --time[=file]
117 Unshare the time namespace. If file is specified, then a persistent
118 namespace is created by a bind mount. The --monotonic and
119 --boottime options can be used to specify the corresponding offset
120 in the time namespace.
121 -f, --fork
123 Fork the specified program as a child process of unshare rather
124 than running it directly. This is useful when creating a new PID
125 namespace. Note that when unshare is waiting for the child process,
126 then it ignores SIGINT and SIGTERM and does not forward any signals
127 to the child. It is necessary to send signals to the child process.
128 --keep-caps
130 When the --user option is given, ensure that capabilities granted
131 in the user namespace are preserved in the child process.
132 --kill-child[=signame]
134 When unshare terminates, have signame be sent to the forked child
135 process. Combined with --pid this allows for an easy and reliable
136 killing of the entire process tree below unshare. If not given,
137 signame defaults to SIGKILL. This option implies --fork.
138 --mount-proc[=mountpoint]
140 Just before running the program, mount the proc filesystem at
141 mountpoint (default is /proc). This is useful when creating a new
142 PID namespace. It also implies creating a new mount namespace since
143 the /proc mount would otherwise mess up existing programs on the
144 system. The new proc filesystem is explicitly mounted as private
145 (with MS_PRIVATE|MS_REC).
146 --map-user=uid|name
148 Run the program only after the current effective user ID has been
149 mapped to uid. If this option is specified multiple times, the last
150 occurrence takes precedence. This option implies --user.
151 --map-group=gid|name
153 Run the program only after the current effective group ID has been
154 mapped to gid. If this option is specified multiple times, the last
155 occurrence takes precedence. This option implies --setgroups=deny
156 and --user.
157 -r, --map-root-user
159 Run the program only after the current effective user and group IDs
160 have been mapped to the superuser UID and GID in the newly created
161 user namespace. This makes it possible to conveniently gain
162 capabilities needed to manage various aspects of the newly created
163 namespaces (such as configuring interfaces in the network namespace
164 or mounting filesystems in the mount namespace) even when run
165 unprivileged. As a mere convenience feature, it does not support
166 more sophisticated use cases, such as mapping multiple ranges of
167 UIDs and GIDs. This option implies --setgroups=deny and --user.
168 This option is equivalent to --map-user=0 --map-group=0.
169 -c, --map-current-user
171 Run the program only after the current effective user and group IDs
172 have been mapped to the same UID and GID in the newly created user
173 namespace. This option implies --setgroups=deny and --user. This
174 option is equivalent to --map-user=$(id -ru) --map-group=$(id -rg).
175 --propagation private|shared|slave|unchanged
177 Recursively set the mount propagation flag in the new mount
178 namespace. The default is to set the propagation to private. It is
179 possible to disable this feature with the argument unchanged. The
180 option is silently ignored when the mount namespace (--mount) is
181 not requested.
182 --setgroups allow|deny
184 Allow or deny the setgroups(2) system call in a user namespace.
185 To be able to call setgroups(2), the calling process must at least
187 have CAP_SETGID. But since Linux 3.19 a further restriction
188 applies: the kernel gives permission to call setgroups(2) only
189 after the GID map (/proc/pid*/gid_map*) has been set. The GID map
190 is writable by root when setgroups(2) is enabled (i.e., allow, the
191 default), and the GID map becomes writable by unprivileged
192 processes when setgroups(2) is permanently disabled (with deny).
193 -R, --root=dir
195 run the command with root directory set to dir.
196 -w, --wd=dir
198 change working directory to dir.
199 -S, --setuid uid
201 Set the user ID which will be used in the entered namespace.
202 -G, --setgid gid
204 Set the group ID which will be used in the entered namespace and
205 drop supplementary groups.
206 --monotonic offset
208 Set the offset of CLOCK_MONOTONIC which will be used in the entered
209 time namespace. This option requires unsharing a time namespace
210 with --time.
211 --boottime offset
213 Set the offset of CLOCK_BOOTTIME which will be used in the entered
214 time namespace. This option requires unsharing a time namespace
215 with --time.
216 -V, --version
218 Display version information and exit.
219 -h, --help
221 Display help text and exit.
222
224 The proc and sysfs filesystems mounting as root in a user namespace
225 have to be restricted so that a less privileged user can not get more
226 access to sensitive files that a more privileged user made unavailable.
227 In short the rule for proc and sysfs is as close to a bind mount as
228 possible.
229
231 The following command creates a PID namespace, using --fork to ensure
232 that the executed command is performed in a child process that (being
233 the first process in the namespace) has PID 1. The --mount-proc option
234 ensures that a new mount namespace is also simultaneously created and
235 that a new proc(5) filesystem is mounted that contains information
236 corresponding to the new PID namespace. When the readlink command
237 terminates, the new namespaces are automatically torn down.
238 # unshare --fork --pid --mount-proc readlink /proc/self
240 1
241 As an unprivileged user, create a new user namespace where the user’s
243 credentials are mapped to the root IDs inside the namespace:
244 $ id -u; id -g
246 1000
247 1000
248 $ unshare --user --map-root-user \
249 sh -c ''whoami; cat /proc/self/uid_map /proc/self/gid_map''
250 root
251 0 1000 1
252 0 1000 1
253 The first of the following commands creates a new persistent UTS
255 namespace and modifies the hostname as seen in that namespace. The
256 namespace is then entered with nsenter(1) in order to display the
257 modified hostname; this step demonstrates that the UTS namespace
258 continues to exist even though the namespace had no member processes
259 after the unshare command terminated. The namespace is then destroyed
260 by removing the bind mount.
261 # touch /root/uts-ns
263 # unshare --uts=/root/uts-ns hostname FOO
264 # nsenter --uts=/root/uts-ns hostname
265 FOO
266 # umount /root/uts-ns
267 The following commands establish a persistent mount namespace
269 referenced by the bind mount /root/namespaces/mnt. In order to ensure
270 that the creation of that bind mount succeeds, the parent directory
271 (/root/namespaces) is made a bind mount whose propagation type is not
272 shared.
273 # mount --bind /root/namespaces /root/namespaces
275 # mount --make-private /root/namespaces
276 # touch /root/namespaces/mnt
277 # unshare --mount=/root/namespaces/mnt
278 The following commands demonstrate the use of the --kill-child option
280 when creating a PID namespace, in order to ensure that when unshare is
281 killed, all of the processes within the PID namespace are killed.
282 # set +m # Don't print job status messages
284 # unshare --pid --fork --mount-proc --kill-child -- \
287 bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' &
290 [1] 53456
291 # PID TTY STAT TIME COMMAND
292 1 pts/3 S+ 0:00 sleep 999
293 3 pts/3 S+ 0:00 sleep 555
294 5 pts/3 R+ 0:00 ps a
295 # ps h -o 'comm' $! # Show that background job is unshare(1)
297 unshare
298 # kill $! # Kill unshare(1)
299 # pidof sleep
300 The pidof(1) command prints no output, because the sleep processes have
302 been killed. More precisely, when the sleep process that has PID 1 in
303 the namespace (i.e., the namespace’s init process) was killed, this
304 caused all other processes in the namespace to be killed. By contrast,
305 a similar series of commands where the --kill-child option is not used
306 shows that when unshare terminates, the processes in the PID namespace
307 are not killed:
308 # unshare --pid --fork --mount-proc -- \
310 bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' &
313 [1] 53479
314 # PID TTY STAT TIME COMMAND
315 1 pts/3 S+ 0:00 sleep 999
316 3 pts/3 S+ 0:00 sleep 555
317 5 pts/3 R+ 0:00 ps a
318 # kill $!
320 # pidof sleep
321 53482 53480
322 The following example demonstrates the creation of a time namespace
324 where the boottime clock is set to a point several years in the past:
325 # uptime -p # Show uptime in initial time namespace
327 up 21 hours, 30 minutes
328 # unshare --time --fork --boottime 300000000 uptime -p
329 up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes
330
332 Mikhail Gusarov <dottedmag@dottedmag.net>, Karel Zak <kzak@redhat.com>
333
335 clone(2), unshare(2), namespaces(7), mount(8)
336
338 For bug reports, use the issue tracker at
339 https://github.com/karelzak/util-linux/issues.
340
342 The unshare command is part of the util-linux package which can be
343 downloaded from Linux Kernel Archive
344 <https://www.kernel.org/pub/linux/utils/util-linux/>.
345util-linux 2.37.2 2021-07-20 UNSHARE(1)