1SYSTEMD-NSPAWN(1) systemd-nspawn SYSTEMD-NSPAWN(1)
2
6 systemd-nspawn - Spawn a command or OS in a light-weight container
7
9 systemd-nspawn [OPTIONS...] [COMMAND [ARGS...]]
10 systemd-nspawn --boot [OPTIONS...] [ARGS...]
12
14 systemd-nspawn may be used to run a command or OS in a light-weight
15 namespace container. In many ways it is similar to chroot(1), but more
16 powerful since it fully virtualizes the file system hierarchy, as well
17 as the process tree, the various IPC subsystems and the host and domain
18 name.
19 systemd-nspawn may be invoked on any directory tree containing an
21 operating system tree, using the --directory= command line option. By
22 using the --machine= option an OS tree is automatically searched for in
23 a couple of locations, most importantly in /var/lib/machines, the
24 suggested directory to place OS container images installed on the
25 system.
26 In contrast to chroot(1) systemd-nspawn may be used to boot full
28 Linux-based operating systems in a container.
29 systemd-nspawn limits access to various kernel interfaces in the
31 container to read-only, such as /sys, /proc/sys or /sys/fs/selinux. The
32 host's network interfaces and the system clock may not be changed from
33 within the container. Device nodes may not be created. The host system
34 cannot be rebooted and kernel modules may not be loaded from within the
35 container.
36 Use a tool like dnf(8), debootstrap(8), or pacman(8) to set up an OS
38 directory tree suitable as file system hierarchy for systemd-nspawn
39 containers. See the Examples section below for details on suitable
40 invocation of these commands.
41 As a safety check systemd-nspawn will verify the existence of
43 /usr/lib/os-release or /etc/os-release in the container tree before
44 starting the container (see os-release(5)). It might be necessary to
45 add this file to the container tree manually if the OS of the container
46 is too old to contain this file out-of-the-box.
47 systemd-nspawn may be invoked directly from the interactive command
49 line or run as system service in the background. In this mode each
50 container instance runs as its own service instance; a default template
51 unit file systemd-nspawn@.service is provided to make this easy, taking
52 the container name as instance identifier. Note that different default
53 options apply when systemd-nspawn is invoked by the template unit file
54 than interactively on the command line. Most importantly the template
55 unit file makes use of the --boot which is not the default in case
56 systemd-nspawn is invoked from the interactive command line. Further
57 differences with the defaults are documented along with the various
58 supported options below.
59 The machinectl(1) tool may be used to execute a number of operations on
61 containers. In particular it provides easy-to-use commands to run
62 containers as system services using the systemd-nspawn@.service
63 template unit file.
64 Along with each container a settings file with the .nspawn suffix may
66 exist, containing additional settings to apply when running the
67 container. See systemd.nspawn(5) for details. Settings files override
68 the default options used by the systemd-nspawn@.service template unit
69 file, making it usually unnecessary to alter this template file
70 directly.
71 Note that systemd-nspawn will mount file systems private to the
73 container to /dev, /run and similar. These will not be visible outside
74 of the container, and their contents will be lost when the container
75 exits.
76 Note that running two systemd-nspawn containers from the same directory
78 tree will not make processes in them see each other. The PID namespace
79 separation of the two containers is complete and the containers will
80 share very few runtime objects except for the underlying file system.
81 Use machinectl(1)'s login or shell commands to request an additional
82 login session in a running container.
83 systemd-nspawn implements the Container Interface[1] specification.
85 While running, containers invoked with systemd-nspawn are registered
87 with the systemd-machined(8) service that keeps track of running
88 containers, and provides programming interfaces to interact with them.
89
91 If option -b is specified, the arguments are used as arguments for the
92 init program. Otherwise, COMMAND specifies the program to launch in the
93 container, and the remaining arguments are used as arguments for this
94 program. If --boot is not used and no arguments are specified, a shell
95 is launched in the container.
96 The following options are understood:
98 -D, --directory=
100 Directory to use as file system root for the container.
101 If neither --directory=, nor --image= is specified the directory is
103 determined by searching for a directory named the same as the
104 machine name specified with --machine=. See machinectl(1) section
105 "Files and Directories" for the precise search path.
106 If neither --directory=, --image=, nor --machine= are specified,
108 the current directory will be used. May not be specified together
109 with --image=.
110 --template=
112 Directory or "btrfs" subvolume to use as template for the
113 container's root directory. If this is specified and the
114 container's root directory (as configured by --directory=) does not
115 yet exist it is created as "btrfs" snapshot (if supported) or plain
116 directory (otherwise) and populated from this template tree.
117 Ideally, the specified template path refers to the root of a
118 "btrfs" subvolume, in which case a simple copy-on-write snapshot is
119 taken, and populating the root directory is instant. If the
120 specified template path does not refer to the root of a "btrfs"
121 subvolume (or not even to a "btrfs" file system at all), the tree
122 is copied (though possibly in a copy-on-write scheme — if the file
123 system supports that), which can be substantially more
124 time-consuming. May not be specified together with --image= or
125 --ephemeral.
126 Note that this switch leaves host name, machine ID and all other
128 settings that could identify the instance unmodified.
129 -x, --ephemeral
131 If specified, the container is run with a temporary snapshot of its
132 file system that is removed immediately when the container
133 terminates. May not be specified together with --template=.
134 Note that this switch leaves host name, machine ID and all other
136 settings that could identify the instance unmodified.
137 -i, --image=
139 Disk image to mount the root directory for the container from.
140 Takes a path to a regular file or to a block device node. The file
141 or block device must contain either:
142 · An MBR partition table with a single partition of type 0x83
144 that is marked bootable.
145 · A GUID partition table (GPT) with a single partition of type
147 0fc63daf-8483-4772-8e79-3d69d8477de4.
148 · A GUID partition table (GPT) with a marked root partition which
150 is mounted as the root directory of the container. Optionally,
151 GPT images may contain a home and/or a server data partition
152 which are mounted to the appropriate places in the container.
153 All these partitions must be identified by the partition types
154 defined by the Discoverable Partitions Specification[2].
155 · No partition table, and a single file system spanning the whole
157 image.
158 On GPT images, if an EFI System Partition (ESP) is discovered, it
160 is automatically mounted to /efi (or /boot as fallback) in case a
161 directory by this name exists and is empty.
162 Partitions encrypted with LUKS are automatically decrypted. Also,
164 on GPT images dm-verity data integrity hash partitions are set up
165 if the root hash for them is specified using the --root-hash=
166 option.
167 Any other partitions, such as foreign partitions or swap partitions
169 are not mounted. May not be specified together with --directory=,
170 --template=.
171 --root-hash=
173 Takes a data integrity (dm-verity) root hash specified in
174 hexadecimal. This option enables data integrity checks using
175 dm-verity, if the used image contains the appropriate integrity
176 data (see above). The specified hash must match the root hash of
177 integrity data, and is usually at least 256 bits (and hence 64
178 formatted hexadecimal characters) long (in case of SHA256 for
179 example). If this option is not specified, but the image file
180 carries the "user.verity.roothash" extended file attribute (see
181 xattr(7)), then the root hash is read from it, also as formatted
182 hexadecimal characters. If the extended file attribute is not found
183 (or is not supported by the underlying file system), but a file
184 with the .roothash suffix is found next to the image file, bearing
185 otherwise the same name, the root hash is read from it and
186 automatically used, also as formatted hexadecimal characters.
187 -a, --as-pid2
189 Invoke the shell or specified program as process ID (PID) 2 instead
190 of PID 1 (init). By default, if neither this option nor --boot is
191 used, the selected program is run as the process with PID 1, a mode
192 only suitable for programs that are aware of the special semantics
193 that the process with PID 1 has on UNIX. For example, it needs to
194 reap all processes reparented to it, and should implement sysvinit
195 compatible signal handling (specifically: it needs to reboot on
196 SIGINT, reexecute on SIGTERM, reload configuration on SIGHUP, and
197 so on). With --as-pid2 a minimal stub init process is run as PID 1
198 and the selected program is executed as PID 2 (and hence does not
199 need to implement any special semantics). The stub init process
200 will reap processes as necessary and react appropriately to
201 signals. It is recommended to use this mode to invoke arbitrary
202 commands in containers, unless they have been modified to run
203 correctly as PID 1. Or in other words: this switch should be used
204 for pretty much all commands, except when the command refers to an
205 init or shell implementation, as these are generally capable of
206 running correctly as PID 1. This option may not be combined with
207 --boot.
208 -b, --boot
210 Automatically search for an init program and invoke it as PID 1,
211 instead of a shell or a user supplied program. If this option is
212 used, arguments specified on the command line are used as arguments
213 for the init program. This option may not be combined with
214 --as-pid2.
215 The following table explains the different modes of invocation and
217 relationship to --as-pid2 (see above):
218 Table 1. Invocation Mode
220 ┌──────────────────────┬────────────────────────────┐
221 │Switch │ Explanation │
222 ├──────────────────────┼────────────────────────────┤
223 │Neither --as-pid2 nor │ The passed parameters are │
224 │--boot specified │ interpreted as the command │
225 │ │ line, which is executed as │
226 │ │ PID 1 in the container. │
227 ├──────────────────────┼────────────────────────────┤
228 │--as-pid2 specified │ The passed parameters are │
229 │ │ interpreted as the command │
230 │ │ line, which is executed as │
231 │ │ PID 2 in the container. A │
232 │ │ stub init process is run │
233 │ │ as PID 1. │
234 ├──────────────────────┼────────────────────────────┤
235 │--boot specified │ An init program is │
236 │ │ automatically searched for │
237 │ │ and run as PID 1 in the │
238 │ │ container. The passed │
239 │ │ parameters are used as │
240 │ │ invocation parameters for │
241 │ │ this process. │
242 └──────────────────────┴────────────────────────────┘
243 Note that --boot is the default mode of operation if the
244 systemd-nspawn@.service template unit file is used.
245 --chdir=
247 Change to the specified working directory before invoking the
248 process in the container. Expects an absolute path in the
249 container's file system namespace.
250 --pivot-root=
252 Pivot the specified directory to / inside the container, and either
253 unmount the container's old root, or pivot it to another specified
254 directory. Takes one of: a path argument — in which case the
255 specified path will be pivoted to / and the old root will be
256 unmounted; or a colon-separated pair of new root path and pivot
257 destination for the old root. The new root path will be pivoted to
258 /, and the old / will be pivoted to the other directory. Both paths
259 must be absolute, and are resolved in the container's file system
260 namespace.
261 This is for containers which have several bootable directories in
263 them; for example, several OSTree[3] deployments. It emulates the
264 behavior of the boot loader and initial RAM disk which normally
265 select which directory to mount as the root and start the
266 container's PID 1 in.
267 -u, --user=
269 After transitioning into the container, change to the specified
270 user-defined in the container's user database. Like all other
271 systemd-nspawn features, this is not a security feature and
272 provides protection against accidental destructive operations only.
273 -M, --machine=
275 Sets the machine name for this container. This name may be used to
276 identify this container during its runtime (for example in tools
277 like machinectl(1) and similar), and is used to initialize the
278 container's hostname (which the container can choose to override,
279 however). If not specified, the last component of the root
280 directory path of the container is used, possibly suffixed with a
281 random identifier in case --ephemeral mode is selected. If the root
282 directory selected is the host's root directory the host's hostname
283 is used as default instead.
284 --hostname=
286 Controls the hostname to set within the container, if different
287 from the machine name. Expects a valid hostname as argument. If
288 this option is used, the kernel hostname of the container will be
289 set to this value, otherwise it will be initialized to the machine
290 name as controlled by the --machine= option described above. The
291 machine name is used for various aspect of identification of the
292 container from the outside, the kernel hostname configurable with
293 this option is useful for the container to identify itself from the
294 inside. It is usually a good idea to keep both forms of
295 identification synchronized, in order to avoid confusion. It is
296 hence recommended to avoid usage of this option, and use --machine=
297 exclusively. Note that regardless whether the container's hostname
298 is initialized from the name set with --hostname= or the one set
299 with --machine=, the container can later override its kernel
300 hostname freely on its own as well.
301 --uuid=
303 Set the specified UUID for the container. The init system will
304 initialize /etc/machine-id from this if this file is not set yet.
305 Note that this option takes effect only if /etc/machine-id in the
306 container is unpopulated.
307 -S, --slice=
309 Make the container part of the specified slice, instead of the
310 default machine.slice. This applies only if the machine is run in
311 its own scope unit, i.e. if --keep-unit isn't used.
312 --property=
314 Set a unit property on the scope unit to register for the machine.
315 This applies only if the machine is run in its own scope unit, i.e.
316 if --keep-unit isn't used. Takes unit property assignments in the
317 same format as systemctl set-property. This is useful to set memory
318 limits and similar for container.
319 --private-users=
321 Controls user namespacing. If enabled, the container will run with
322 its own private set of UNIX user and group ids (UIDs and GIDs).
323 This involves mapping the private UIDs/GIDs used in the container
324 (starting with the container's root user 0 and up) to a range of
325 UIDs/GIDs on the host that are not used for other purposes (usually
326 in the range beyond the host's UID/GID 65536). The parameter may be
327 specified as follows:
328 1. If one or two colon-separated numbers are specified, user
330 namespacing is turned on. The first parameter specifies the
331 first host UID/GID to assign to the container, the second
332 parameter specifies the number of host UIDs/GIDs to assign to
333 the container. If the second parameter is omitted, 65536
334 UIDs/GIDs are assigned.
335 2. If the parameter is omitted, or true, user namespacing is
337 turned on. The UID/GID range to use is determined automatically
338 from the file ownership of the root directory of the
339 container's directory tree. To use this option, make sure to
340 prepare the directory tree in advance, and ensure that all
341 files and directories in it are owned by UIDs/GIDs in the range
342 you'd like to use. Also, make sure that used file ACLs
343 exclusively reference UIDs/GIDs in the appropriate range. If
344 this mode is used the number of UIDs/GIDs assigned to the
345 container for use is 65536, and the UID/GID of the root
346 directory must be a multiple of 65536.
347 3. If the parameter is false, user namespacing is turned off. This
349 is the default.
350 4. The special value "pick" turns on user namespacing. In this
352 case the UID/GID range is automatically chosen. As first step,
353 the file owner of the root directory of the container's
354 directory tree is read, and it is checked that it is currently
355 not used by the system otherwise (in particular, that no other
356 container is using it). If this check is successful, the
357 UID/GID range determined this way is used, similar to the
358 behavior if "yes" is specified. If the check is not successful
359 (and thus the UID/GID range indicated in the root directory's
360 file owner is already used elsewhere) a new – currently unused
361 – UID/GID range of 65536 UIDs/GIDs is randomly chosen between
362 the host UID/GIDs of 524288 and 1878982656, always starting at
363 a multiple of 65536. This setting implies --private-users-chown
364 (see below), which has the effect that the files and
365 directories in the container's directory tree will be owned by
366 the appropriate users of the range picked. Using this option
367 makes user namespace behavior fully automatic. Note that the
368 first invocation of a previously unused container image might
369 result in picking a new UID/GID range for it, and thus in the
370 (possibly expensive) file ownership adjustment operation.
371 However, subsequent invocations of the container will be cheap
372 (unless of course the picked UID/GID range is assigned to a
373 different use by then).
374 It is recommended to assign at least 65536 UIDs/GIDs to each
376 container, so that the usable UID/GID range in the container covers
377 16 bit. For best security, do not assign overlapping UID/GID ranges
378 to multiple containers. It is hence a good idea to use the upper 16
379 bit of the host 32-bit UIDs/GIDs as container identifier, while the
380 lower 16 bit encode the container UID/GID used. This is in fact the
381 behavior enforced by the --private-users=pick option.
382 When user namespaces are used, the GID range assigned to each
384 container is always chosen identical to the UID range.
385 In most cases, using --private-users=pick is the recommended option
387 as it enhances container security massively and operates fully
388 automatically in most cases.
389 Note that the picked UID/GID range is not written to /etc/passwd or
391 /etc/group. In fact, the allocation of the range is not stored
392 persistently anywhere, except in the file ownership of the files
393 and directories of the container.
394 Note that when user namespacing is used file ownership on disk
396 reflects this, and all of the container's files and directories are
397 owned by the container's effective user and group IDs. This means
398 that copying files from and to the container image requires
399 correction of the numeric UID/GID values, according to the UID/GID
400 shift applied.
401 --private-users-chown
403 If specified, all files and directories in the container's
404 directory tree will adjusted so that they are owned to the
405 appropriate UIDs/GIDs selected for the container (see above). This
406 operation is potentially expensive, as it involves descending and
407 iterating through the full directory tree of the container. Besides
408 actual file ownership, file ACLs are adjusted as well.
409 This option is implied if --private-users=pick is used. This option
411 has no effect if user namespacing is not used.
412 -U
414 If the kernel supports the user namespaces feature, equivalent to
415 --private-users=pick --private-users-chown, otherwise equivalent to
416 --private-users=no.
417 Note that -U is the default if the systemd-nspawn@.service template
419 unit file is used.
420 Note: it is possible to undo the effect of --private-users-chown
422 (or -U) on the file system by redoing the operation with the first
423 UID of 0:
424 systemd-nspawn ... --private-users=0 --private-users-chown
426 --private-network
428 Disconnect networking of the container from the host. This makes
429 all network interfaces unavailable in the container, with the
430 exception of the loopback device and those specified with
431 --network-interface= and configured with --network-veth. If this
432 option is specified, the CAP_NET_ADMIN capability will be added to
433 the set of capabilities the container retains. The latter may be
434 disabled by using --drop-capability=. If this option is not
435 specified (or implied by one of the options listed below), the
436 container will have full access to the host network.
437 --network-namespace-path=
439 Takes the path to a file representing a kernel network namespace
440 that the container shall run in. The specified path should refer to
441 a (possibly bind-mounted) network namespace file, as exposed by the
442 kernel below /proc/$PID/ns/net. This makes the container enter the
443 given network namespace. One of the typical use cases is to give a
444 network namespace under /run/netns created by ip-netns(8), for
445 example, --network-namespace-path=/run/netns/foo. Note that this
446 option cannot be used together with other network-related options,
447 such as --private-network or --network-interface=.
448 --network-interface=
450 Assign the specified network interface to the container. This will
451 remove the specified interface from the calling namespace and place
452 it in the container. When the container terminates, it is moved
453 back to the host namespace. Note that --network-interface= implies
454 --private-network. This option may be used more than once to add
455 multiple network interfaces to the container.
456 --network-macvlan=
458 Create a "macvlan" interface of the specified Ethernet network
459 interface and add it to the container. A "macvlan" interface is a
460 virtual interface that adds a second MAC address to an existing
461 physical Ethernet link. The interface in the container will be
462 named after the interface on the host, prefixed with "mv-". Note
463 that --network-macvlan= implies --private-network. This option may
464 be used more than once to add multiple network interfaces to the
465 container.
466 --network-ipvlan=
468 Create an "ipvlan" interface of the specified Ethernet network
469 interface and add it to the container. An "ipvlan" interface is a
470 virtual interface, similar to a "macvlan" interface, which uses the
471 same MAC address as the underlying interface. The interface in the
472 container will be named after the interface on the host, prefixed
473 with "iv-". Note that --network-ipvlan= implies --private-network.
474 This option may be used more than once to add multiple network
475 interfaces to the container.
476 -n, --network-veth
478 Create a virtual Ethernet link ("veth") between host and container.
479 The host side of the Ethernet link will be available as a network
480 interface named after the container's name (as specified with
481 --machine=), prefixed with "ve-". The container side of the
482 Ethernet link will be named "host0". The --network-veth option
483 implies --private-network.
484 Note that systemd-networkd.service(8) includes by default a network
486 file /usr/lib/systemd/network/80-container-ve.network matching the
487 host-side interfaces created this way, which contains settings to
488 enable automatic address provisioning on the created virtual link
489 via DHCP, as well as automatic IP routing onto the host's external
490 network interfaces. It also contains
491 /usr/lib/systemd/network/80-container-host0.network matching the
492 container-side interface created this way, containing settings to
493 enable client side address assignment via DHCP. In case
494 systemd-networkd is running on both the host and inside the
495 container, automatic IP communication from the container to the
496 host is thus available, with further connectivity to the external
497 network.
498 Note that --network-veth is the default if the
500 systemd-nspawn@.service template unit file is used.
501 Note that on Linux network interface names may have a length of 15
503 characters at maximum, while container names may have a length up
504 to 64 characters. As this option derives the host-side interface
505 name from the container name the name is possibly truncated. Thus,
506 care needs to be taken to ensure that interface names remain unique
507 in this case, or even better container names are generally not
508 chosen longer than 12 characters, to avoid the truncation.
509 Alternatively, the --network-veth-extra= option may be used, which
510 allows free configuration of the host-side interface name
511 independently of the container name — but might require a bit more
512 additional configuration in case bridging in a fashion similar to
513 --network-bridge= is desired.
514 --network-veth-extra=
516 Adds an additional virtual Ethernet link between host and
517 container. Takes a colon-separated pair of host interface name and
518 container interface name. The latter may be omitted in which case
519 the container and host sides will be assigned the same name. This
520 switch is independent of --network-veth, and — in contrast — may be
521 used multiple times, and allows configuration of the network
522 interface names. Note that --network-bridge= has no effect on
523 interfaces created with --network-veth-extra=.
524 --network-bridge=
526 Adds the host side of the Ethernet link created with --network-veth
527 to the specified Ethernet bridge interface. Expects a valid network
528 interface name of a bridge device as argument. Note that
529 --network-bridge= implies --network-veth. If this option is used,
530 the host side of the Ethernet link will use the "vb-" prefix
531 instead of "ve-". Regardless of the used naming prefix the same
532 network interface name length limits imposed by Linux apply, along
533 with the complications this creates (for details see above).
534 --network-zone=
536 Creates a virtual Ethernet link ("veth") to the container and adds
537 it to an automatically managed Ethernet bridge interface. The
538 bridge interface is named after the passed argument, prefixed with
539 "vz-". The bridge interface is automatically created when the first
540 container configured for its name is started, and is automatically
541 removed when the last container configured for its name exits.
542 Hence, each bridge interface configured this way exists only as
543 long as there's at least one container referencing it running. This
544 option is very similar to --network-bridge=, besides this automatic
545 creation/removal of the bridge device.
546 This setting makes it easy to place multiple related containers on
548 a common, virtual Ethernet-based broadcast domain, here called a
549 "zone". Each container may only be part of one zone, but each zone
550 may contain any number of containers. Each zone is referenced by
551 its name. Names may be chosen freely (as long as they form valid
552 network interface names when prefixed with "vz-"), and it is
553 sufficient to pass the same name to the --network-zone= switch of
554 the various concurrently running containers to join them in one
555 zone.
556 Note that systemd-networkd.service(8) includes by default a network
558 file /usr/lib/systemd/network/80-container-vz.network matching the
559 bridge interfaces created this way, which contains settings to
560 enable automatic address provisioning on the created virtual
561 network via DHCP, as well as automatic IP routing onto the host's
562 external network interfaces. Using --network-zone= is hence in most
563 cases fully automatic and sufficient to connect multiple local
564 containers in a joined broadcast domain to the host, with further
565 connectivity to the external network.
566 -p, --port=
568 If private networking is enabled, maps an IP port on the host onto
569 an IP port on the container. Takes a protocol specifier (either
570 "tcp" or "udp"), separated by a colon from a host port number in
571 the range 1 to 65535, separated by a colon from a container port
572 number in the range from 1 to 65535. The protocol specifier and its
573 separating colon may be omitted, in which case "tcp" is assumed.
574 The container port number and its colon may be omitted, in which
575 case the same port as the host port is implied. This option is only
576 supported if private networking is used, such as with
577 --network-veth, --network-zone= --network-bridge=.
578 -Z, --selinux-context=
580 Sets the SELinux security context to be used to label processes in
581 the container.
582 -L, --selinux-apifs-context=
584 Sets the SELinux security context to be used to label files in the
585 virtual API file systems in the container.
586 --capability=
588 List one or more additional capabilities to grant the container.
589 Takes a comma-separated list of capability names, see
590 capabilities(7) for more information. Note that the following
591 capabilities will be granted in any way: CAP_AUDIT_CONTROL,
592 CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
593 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE,
594 CAP_LINUX_IMMUTABLE, CAP_MKNOD, CAP_NET_BIND_SERVICE,
595 CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETFCAP, CAP_SETGID,
596 CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_BOOT,
597 CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_RESOURCE,
598 CAP_SYS_TTY_CONFIG. Also CAP_NET_ADMIN is retained if
599 --private-network is specified. If the special value "all" is
600 passed, all capabilities are retained.
601 --drop-capability=
603 Specify one or more additional capabilities to drop for the
604 container. This allows running the container with fewer
605 capabilities than the default (see above).
606 --no-new-privileges=
608 Takes a boolean argument. Specifies the value of the
609 PR_SET_NO_NEW_PRIVS flag for the container payload. Defaults to
610 off. When turned on the payload code of the container cannot
611 acquire new privileges, i.e. the "setuid" file bit as well as file
612 system capabilities will not have an effect anymore. See prctl(2)
613 for details about this flag.
614 --system-call-filter=
616 Alter the system call filter applied to containers. Takes a
617 space-separated list of system call names or group names (the
618 latter prefixed with "@", as listed by the syscall-filter command
619 of systemd-analyze(1)). Passed system calls will be permitted. The
620 list may optionally be prefixed by "~", in which case all listed
621 system calls are prohibited. If this command line option is used
622 multiple times the configured lists are combined. If both a
623 positive and a negative list (that is one system call list without
624 and one with the "~" prefix) are configured, the negative list
625 takes precedence over the positive list. Note that systemd-nspawn
626 always implements a system call whitelist (as opposed to a
627 blacklist), and this command line option hence adds or removes
628 entries from the default whitelist, depending on the "~" prefix.
629 Note that the applied system call filter is also altered implicitly
630 if additional capabilities are passed using the --capabilities=.
631 --rlimit=
633 Sets the specified POSIX resource limit for the container payload.
634 Expects an assignment of the form "LIMIT=SOFT:HARD" or
635 "LIMIT=VALUE", where LIMIT should refer to a resource limit type,
636 such as RLIMIT_NOFILE or RLIMIT_NICE. The SOFT and HARD fields
637 should refer to the numeric soft and hard resource limit values. If
638 the second form is used, VALUE may specify a value that is used
639 both as soft and hard limit. In place of a numeric value the
640 special string "infinity" may be used to turn off resource limiting
641 for the specific type of resource. This command line option may be
642 used multiple times to control limits on multiple limit types. If
643 used multiple times for the same limit type, the last use wins. For
644 details about resource limits see setrlimit(2). By default resource
645 limits for the container's init process (PID 1) are set to the same
646 values the Linux kernel originally passed to the host init system.
647 Note that some resource limits are enforced on resources counted
648 per user, in particular RLIMIT_NPROC. This means that unless user
649 namespacing is deployed (i.e. --private-users= is used, see
650 above), any limits set will be applied to the resource usage of the
651 same user on all local containers as well as the host. This means
652 particular care needs to be taken with these limits as they might
653 be triggered by possibly less trusted code. Example:
654 "--rlimit=RLIMIT_NOFILE=8192:16384".
655 --oom-score-adjust=
657 Changes the OOM ("Out Of Memory") score adjustment value for the
658 container payload. This controls /proc/self/oom_score_adj which
659 influences the preference with which this container is terminated
660 when memory becomes scarce. For details see proc(5). Takes an
661 integer in the range -1000...1000.
662 --cpu-affinity=
664 Controls the CPU affinity of the container payload. Takes a comma
665 separated list of CPU numbers or number ranges (the latter's start
666 and end value separated by dashes). See sched_setaffinity(2) for
667 details.
668 --kill-signal=
670 Specify the process signal to send to the container's PID 1 when
671 nspawn itself receives SIGTERM, in order to trigger an orderly
672 shutdown of the container. Defaults to SIGRTMIN+3 if --boot is used
673 (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly
674 shutdown). If --boot is not used and this option is not specified
675 the container's processes are terminated abrubtly via SIGKILL. For
676 a list of valid signals, see signal(7).
677 --link-journal=
679 Control whether the container's journal shall be made visible to
680 the host system. If enabled, allows viewing the container's journal
681 files from the host (but not vice versa). Takes one of "no",
682 "host", "try-host", "guest", "try-guest", "auto". If "no", the
683 journal is not linked. If "host", the journal files are stored on
684 the host file system (beneath /var/log/journal/machine-id) and the
685 subdirectory is bind-mounted into the container at the same
686 location. If "guest", the journal files are stored on the guest
687 file system (beneath /var/log/journal/machine-id) and the
688 subdirectory is symlinked into the host at the same location.
689 "try-host" and "try-guest" do the same but do not fail if the host
690 does not have persistent journaling enabled. If "auto" (the
691 default), and the right subdirectory of /var/log/journal exists, it
692 will be bind mounted into the container. If the subdirectory does
693 not exist, no linking is performed. Effectively, booting a
694 container once with "guest" or "host" will link the journal
695 persistently if further on the default of "auto" is used.
696 Note that --link-journal=try-guest is the default if the
698 systemd-nspawn@.service template unit file is used.
699 -j
701 Equivalent to --link-journal=try-guest.
702 --resolv-conf=
704 Configures how /etc/resolv.conf inside of the container (i.e. DNS
705 configuration synchronization from host to container) shall be
706 handled. Takes one of "off", "copy-host", "copy-static",
707 "bind-host", "bind-static", "delete" or "auto". If set to "off" the
708 /etc/resolv.conf file in the container is left as it is included in
709 the image, and neither modified nor bind mounted over. If set to
710 "copy-host", the /etc/resolv.conf file from the host is copied into
711 the container. Similar, if "bind-host" is used, the file is bind
712 mounted from the host into the container. If set to "copy-static"
713 the static resolv.conf file supplied with systemd-
714 resolved.service(8) is copied into the container, and
715 correspondingly "bind-static" bind mounts it there. If set to
716 "delete" the /etc/resolv.conf file in the container is deleted if
717 it exists. Finally, if set to "auto" the file is left as it is if
718 private networking is turned on (see --private-network). Otherwise,
719 if systemd-resolved.service is connectible its static resolv.conf
720 file is used, and if not the host's /etc/resolv.conf file is used.
721 In the latter cases the file is copied if the image is writable,
722 and bind mounted otherwise. It's recommended to use "copy" if the
723 container shall be able to make changes to the DNS configuration on
724 its own, deviating from the host's settings. Otherwise "bind" is
725 preferable, as it means direct changes to /etc/resolv.conf in the
726 container are not allowed, as it is a read-only bind mount (but
727 note that if the container has enough privileges, it might simply
728 go ahead and unmount the bind mount anyway). Note that both if the
729 file is bind mounted and if it is copied no further propagation of
730 configuration is generally done after the one-time early
731 initialization (this is because the file is usually updated through
732 copying and renaming). Defaults to "auto".
733 --timezone=
735 Configures how /etc/localtime inside of the container (i.e. local
736 timezone synchronization from host to container) shall be handled.
737 Takes one of "off", "copy", "bind", "symlink", "delete" or "auto".
738 If set to "off" the /etc/localtime file in the container is left as
739 it is included in the image, and neither modified nor bind mounted
740 over. If set to "copy" the /etc/localtime file of the host is
741 copied into the container. Similar, if "bind" is used, it is bind
742 mounted from the host into the container. If set to "symlink" a
743 symlink from /etc/localtime in the container is created pointing to
744 the matching the timezone file of the container that matches the
745 timezone setting on the host. If set to "delete" the file in the
746 container is deleted, should it exist. If set to "auto" and the
747 /etc/localtime file of the host is a symlink, then "symlink" mode
748 is used, and "copy" otherwise, except if the image is read-only in
749 which case "bind" is used instead. Defaults to "auto".
750 --read-only
752 Mount the root file system read-only for the container.
753 --bind=, --bind-ro=
755 Bind mount a file or directory from the host into the container.
756 Takes one of: a path argument — in which case the specified path
757 will be mounted from the host to the same path in the container, or
758 a colon-separated pair of paths — in which case the first specified
759 path is the source in the host, and the second path is the
760 destination in the container, or a colon-separated triple of source
761 path, destination path and mount options. The source path may
762 optionally be prefixed with a "+" character. If so, the source path
763 is taken relative to the image's root directory. This permits
764 setting up bind mounts within the container image. The source path
765 may be specified as empty string, in which case a temporary
766 directory below the host's /var/tmp directory is used. It is
767 automatically removed when the container is shut down. Mount
768 options are comma-separated and currently, only rbind and norbind
769 are allowed, controlling whether to create a recursive or a regular
770 bind mount. Defaults to "rbind". Backslash escapes are interpreted,
771 so "\:" may be used to embed colons in either path. This option may
772 be specified multiple times for creating multiple independent bind
773 mount points. The --bind-ro= option creates read-only bind mounts.
774 Note that when this option is used in combination with
776 --private-users, the resulting mount points will be owned by the
777 nobody user. That's because the mount and its files and directories
778 continue to be owned by the relevant host users and groups, which
779 do not exist in the container, and thus show up under the wildcard
780 UID 65534 (nobody). If such bind mounts are created, it is
781 recommended to make them read-only, using --bind-ro=.
782 --tmpfs=
784 Mount a tmpfs file system into the container. Takes a single
785 absolute path argument that specifies where to mount the tmpfs
786 instance to (in which case the directory access mode will be chosen
787 as 0755, owned by root/root), or optionally a colon-separated pair
788 of path and mount option string that is used for mounting (in which
789 case the kernel default for access mode and owner will be chosen,
790 unless otherwise specified). This option is particularly useful for
791 mounting directories such as /var as tmpfs, to allow state-less
792 systems, in particular when combined with --read-only. Backslash
793 escapes are interpreted in the path, so "\:" may be used to embed
794 colons in the path.
795 --overlay=, --overlay-ro=
797 Combine multiple directory trees into one overlay file system and
798 mount it into the container. Takes a list of colon-separated paths
799 to the directory trees to combine and the destination mount point.
800 Backslash escapes are interpreted in the paths, so "\:" may be used
802 to embed colons in the paths.
803 If three or more paths are specified, then the last specified path
805 is the destination mount point in the container, all paths
806 specified before refer to directory trees on the host and are
807 combined in the specified order into one overlay file system. The
808 left-most path is hence the lowest directory tree, the
809 second-to-last path the highest directory tree in the stacking
810 order. If --overlay-ro= is used instead of --overlay=, a read-only
811 overlay file system is created. If a writable overlay file system
812 is created, all changes made to it are written to the highest
813 directory tree in the stacking order, i.e. the second-to-last
814 specified.
815 If only two paths are specified, then the second specified path is
817 used both as the top-level directory tree in the stacking order as
818 seen from the host, as well as the mount point for the overlay file
819 system in the container. At least two paths have to be specified.
820 The source paths may optionally be prefixed with "+" character. If
822 so they are taken relative to the image's root directory. The
823 uppermost source path may also be specified as empty string, in
824 which case a temporary directory below the host's /var/tmp is used.
825 The directory is removed automatically when the container is shut
826 down. This behaviour is useful in order to make read-only container
827 directories writable while the container is running. For example,
828 use the "--overlay=+/var::/var" option in order to automatically
829 overlay a writable temporary directory on a read-only /var
830 directory.
831 For details about overlay file systems, see overlayfs.txt[4]. Note
833 that the semantics of overlay file systems are substantially
834 different from normal file systems, in particular regarding
835 reported device and inode information. Device and inode information
836 may change for a file while it is being written to, and processes
837 might see out-of-date versions of files at times. Note that this
838 switch automatically derives the "workdir=" mount option for the
839 overlay file system from the top-level directory tree, making it a
840 sibling of it. It is hence essential that the top-level directory
841 tree is not a mount point itself (since the working directory must
842 be on the same file system as the top-most directory tree). Also
843 note that the "lowerdir=" mount option receives the paths to stack
844 in the opposite order of this switch.
845 -E NAME=VALUE, --setenv=NAME=VALUE
847 Specifies an environment variable assignment to pass to the init
848 process in the container, in the format "NAME=VALUE". This may be
849 used to override the default variables or to set additional
850 variables. This parameter may be used more than once.
851 --register=
853 Controls whether the container is registered with systemd-
854 machined(8). Takes a boolean argument, which defaults to "yes".
855 This option should be enabled when the container runs a full
856 Operating System (more specifically: a system and service manager
857 as PID 1), and is useful to ensure that the container is accessible
858 via machinectl(1) and shown by tools such as ps(1). If the
859 container does not run a service manager, it is recommended to set
860 this option to "no".
861 --keep-unit
863 Instead of creating a transient scope unit to run the container in,
864 simply use the service or scope unit systemd-nspawn has been
865 invoked in. If --register=yes is set this unit is registered with
866 systemd-machined(8). This switch should be used if systemd-nspawn
867 is invoked from within a service unit, and the service unit's sole
868 purpose is to run a single systemd-nspawn container. This option is
869 not available if run from a user session.
870 Note that passing --keep-unit disables the effect of --slice= and
872 --property=. Use --keep-unit and --register=no in combination to
873 disable any kind of unit allocation or registration with
874 systemd-machined.
875 --personality=
877 Control the architecture ("personality") reported by uname(2) in
878 the container. Currently, only "x86" and "x86-64" are supported.
879 This is useful when running a 32-bit container on a 64-bit host. If
880 this setting is not used, the personality reported in the container
881 is the same as the one reported on the host.
882 -q, --quiet
884 Turns off any status output by the tool itself. When this switch is
885 used, the only output from nspawn will be the console output of the
886 container OS itself.
887 --volatile, --volatile=MODE
889 Boots the container in volatile mode. When no mode parameter is
890 passed or when mode is specified as yes, full volatile mode is
891 enabled. This means the root directory is mounted as a mostly
892 unpopulated "tmpfs" instance, and /usr from the OS tree is mounted
893 into it in read-only mode (the system thus starts up with read-only
894 OS image, but pristine state and configuration, any changes are
895 lost on shutdown). When the mode parameter is specified as state,
896 the OS tree is mounted read-only, but /var is mounted as a "tmpfs"
897 instance into it (the system thus starts up with read-only OS
898 resources and configuration, but pristine state, and any changes to
899 the latter are lost on shutdown). When the mode parameter is
900 specified as no (the default), the whole OS tree is made available
901 writable.
902 This option provides similar functionality for containers as the
904 "systemd.volatile=" kernel command line switch provides for host
905 systems. See kernel-command-line(7) for details.
906 Note that enabling this setting will only work correctly with
908 operating systems in the container that can boot up with only /usr
909 mounted, and are able to automatically populate /var, and also /etc
910 in case of "--volatile=yes".
911 --settings=MODE
913 Controls whether systemd-nspawn shall search for and use additional
914 per-container settings from .nspawn files. Takes a boolean or the
915 special values override or trusted.
916 If enabled (the default), a settings file named after the machine
918 (as specified with the --machine= setting, or derived from the
919 directory or image file name) with the suffix .nspawn is searched
920 in /etc/systemd/nspawn/ and /run/systemd/nspawn/. If it is found
921 there, its settings are read and used. If it is not found there, it
922 is subsequently searched in the same directory as the image file or
923 in the immediate parent of the root directory of the container. In
924 this case, if the file is found, its settings will be also read and
925 used, but potentially unsafe settings are ignored. Note that in
926 both these cases, settings on the command line take precedence over
927 the corresponding settings from loaded .nspawn files, if both are
928 specified. Unsafe settings are considered all settings that elevate
929 the container's privileges or grant access to additional resources
930 such as files or directories of the host. For details about the
931 format and contents of .nspawn files, consult systemd.nspawn(5).
932 If this option is set to override, the file is searched, read and
934 used the same way, however, the order of precedence is reversed:
935 settings read from the .nspawn file will take precedence over the
936 corresponding command line options, if both are specified.
937 If this option is set to trusted, the file is searched, read and
939 used the same way, but regardless of being found in
940 /etc/systemd/nspawn/, /run/systemd/nspawn/ or next to the image
941 file or container root directory, all settings will take effect,
942 however, command line arguments still take precedence over
943 corresponding settings.
944 If disabled, no .nspawn file is read and no settings except the
946 ones on the command line are in effect.
947 --notify-ready=
949 Configures support for notifications from the container's init
950 process. --notify-ready= takes a boolean (no and yes). With option
951 no systemd-nspawn notifies systemd with a "READY=1" message when
952 the init process is created. With option yes systemd-nspawn waits
953 for the "READY=1" message from the init process in the container
954 before sending its own to systemd. For more details about
955 notifications see sd_notify(3)).
956 -h, --help
958 Print a short help text and exit.
959 --version
961 Print a short version string and exit.
962
964 Example 1. Download a Fedora image and start a shell in it
965 # machinectl pull-raw --verify=no \
967 https://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.raw.xz
968 # systemd-nspawn -M Fedora-Cloud-Base-28-1.1.x86_64.raw
969 This downloads an image using machinectl(1) and opens a shell in it.
971 Example 2. Build and boot a minimal Fedora distribution in a container
973 # dnf -y --releasever=28 --installroot=/var/lib/machines/f28 \
975 --disablerepo='*' --enablerepo=fedora --enablerepo=updates install \
976 systemd passwd dnf fedora-release vim-minimal
977 # systemd-nspawn -bD /var/lib/machines/f28
978 This installs a minimal Fedora distribution into the directory
980 /var/lib/machines/f28 and then boots an OS in a namespace container in
981 it. Because the installation is located underneath the standard
982 /var/lib/machines/ directory, it is also possible to start the machine
983 using systemd-nspawn -M f28.
984 Example 3. Spawn a shell in a container of a minimal Debian unstable
986 distribution
987 # debootstrap unstable ~/debian-tree/
989 # systemd-nspawn -D ~/debian-tree/
990 This installs a minimal Debian unstable distribution into the directory
992 ~/debian-tree/ and then spawns a shell in a namespace container in it.
993 debootstrap supports Debian[6], Ubuntu[7], and Tanglu[8] out of the
995 box, so the same command can be used to install any of those. For other
996 distributions from the Debian family, a mirror has to be specified, see
997 debootstrap(8).
998 Example 4. Boot a minimal Arch Linux distribution in a container
1000 # pacstrap -c -d ~/arch-tree/ base
1002 # systemd-nspawn -bD ~/arch-tree/
1003 This installs a minimal Arch Linux distribution into the directory
1005 ~/arch-tree/ and then boots an OS in a namespace container in it.
1006 Example 5. Install the OpenSUSE Tumbleweed rolling distribution
1008 # zypper --root=/var/lib/machines/tumbleweed ar -c \
1010 https://download.opensuse.org/tumbleweed/repo/oss tumbleweed
1011 # zypper --root=/var/lib/machines/tumbleweed refresh
1012 # zypper --root=/var/lib/machines/tumbleweed install --no-recommends \
1013 systemd shadow zypper openSUSE-release vim
1014 # systemd-nspawn -M tumbleweed passwd root
1015 # systemd-nspawn -M tumbleweed -b
1016 Example 6. Boot into an ephemeral snapshot of the host system
1018 # systemd-nspawn -D / -xb
1020 This runs a copy of the host system in a snapshot which is removed
1022 immediately when the container exits. All file system changes made
1023 during runtime will be lost on shutdown, hence.
1024 Example 7. Run a container with SELinux sandbox security contexts
1026 # chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
1028 # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \
1029 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh
1030 Example 8. Run a container with an OSTree deployment
1032 # systemd-nspawn -b -i ~/image.raw \
1034 --pivot-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \
1035 --bind=+/sysroot/ostree/deploy/$OS/var:/var
1036
1038 The exit code of the program executed in the container is returned.
1039
1041 systemd(1), systemd.nspawn(5), chroot(1), dnf(8), debootstrap(8),
1042 pacman(8), zypper(8), systemd.slice(5), machinectl(1), btrfs(8)
1043
1045 1. Container Interface
1046 https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface
1047 2. Discoverable Partitions Specification
1049 https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/
1050 3. OSTree
1052 https://ostree.readthedocs.io/en/latest/
1053 4. overlayfs.txt
1055 https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt
1056 5. Fedora
1058 https://getfedora.org
1059 6. Debian
1061 https://www.debian.org
1062 7. Ubuntu
1064 https://www.ubuntu.com
1065 8. Tanglu
1067 https://www.tanglu.org
1068 9. Arch Linux
1070 https://www.archlinux.org
1071 10. OpenSUSE Tumbleweed
1073 https://software.opensuse.org/distributions/tumbleweed
1074systemd 241 SYSTEMD-NSPAWN(1)