1SYSTEMD-NSPAWN(1) systemd-nspawn SYSTEMD-NSPAWN(1)
2
6 systemd-nspawn - Spawn a namespace container for debugging, testing and
7 building
8
10 systemd-nspawn [OPTIONS...] [COMMAND [ARGS...]]
11 systemd-nspawn -b [OPTIONS...] [ARGS...]
13
15 systemd-nspawn may be used to run a command or OS in a light-weight
16 namespace container. In many ways it is similar to chroot(1), but more
17 powerful since it fully virtualizes the file system hierarchy, as well
18 as the process tree, the various IPC subsystems and the host and domain
19 name.
20 systemd-nspawn limits access to various kernel interfaces in the
22 container to read-only, such as /sys, /proc/sys or /sys/fs/selinux.
23 Network interfaces and the system clock may not be changed from within
24 the container. Device nodes may not be created. The host system cannot
25 be rebooted and kernel modules may not be loaded from within the
26 container.
27 Note that even though these security precautions are taken
29 systemd-nspawn is not suitable for secure container setups. Many of the
30 security features may be circumvented and are hence primarily useful to
31 avoid accidental changes to the host system from the container. The
32 intended use of this program is debugging and testing as well as
33 building of packages, distributions and software involved with boot and
34 systems management.
35 In contrast to chroot(1) systemd-nspawn may be used to boot full
37 Linux-based operating systems in a container.
38 Use a tool like yum(8), debootstrap(8), or pacman(8) to set up an OS
40 directory tree suitable as file system hierarchy for systemd-nspawn
41 containers.
42 Note that systemd-nspawn will mount file systems private to the
44 container to /dev, /run and similar. These will not be visible outside
45 of the container, and their contents will be lost when the container
46 exits.
47 Note that running two systemd-nspawn containers from the same directory
49 tree will not make processes in them see each other. The PID namespace
50 separation of the two containers is complete and the containers will
51 share very few runtime objects except for the underlying file system.
52 Use machinectl(1)'s login command to request an additional login prompt
53 in a running container.
54 systemd-nspawn implements the Container Interface[1] specification.
56 As a safety check systemd-nspawn will verify the existence of
58 /usr/lib/os-release or /etc/os-release in the container tree before
59 starting the container (see os-release(5)). It might be necessary to
60 add this file to the container tree manually if the OS of the container
61 is too old to contain this file out-of-the-box.
62
64 If option -b is specified, the arguments are used as arguments for the
65 init binary. Otherwise, COMMAND specifies the program to launch in the
66 container, and the remaining arguments are used as arguments for this
67 program. If -b is not used and no arguments are specifed, a shell is
68 launched in the container.
69 The following options are understood:
71 -D, --directory=
73 Directory to use as file system root for the container.
74 If neither --directory=, nor --image= is specified the directory is
76 determined as /var/lib/machines/ suffixed by the machine name as
77 specified with --machine=. If neither --directory=, --image=, nor
78 --machine= are specified, the current directory will be used. May
79 not be specified together with --image=.
80 --template=
82 Directory or "btrfs" subvolume to use as template for the
83 container's root directory. If this is specified and the
84 container's root directory (as configured by --directory=) does not
85 yet exist it is created as "btrfs" subvolume and populated from
86 this template tree. Ideally, the specified template path refers to
87 the root of a "btrfs" subvolume, in which case a simple
88 copy-on-write snapshot is taken, and populating the root directory
89 is instant. If the specified template path does not refer to the
90 root of a "btrfs" subvolume (or not even to a "btrfs" file system
91 at all), the tree is copied, which can be substantially more
92 time-consuming. Note that if this option is used the container's
93 root directory (in contrast to the template directory!) must be
94 located on a "btrfs" file system, so that the "btrfs" subvolume may
95 be created. May not be specified together with --image= or
96 --ephemeral.
97 -x, --ephemeral
99 If specified, the container is run with a temporary "btrfs"
100 snapshot of its root directory (as configured with --directory=),
101 that is removed immediately when the container terminates. This
102 option is only supported if the root file system is "btrfs". May
103 not be specified together with --image= or --template=.
104 -i, --image=
106 Disk image to mount the root directory for the container from.
107 Takes a path to a regular file or to a block device node. The file
108 or block device must contain either:
109 · An MBR partition table with a single partition of type 0x83
111 that is marked bootable.
112 · A GUID partition table (GPT) with a single partition of type
114 0fc63daf-8483-4772-8e79-3d69d8477de4.
115 · A GUID partition table (GPT) with a marked root partition which
117 is mounted as the root directory of the container. Optionally,
118 GPT images may contain a home and/or a server data partition
119 which are mounted to the appropriate places in the container.
120 All these partitions must be identified by the partition types
121 defined by the Discoverable Partitions Specification[2].
122 Any other partitions, such as foreign partitions, swap partitions
124 or EFI system partitions are not mounted. May not be specified
125 together with --directory=, --template= or --ephemeral.
126 -a, --as-pid2
128 Invoke the shell or specified program as process ID (PID) 2 instead
129 of PID 1 (init). By default, if neither this option nor --boot is
130 used, the selected binary is run as process with PID 1, a mode only
131 suitable for programs that are aware of the special semantics that
132 the process with PID 1 has on UNIX. For example, it needs to reap
133 all processes reparented to it, and should implement sysvinit
134 compatible signal handling (specifically: it needs to reboot on
135 SIGINT, reexecute on SIGTERM, reload configuration on SIGHUP, and
136 so on). With --as-pid2 a minimal stub init process is run as PID 1
137 and the selected binary is executed as PID 2 (and hence does not
138 need to implement any special semantics). The stub init process
139 will reap processes as necessary and react appropriately to
140 signals. It is recommended to use this mode to invoke arbitrary
141 commands in containers, unless they have been modified to run
142 correctly as PID 1. Or in other words: this switch should be used
143 for pretty much all commands, except when the command refers to an
144 init or shell implementation, as these are generally capable of
145 running correctly as PID 1). This option may not be combined with
146 --boot or --share-system.
147 -b, --boot
149 Automatically search for an init binary and invoke it as PID 1,
150 instead of a shell or a user supplied program. If this option is
151 used, arguments specified on the command line are used as arguments
152 for the init binary. This option may not be combined with --as-pid2
153 or --share-system.
154 The following table explains the different modes of invocation and
156 relationship to --as-pid2 (see above):
157 Table 1. Invocation Mode
159 ┌──────────────────────┬────────────────────────────┐
160 │Switch │ Explanation │
161 ├──────────────────────┼────────────────────────────┤
162 │Neither --as-pid2 nor │ The passed parameters are │
163 │--boot specified │ interpreted as command │
164 │ │ line, which is executed as │
165 │ │ PID 1 in the container. │
166 ├──────────────────────┼────────────────────────────┤
167 │--as-pid2 specified │ The passed parameters are │
168 │ │ interpreted as command │
169 │ │ line, which are executed │
170 │ │ as PID 2 in the container. │
171 │ │ A stub init process is run │
172 │ │ as PID 1. │
173 ├──────────────────────┼────────────────────────────┤
174 │--boot specified │ An init binary as │
175 │ │ automatically searched and │
176 │ │ run as PID 1 in the │
177 │ │ container. The passed │
178 │ │ parameters are used as │
179 │ │ invocation parameters for │
180 │ │ this process. │
181 └──────────────────────┴────────────────────────────┘
182 -u, --user=
184 After transitioning into the container, change to the specified
185 user-defined in the container's user database. Like all other
186 systemd-nspawn features, this is not a security feature and
187 provides protection against accidental destructive operations only.
188 -M, --machine=
190 Sets the machine name for this container. This name may be used to
191 identify this container during its runtime (for example in tools
192 like machinectl(1) and similar), and is used to initialize the
193 container's hostname (which the container can choose to override,
194 however). If not specified, the last component of the root
195 directory path of the container is used, possibly suffixed with a
196 random identifier in case --ephemeral mode is selected. If the root
197 directory selected is the host's root directory the host's hostname
198 is used as default instead.
199 --uuid=
201 Set the specified UUID for the container. The init system will
202 initialize /etc/machine-id from this if this file is not set yet.
203 --slice=
205 Make the container part of the specified slice, instead of the
206 default machine.slice.
207 --private-network
209 Disconnect networking of the container from the host. This makes
210 all network interfaces unavailable in the container, with the
211 exception of the loopback device and those specified with
212 --network-interface= and configured with --network-veth. If this
213 option is specified, the CAP_NET_ADMIN capability will be added to
214 the set of capabilities the container retains. The latter may be
215 disabled by using --drop-capability=.
216 --network-interface=
218 Assign the specified network interface to the container. This will
219 remove the specified interface from the calling namespace and place
220 it in the container. When the container terminates, it is moved
221 back to the host namespace. Note that --network-interface= implies
222 --private-network. This option may be used more than once to add
223 multiple network interfaces to the container.
224 --network-macvlan=
226 Create a "macvlan" interface of the specified Ethernet network
227 interface and add it to the container. A "macvlan" interface is a
228 virtual interface that adds a second MAC address to an existing
229 physical Ethernet link. The interface in the container will be
230 named after the interface on the host, prefixed with "mv-". Note
231 that --network-macvlan= implies --private-network. This option may
232 be used more than once to add multiple network interfaces to the
233 container.
234 --network-ipvlan=
236 Create an "ipvlan" interface of the specified Ethernet network
237 interface and add it to the container. An "ipvlan" interface is a
238 virtual interface, similar to a "macvlan" interface, which uses the
239 same MAC address as the underlying interface. The interface in the
240 container will be named after the interface on the host, prefixed
241 with "iv-". Note that --network-ipvlan= implies --private-network.
242 This option may be used more than once to add multiple network
243 interfaces to the container.
244 -n, --network-veth
246 Create a virtual Ethernet link ("veth") between host and container.
247 The host side of the Ethernet link will be available as a network
248 interface named after the container's name (as specified with
249 --machine=), prefixed with "ve-". The container side of the
250 Ethernet link will be named "host0". Note that --network-veth
251 implies --private-network.
252 --network-bridge=
254 Adds the host side of the Ethernet link created with --network-veth
255 to the specified bridge. Note that --network-bridge= implies
256 --network-veth. If this option is used, the host side of the
257 Ethernet link will use the "vb-" prefix instead of "ve-".
258 -p, --port=
260 If private networking is enabled, maps an IP port on the host onto
261 an IP port on the container. Takes a protocol specifier (either
262 "tcp" or "udp"), separated by a colon from a host port number in
263 the range 1 to 65535, separated by a colon from a container port
264 number in the range from 1 to 65535. The protocol specifier and its
265 separating colon may be omitted, in which case "tcp" is assumed.
266 The container port number and its colon may be ommitted, in which
267 case the same port as the host port is implied. This option is only
268 supported if private networking is used, such as --network-veth or
269 --network-bridge=.
270 -Z, --selinux-context=
272 Sets the SELinux security context to be used to label processes in
273 the container.
274 -L, --selinux-apifs-context=
276 Sets the SELinux security context to be used to label files in the
277 virtual API file systems in the container.
278 --capability=
280 List one or more additional capabilities to grant the container.
281 Takes a comma-separated list of capability names, see
282 capabilities(7) for more information. Note that the following
283 capabilities will be granted in any way: CAP_CHOWN,
284 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID,
285 CAP_IPC_OWNER, CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
286 CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETGID,
287 CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN,
288 CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
289 CAP_SYS_RESOURCE, CAP_SYS_BOOT, CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL.
290 Also CAP_NET_ADMIN is retained if --private-network is specified.
291 If the special value "all" is passed, all capabilities are
292 retained.
293 --drop-capability=
295 Specify one or more additional capabilities to drop for the
296 container. This allows running the container with fewer
297 capabilities than the default (see above).
298 --link-journal=
300 Control whether the container's journal shall be made visible to
301 the host system. If enabled, allows viewing the container's journal
302 files from the host (but not vice versa). Takes one of "no",
303 "host", "try-host", "guest", "try-guest", "auto". If "no", the
304 journal is not linked. If "host", the journal files are stored on
305 the host file system (beneath /var/log/journal/machine-id) and the
306 subdirectory is bind-mounted into the container at the same
307 location. If "guest", the journal files are stored on the guest
308 file system (beneath /var/log/journal/machine-id) and the
309 subdirectory is symlinked into the host at the same location.
310 "try-host" and "try-guest" do the same but do not fail if the host
311 does not have persistent journalling enabled. If "auto" (the
312 default), and the right subdirectory of /var/log/journal exists, it
313 will be bind mounted into the container. If the subdirectory does
314 not exist, no linking is performed. Effectively, booting a
315 container once with "guest" or "host" will link the journal
316 persistently if further on the default of "auto" is used.
317 -j
319 Equivalent to --link-journal=try-guest.
320 --read-only
322 Mount the root file system read-only for the container.
323 --bind=, --bind-ro=
325 Bind mount a file or directory from the host into the container.
326 Either takes a path argument -- in which case the specified path
327 will be mounted from the host to the same path in the container --,
328 or a colon-separated pair of paths -- in which case the first
329 specified path is the source in the host, and the second path is
330 the destination in the container. The --bind-ro= option creates
331 read-only bind mounts.
332 --tmpfs=
334 Mount a tmpfs file system into the container. Takes a single
335 absolute path argument that specifies where to mount the tmpfs
336 instance to (in which case the directory access mode will be chosen
337 as 0755, owned by root/root), or optionally a colon-separated pair
338 of path and mount option string, that is used for mounting (in
339 which case the kernel default for access mode and owner will be
340 chosen, unless otherwise specified). This option is particularly
341 useful for mounting directories such as /var as tmpfs, to allow
342 state-less systems, in particular when combined with --read-only.
343 --setenv=
345 Specifies an environment variable assignment to pass to the init
346 process in the container, in the format "NAME=VALUE". This may be
347 used to override the default variables or to set additional
348 variables. This parameter may be used more than once.
349 --share-system
351 Allows the container to share certain system facilities with the
352 host. More specifically, this turns off PID namespacing, UTS
353 namespacing and IPC namespacing, and thus allows the guest to see
354 and interact more easily with processes outside of the container.
355 Note that using this option makes it impossible to start up a full
356 Operating System in the container, as an init system cannot operate
357 in this mode. It is only useful to run specific programs or
358 applications this way, without involving an init system in the
359 container. This option implies --register=no. This option may not
360 be combined with --boot.
361 --register=
363 Controls whether the container is registered with systemd-
364 machined(8). Takes a boolean argument, defaults to "yes". This
365 option should be enabled when the container runs a full Operating
366 System (more specifically: an init system), and is useful to ensure
367 that the container is accessible via machinectl(1) and shown by
368 tools such as ps(1). If the container does not run an init system,
369 it is recommended to set this option to "no". Note that
370 --share-system implies --register=no.
371 --keep-unit
373 Instead of creating a transient scope unit to run the container in,
374 simply register the service or scope unit systemd-nspawn has been
375 invoked in with systemd-machined(8). This has no effect if
376 --register=no is used. This switch should be used if systemd-nspawn
377 is invoked from within a service unit, and the service unit's sole
378 purpose is to run a single systemd-nspawn container. This option is
379 not available if run from a user session.
380 --personality=
382 Control the architecture ("personality") reported by uname(2) in
383 the container. Currently, only "x86" and "x86-64" are supported.
384 This is useful when running a 32-bit container on a 64-bit host. If
385 this setting is not used, the personality reported in the container
386 is the same as the one reported on the host.
387 -q, --quiet
389 Turns off any status output by the tool itself. When this switch is
390 used, the only output from nspawn will be the console output of the
391 container OS itself.
392 --volatile=MODE
394 Boots the container in volatile mode. When no mode parameter is
395 passed or when mode is specified as "yes" full volatile mode is
396 enabled. This means the root directory is mounted as mostly
397 unpopulated "tmpfs" instance, and /usr from the OS tree is mounted
398 into it, read-only (the system thus starts up with read-only OS
399 resources, but pristine state and configuration, any changes to the
400 either are lost on shutdown). When the mode parameter is specified
401 as "state" the OS tree is mounted read-only, but /var is mounted as
402 "tmpfs" instance into it (the system thus starts up with read-only
403 OS resources and configuration, but pristine state, any changes to
404 the latter are lost on shutdown). When the mode parameter is
405 specified as "no" (the default) the whole OS tree is made available
406 writable.
407 Note that setting this to "yes" or "state" will only work correctly
409 with operating systems in the container that can boot up with only
410 /usr mounted, and are able to populate /var automatically, as
411 needed.
412 -h, --help
414 Print a short help text and exit.
415 --version
417 Print a short version string and exit.
418
420 Example 1. Download a Fedora image and start a shell in it
421 # machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
423 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21
424 This downloads an image using machinectl(1) and opens a shell in it.
426 Example 2. Build and boot a minimal Fedora distribution in a container
428 # yum -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
430 # systemd-nspawn -bD /srv/mycontainer
431 This installs a minimal Fedora distribution into the directory
433 /srv/mycontainer/ and then boots an OS in a namespace container in it.
434 Example 3. Spawn a shell in a container of a minimal Debian unstable
436 distribution
437 # debootstrap --arch=amd64 unstable ~/debian-tree/
439 # systemd-nspawn -D ~/debian-tree/
440 This installs a minimal Debian unstable distribution into the directory
442 ~/debian-tree/ and then spawns a shell in a namespace container in it.
443 Example 4. Boot a minimal Arch Linux distribution in a container
445 # pacstrap -c -d ~/arch-tree/ base
447 # systemd-nspawn -bD ~/arch-tree/
448 This installs a mimimal Arch Linux distribution into the directory
450 ~/arch-tree/ and then boots an OS in a namespace container in it.
451 Example 5. Boot into an ephemeral "btrfs" snapshot of the host system
453 # systemd-nspawn -D / -xb
455 This runs a copy of the host system in a "btrfs" snapshot which is
457 removed immediately when the container exits. All file system changes
458 made during runtime will be lost on shutdown, hence.
459 Example 6. Run a container with SELinux sandbox security contexts
461 # chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
463 # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh
464
466 The exit code of the program executed in the container is returned.
467
469 systemd(1), chroot(1), yum(8), debootstrap(8), pacman(8),
470 systemd.slice(5), machinectl(1), btrfs(8)
471
473 1. Container Interface
474 http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface
475 2. Discoverable Partitions Specification
477 http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/
478systemd 219 SYSTEMD-NSPAWN(1)