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 --boot [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 may be invoked on any directory tree containing an
22 operating system tree, using the --directory= command line option. By
23 using the --machine= option an OS tree is automatically searched for in
24 a couple of locations, most importantly in /var/lib/machines, the
25 suggested directory to place container images installed on the 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 --network-veth-extra=
503 Adds an additional virtual Ethernet link between host and
504 container. Takes a colon-separated pair of host interface name and
505 container interface name. The latter may be omitted in which case
506 the container and host sides will be assigned the same name. This
507 switch is independent of --network-veth, and — in contrast — may be
508 used multiple times, and allows configuration of the network
509 interface names. Note that --network-bridge= has no effect on
510 interfaces created with --network-veth-extra=.
511 --network-bridge=
513 Adds the host side of the Ethernet link created with --network-veth
514 to the specified Ethernet bridge interface. Expects a valid network
515 interface name of a bridge device as argument. Note that
516 --network-bridge= implies --network-veth. If this option is used,
517 the host side of the Ethernet link will use the "vb-" prefix
518 instead of "ve-".
519 --network-zone=
521 Creates a virtual Ethernet link ("veth") to the container and adds
522 it to an automatically managed Ethernet bridge interface. The
523 bridge interface is named after the passed argument, prefixed with
524 "vz-". The bridge interface is automatically created when the first
525 container configured for its name is started, and is automatically
526 removed when the last container configured for its name exits.
527 Hence, each bridge interface configured this way exists only as
528 long as there's at least one container referencing it running. This
529 option is very similar to --network-bridge=, besides this automatic
530 creation/removal of the bridge device.
531 This setting makes it easy to place multiple related containers on
533 a common, virtual Ethernet-based broadcast domain, here called a
534 "zone". Each container may only be part of one zone, but each zone
535 may contain any number of containers. Each zone is referenced by
536 its name. Names may be chosen freely (as long as they form valid
537 network interface names when prefixed with "vz-"), and it is
538 sufficient to pass the same name to the --network-zone= switch of
539 the various concurrently running containers to join them in one
540 zone.
541 Note that systemd-networkd.service(8) includes by default a network
543 file /usr/lib/systemd/network/80-container-vz.network matching the
544 bridge interfaces created this way, which contains settings to
545 enable automatic address provisioning on the created virtual
546 network via DHCP, as well as automatic IP routing onto the host's
547 external network interfaces. Using --network-zone= is hence in most
548 cases fully automatic and sufficient to connect multiple local
549 containers in a joined broadcast domain to the host, with further
550 connectivity to the external network.
551 -p, --port=
553 If private networking is enabled, maps an IP port on the host onto
554 an IP port on the container. Takes a protocol specifier (either
555 "tcp" or "udp"), separated by a colon from a host port number in
556 the range 1 to 65535, separated by a colon from a container port
557 number in the range from 1 to 65535. The protocol specifier and its
558 separating colon may be omitted, in which case "tcp" is assumed.
559 The container port number and its colon may be omitted, in which
560 case the same port as the host port is implied. This option is only
561 supported if private networking is used, such as with
562 --network-veth, --network-zone= --network-bridge=.
563 -Z, --selinux-context=
565 Sets the SELinux security context to be used to label processes in
566 the container.
567 -L, --selinux-apifs-context=
569 Sets the SELinux security context to be used to label files in the
570 virtual API file systems in the container.
571 --capability=
573 List one or more additional capabilities to grant the container.
574 Takes a comma-separated list of capability names, see
575 capabilities(7) for more information. Note that the following
576 capabilities will be granted in any way: CAP_AUDIT_CONTROL,
577 CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
578 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE,
579 CAP_LINUX_IMMUTABLE, CAP_MKNOD, CAP_NET_BIND_SERVICE,
580 CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETFCAP, CAP_SETGID,
581 CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_BOOT,
582 CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_RESOURCE,
583 CAP_SYS_TTY_CONFIG. Also CAP_NET_ADMIN is retained if
584 --private-network is specified. If the special value "all" is
585 passed, all capabilities are retained.
586 --drop-capability=
588 Specify one or more additional capabilities to drop for the
589 container. This allows running the container with fewer
590 capabilities than the default (see above).
591 --no-new-privileges=
593 Takes a boolean argument. Specifies the value of the
594 PR_SET_NO_NEW_PRIVS flag for the container payload. Defaults to
595 off. When turned on the payload code of the container cannot
596 acquire new privileges, i.e. the "setuid" file bit as well as file
597 system capabilities will not have an effect anymore. See prctl(2)
598 for details about this flag.
599 --system-call-filter=
601 Alter the system call filter applied to containers. Takes a
602 space-separated list of system call names or group names (the
603 latter prefixed with "@", as listed by the syscall-filter command
604 of systemd-analyze(1)). Passed system calls will be permitted. The
605 list may optionally be prefixed by "~", in which case all listed
606 system calls are prohibited. If this command line option is used
607 multiple times the configured lists are combined. If both a
608 positive and a negative list (that is one system call list without
609 and one with the "~" prefix) are configured, the negative list
610 takes precedence over the positive list. Note that systemd-nspawn
611 always implements a system call whitelist (as opposed to a
612 blacklist), and this command line option hence adds or removes
613 entries from the default whitelist, depending on the "~" prefix.
614 Note that the applied system call filter is also altered implicitly
615 if additional capabilities are passed using the --capabilities=.
616 --rlimit=
618 Sets the specified POSIX resource limit for the container payload.
619 Expects an assignment of the form "LIMIT=SOFT:HARD" or
620 "LIMIT=VALUE", where LIMIT should refer to a resource limit type,
621 such as RLIMIT_NOFILE or RLIMIT_NICE. The SOFT and HARD fields
622 should refer to the numeric soft and hard resource limit values. If
623 the second form is used, VALUE may specify a value that is used
624 both as soft and hard limit. In place of a numeric value the
625 special string "infinity" may be used to turn off resource limiting
626 for the specific type of resource. This command line option may be
627 used multiple times to control limits on multiple limit types. If
628 used multiple times for the same limit type, the last use wins. For
629 details about resource limits see setrlimit(2). By default resource
630 limits for the container's init process (PID 1) are set to the same
631 values the Linux kernel originally passed to the host init system.
632 Note that some resource limits are enforced on resources counted
633 per user, in particular RLIMIT_NPROC. This means that unless user
634 namespacing is deployed (i.e. --private-users= is used, see
635 above), any limits set will be applied to the resource usage of the
636 same user on all local containers as well as the host. This means
637 particular care needs to be taken with these limits as they might
638 be triggered by possibly less trusted code. Example:
639 "--rlimit=RLIMIT_NOFILE=8192:16384".
640 --oom-score-adjust=
642 Changes the OOM ("Out Of Memory") score adjustment value for the
643 container payload. This controls /proc/self/oom_score_adj which
644 influences the preference with which this container is terminated
645 when memory becomes scarce. For details see proc(5). Takes an
646 integer in the range -1000...1000.
647 --cpu-affinity=
649 Controls the CPU affinity of the container payload. Takes a comma
650 separated list of CPU numbers or number ranges (the latter's start
651 and end value separated by dashes). See sched_setaffinity(2) for
652 details.
653 --kill-signal=
655 Specify the process signal to send to the container's PID 1 when
656 nspawn itself receives SIGTERM, in order to trigger an orderly
657 shutdown of the container. Defaults to SIGRTMIN+3 if --boot is used
658 (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly
659 shutdown). If --boot is not used and this option is not specified
660 the container's processes are terminated abrubtly via SIGKILL. For
661 a list of valid signals, see signal(7).
662 --link-journal=
664 Control whether the container's journal shall be made visible to
665 the host system. If enabled, allows viewing the container's journal
666 files from the host (but not vice versa). Takes one of "no",
667 "host", "try-host", "guest", "try-guest", "auto". If "no", the
668 journal is not linked. If "host", the journal files are stored on
669 the host file system (beneath /var/log/journal/machine-id) and the
670 subdirectory is bind-mounted into the container at the same
671 location. If "guest", the journal files are stored on the guest
672 file system (beneath /var/log/journal/machine-id) and the
673 subdirectory is symlinked into the host at the same location.
674 "try-host" and "try-guest" do the same but do not fail if the host
675 does not have persistent journaling enabled. If "auto" (the
676 default), and the right subdirectory of /var/log/journal exists, it
677 will be bind mounted into the container. If the subdirectory does
678 not exist, no linking is performed. Effectively, booting a
679 container once with "guest" or "host" will link the journal
680 persistently if further on the default of "auto" is used.
681 Note that --link-journal=try-guest is the default if the
683 systemd-nspawn@.service template unit file is used.
684 -j
686 Equivalent to --link-journal=try-guest.
687 --resolv-conf=
689 Configures how /etc/resolv.conf inside of the container (i.e. DNS
690 configuration synchronization from host to container) shall be
691 handled. Takes one of "off", "copy-host", "copy-static",
692 "bind-host", "bind-static", "delete" or "auto". If set to "off" the
693 /etc/resolv.conf file in the container is left as it is included in
694 the image, and neither modified nor bind mounted over. If set to
695 "copy-host", the /etc/resolv.conf file from the host is copied into
696 the container. Similar, if "bind-host" is used, the file is bind
697 mounted from the host into the container. If set to "copy-static"
698 the static resolv.conf file supplied with systemd-
699 resolved.service(8) is copied into the container, and
700 correspondingly "bind-static" bind mounts it there. If set to
701 "delete" the /etc/resolv.conf file in the container is deleted if
702 it exists. Finally, if set to "auto" the file is left as it is if
703 private networking is turned on (see --private-network). Otherwise,
704 if systemd-resolved.service is connectible its static resolv.conf
705 file is used, and if not the host's /etc/resolv.conf file is used.
706 In the latter cases the file is copied if the image is writable,
707 and bind mounted otherwise. It's recommended to use "copy" if the
708 container shall be able to make changes to the DNS configuration on
709 its own, deviating from the host's settings. Otherwise "bind" is
710 preferable, as it means direct changes to /etc/resolv.conf in the
711 container are not allowed, as it is a read-only bind mount (but
712 note that if the container has enough privileges, it might simply
713 go ahead and unmount the bind mount anyway). Note that both if the
714 file is bind mounted and if it is copied no further propagation of
715 configuration is generally done after the one-time early
716 initialization (this is because the file is usually updated through
717 copying and renaming). Defaults to "auto".
718 --timezone=
720 Configures how /etc/localtime inside of the container (i.e. local
721 timezone synchronization from host to container) shall be handled.
722 Takes one of "off", "copy", "bind", "symlink", "delete" or "auto".
723 If set to "off" the /etc/localtime file in the container is left as
724 it is included in the image, and neither modified nor bind mounted
725 over. If set to "copy" the /etc/localtime file of the host is
726 copied into the container. Similar, if "bind" is used, it is bind
727 mounted from the host into the container. If set to "symlink" a
728 symlink from /etc/localtime in the container is created pointing to
729 the matching the timezone file of the container that matches the
730 timezone setting on the host. If set to "delete" the file in the
731 container is deleted, should it exist. If set to "auto" and the
732 /etc/localtime file of the host is a symlink, then "symlink" mode
733 is used, and "copy" otherwise, except if the image is read-only in
734 which case "bind" is used instead. Defaults to "auto".
735 --read-only
737 Mount the root file system read-only for the container.
738 --bind=, --bind-ro=
740 Bind mount a file or directory from the host into the container.
741 Takes one of: a path argument — in which case the specified path
742 will be mounted from the host to the same path in the container, or
743 a colon-separated pair of paths — in which case the first specified
744 path is the source in the host, and the second path is the
745 destination in the container, or a colon-separated triple of source
746 path, destination path and mount options. The source path may
747 optionally be prefixed with a "+" character. If so, the source path
748 is taken relative to the image's root directory. This permits
749 setting up bind mounts within the container image. The source path
750 may be specified as empty string, in which case a temporary
751 directory below the host's /var/tmp directory is used. It is
752 automatically removed when the container is shut down. Mount
753 options are comma-separated and currently, only rbind and norbind
754 are allowed, controlling whether to create a recursive or a regular
755 bind mount. Defaults to "rbind". Backslash escapes are interpreted,
756 so "\:" may be used to embed colons in either path. This option may
757 be specified multiple times for creating multiple independent bind
758 mount points. The --bind-ro= option creates read-only bind mounts.
759 Note that when this option is used in combination with
761 --private-users, the resulting mount points will be owned by the
762 nobody user. That's because the mount and its files and directories
763 continue to be owned by the relevant host users and groups, which
764 do not exist in the container, and thus show up under the wildcard
765 UID 65534 (nobody). If such bind mounts are created, it is
766 recommended to make them read-only, using --bind-ro=.
767 --tmpfs=
769 Mount a tmpfs file system into the container. Takes a single
770 absolute path argument that specifies where to mount the tmpfs
771 instance to (in which case the directory access mode will be chosen
772 as 0755, owned by root/root), or optionally a colon-separated pair
773 of path and mount option string that is used for mounting (in which
774 case the kernel default for access mode and owner will be chosen,
775 unless otherwise specified). This option is particularly useful for
776 mounting directories such as /var as tmpfs, to allow state-less
777 systems, in particular when combined with --read-only. Backslash
778 escapes are interpreted in the path, so "\:" may be used to embed
779 colons in the path.
780 --overlay=, --overlay-ro=
782 Combine multiple directory trees into one overlay file system and
783 mount it into the container. Takes a list of colon-separated paths
784 to the directory trees to combine and the destination mount point.
785 Backslash escapes are interpreted in the paths, so "\:" may be used
787 to embed colons in the paths.
788 If three or more paths are specified, then the last specified path
790 is the destination mount point in the container, all paths
791 specified before refer to directory trees on the host and are
792 combined in the specified order into one overlay file system. The
793 left-most path is hence the lowest directory tree, the
794 second-to-last path the highest directory tree in the stacking
795 order. If --overlay-ro= is used instead of --overlay=, a read-only
796 overlay file system is created. If a writable overlay file system
797 is created, all changes made to it are written to the highest
798 directory tree in the stacking order, i.e. the second-to-last
799 specified.
800 If only two paths are specified, then the second specified path is
802 used both as the top-level directory tree in the stacking order as
803 seen from the host, as well as the mount point for the overlay file
804 system in the container. At least two paths have to be specified.
805 The source paths may optionally be prefixed with "+" character. If
807 so they are taken relative to the image's root directory. The
808 uppermost source path may also be specified as empty string, in
809 which case a temporary directory below the host's /var/tmp is used.
810 The directory is removed automatically when the container is shut
811 down. This behaviour is useful in order to make read-only container
812 directories writable while the container is running. For example,
813 use the "--overlay=+/var::/var" option in order to automatically
814 overlay a writable temporary directory on a read-only /var
815 directory.
816 For details about overlay file systems, see overlayfs.txt[4]. Note
818 that the semantics of overlay file systems are substantially
819 different from normal file systems, in particular regarding
820 reported device and inode information. Device and inode information
821 may change for a file while it is being written to, and processes
822 might see out-of-date versions of files at times. Note that this
823 switch automatically derives the "workdir=" mount option for the
824 overlay file system from the top-level directory tree, making it a
825 sibling of it. It is hence essential that the top-level directory
826 tree is not a mount point itself (since the working directory must
827 be on the same file system as the top-most directory tree). Also
828 note that the "lowerdir=" mount option receives the paths to stack
829 in the opposite order of this switch.
830 -E NAME=VALUE, --setenv=NAME=VALUE
832 Specifies an environment variable assignment to pass to the init
833 process in the container, in the format "NAME=VALUE". This may be
834 used to override the default variables or to set additional
835 variables. This parameter may be used more than once.
836 --register=
838 Controls whether the container is registered with systemd-
839 machined(8). Takes a boolean argument, which defaults to "yes".
840 This option should be enabled when the container runs a full
841 Operating System (more specifically: a system and service manager
842 as PID 1), and is useful to ensure that the container is accessible
843 via machinectl(1) and shown by tools such as ps(1). If the
844 container does not run a service manager, it is recommended to set
845 this option to "no".
846 --keep-unit
848 Instead of creating a transient scope unit to run the container in,
849 simply use the service or scope unit systemd-nspawn has been
850 invoked in. If --register=yes is set this unit is registered with
851 systemd-machined(8). This switch should be used if systemd-nspawn
852 is invoked from within a service unit, and the service unit's sole
853 purpose is to run a single systemd-nspawn container. This option is
854 not available if run from a user session.
855 Note that passing --keep-unit disables the effect of --slice= and
857 --property=. Use --keep-unit and --register=no in combination to
858 disable any kind of unit allocation or registration with
859 systemd-machined.
860 --personality=
862 Control the architecture ("personality") reported by uname(2) in
863 the container. Currently, only "x86" and "x86-64" are supported.
864 This is useful when running a 32-bit container on a 64-bit host. If
865 this setting is not used, the personality reported in the container
866 is the same as the one reported on the host.
867 -q, --quiet
869 Turns off any status output by the tool itself. When this switch is
870 used, the only output from nspawn will be the console output of the
871 container OS itself.
872 --volatile, --volatile=MODE
874 Boots the container in volatile mode. When no mode parameter is
875 passed or when mode is specified as yes, full volatile mode is
876 enabled. This means the root directory is mounted as a mostly
877 unpopulated "tmpfs" instance, and /usr from the OS tree is mounted
878 into it in read-only mode (the system thus starts up with read-only
879 OS image, but pristine state and configuration, any changes are
880 lost on shutdown). When the mode parameter is specified as state,
881 the OS tree is mounted read-only, but /var is mounted as a "tmpfs"
882 instance into it (the system thus starts up with read-only OS
883 resources and configuration, but pristine state, and any changes to
884 the latter are lost on shutdown). When the mode parameter is
885 specified as no (the default), the whole OS tree is made available
886 writable.
887 This option provides similar functionality for containers as the
889 "systemd.volatile=" kernel command line switch provides for host
890 systems. See kernel-command-line(7) for details.
891 Note that enabling this setting will only work correctly with
893 operating systems in the container that can boot up with only /usr
894 mounted, and are able to automatically populate /var, and also /etc
895 in case of "--volatile=yes".
896 --settings=MODE
898 Controls whether systemd-nspawn shall search for and use additional
899 per-container settings from .nspawn files. Takes a boolean or the
900 special values override or trusted.
901 If enabled (the default), a settings file named after the machine
903 (as specified with the --machine= setting, or derived from the
904 directory or image file name) with the suffix .nspawn is searched
905 in /etc/systemd/nspawn/ and /run/systemd/nspawn/. If it is found
906 there, its settings are read and used. If it is not found there, it
907 is subsequently searched in the same directory as the image file or
908 in the immediate parent of the root directory of the container. In
909 this case, if the file is found, its settings will be also read and
910 used, but potentially unsafe settings are ignored. Note that in
911 both these cases, settings on the command line take precedence over
912 the corresponding settings from loaded .nspawn files, if both are
913 specified. Unsafe settings are considered all settings that elevate
914 the container's privileges or grant access to additional resources
915 such as files or directories of the host. For details about the
916 format and contents of .nspawn files, consult systemd.nspawn(5).
917 If this option is set to override, the file is searched, read and
919 used the same way, however, the order of precedence is reversed:
920 settings read from the .nspawn file will take precedence over the
921 corresponding command line options, if both are specified.
922 If this option is set to trusted, the file is searched, read and
924 used the same way, but regardless of being found in
925 /etc/systemd/nspawn/, /run/systemd/nspawn/ or next to the image
926 file or container root directory, all settings will take effect,
927 however, command line arguments still take precedence over
928 corresponding settings.
929 If disabled, no .nspawn file is read and no settings except the
931 ones on the command line are in effect.
932 --notify-ready=
934 Configures support for notifications from the container's init
935 process. --notify-ready= takes a boolean (no and yes). With option
936 no systemd-nspawn notifies systemd with a "READY=1" message when
937 the init process is created. With option yes systemd-nspawn waits
938 for the "READY=1" message from the init process in the container
939 before sending its own to systemd. For more details about
940 notifications see sd_notify(3)).
941 -h, --help
943 Print a short help text and exit.
944 --version
946 Print a short version string and exit.
947
949 Example 1. Download a Fedora image and start a shell in it
950 # machinectl pull-raw --verify=no \
952 https://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.raw.xz
953 # systemd-nspawn -M Fedora-Cloud-Base-28-1.1.x86_64.raw
954 This downloads an image using machinectl(1) and opens a shell in it.
956 Example 2. Build and boot a minimal Fedora distribution in a container
958 # dnf -y --releasever=28 --installroot=/var/lib/machines/f28 \
960 --disablerepo='*' --enablerepo=fedora --enablerepo=updates install \
961 systemd passwd dnf fedora-release vim-minimal
962 # systemd-nspawn -bD /var/lib/machines/f28
963 This installs a minimal Fedora distribution into the directory
965 /var/lib/machines/f28 and then boots an OS in a namespace container in
966 it. Because the installation is located underneath the standard
967 /var/lib/machines/ directory, it is also possible to start the machine
968 using systemd-nspawn -M f28.
969 Example 3. Spawn a shell in a container of a minimal Debian unstable
971 distribution
972 # debootstrap unstable ~/debian-tree/
974 # systemd-nspawn -D ~/debian-tree/
975 This installs a minimal Debian unstable distribution into the directory
977 ~/debian-tree/ and then spawns a shell in a namespace container in it.
978 debootstrap supports Debian[6], Ubuntu[7], and Tanglu[8] out of the
980 box, so the same command can be used to install any of those. For other
981 distributions from the Debian family, a mirror has to be specified, see
982 debootstrap(8).
983 Example 4. Boot a minimal Arch Linux distribution in a container
985 # pacstrap -c -d ~/arch-tree/ base
987 # systemd-nspawn -bD ~/arch-tree/
988 This installs a minimal Arch Linux distribution into the directory
990 ~/arch-tree/ and then boots an OS in a namespace container in it.
991 Example 5. Install the OpenSUSE Tumbleweed rolling distribution
993 # zypper --root=/var/lib/machines/tumbleweed ar -c \
995 https://download.opensuse.org/tumbleweed/repo/oss tumbleweed
996 # zypper --root=/var/lib/machines/tumbleweed refresh
997 # zypper --root=/var/lib/machines/tumbleweed install --no-recommends \
998 systemd shadow zypper openSUSE-release vim
999 # systemd-nspawn -M tumbleweed passwd root
1000 # systemd-nspawn -M tumbleweed -b
1001 Example 6. Boot into an ephemeral snapshot of the host system
1003 # systemd-nspawn -D / -xb
1005 This runs a copy of the host system in a snapshot which is removed
1007 immediately when the container exits. All file system changes made
1008 during runtime will be lost on shutdown, hence.
1009 Example 7. Run a container with SELinux sandbox security contexts
1011 # chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
1013 # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \
1014 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh
1015 Example 8. Run a container with an OSTree deployment
1017 # systemd-nspawn -b -i ~/image.raw \
1019 --pivot-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \
1020 --bind=+/sysroot/ostree/deploy/$OS/var:/var
1021
1023 The exit code of the program executed in the container is returned.
1024
1026 systemd(1), systemd.nspawn(5), chroot(1), dnf(8), debootstrap(8),
1027 pacman(8), zypper(8), systemd.slice(5), machinectl(1), btrfs(8)
1028
1030 1. Container Interface
1031 https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface
1032 2. Discoverable Partitions Specification
1034 https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/
1035 3. OSTree
1037 https://ostree.readthedocs.io/en/latest/
1038 4. overlayfs.txt
1040 https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt
1041 5. Fedora
1043 https://getfedora.org
1044 6. Debian
1046 https://www.debian.org
1047 7. Ubuntu
1049 https://www.ubuntu.com
1050 8. Tanglu
1052 https://www.tanglu.org
1053 9. Arch Linux
1055 https://www.archlinux.org
1056 10. OpenSUSE Tumbleweed
1058 https://software.opensuse.org/distributions/tumbleweed
1059systemd 239 SYSTEMD-NSPAWN(1)