1SYSTEMD-NSPAWN(1)               systemd-nspawn               SYSTEMD-NSPAWN(1)
2
3
4

NAME

6       systemd-nspawn - Spawn a command or OS in a light-weight container
7

SYNOPSIS

9       systemd-nspawn [OPTIONS...] [COMMAND [ARGS...]]
10
11       systemd-nspawn --boot [OPTIONS...] [ARGS...]
12

DESCRIPTION

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
20       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
27       In contrast to chroot(1) systemd-nspawn may be used to boot full
28       Linux-based operating systems in a container.
29
30       systemd-nspawn limits access to various kernel interfaces in the
31       container to read-only, such as /sys/, /proc/sys/ or /sys/fs/selinux/.
32       The host's network interfaces and the system clock may not be changed
33       from within the container. Device nodes may not be created. The host
34       system cannot be rebooted and kernel modules may not be loaded from
35       within the container.
36
37       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
42       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
48       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
60       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
65       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
72       Note that systemd-nspawn will mount file systems private to the
73       container to /dev/, /run/ and similar. These will not be visible
74       outside of the container, and their contents will be lost when the
75       container exits.
76
77       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
84       systemd-nspawn implements the Container Interface[1] specification.
85
86       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

OPTIONS

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
97       The following options are understood:
98
99       -q, --quiet
100           Turns off any status output by the tool itself. When this switch is
101           used, the only output from nspawn will be the console output of the
102           container OS itself.
103
104       --settings=MODE
105           Controls whether systemd-nspawn shall search for and use additional
106           per-container settings from .nspawn files. Takes a boolean or the
107           special values override or trusted.
108
109           If enabled (the default), a settings file named after the machine
110           (as specified with the --machine= setting, or derived from the
111           directory or image file name) with the suffix .nspawn is searched
112           in /etc/systemd/nspawn/ and /run/systemd/nspawn/. If it is found
113           there, its settings are read and used. If it is not found there, it
114           is subsequently searched in the same directory as the image file or
115           in the immediate parent of the root directory of the container. In
116           this case, if the file is found, its settings will be also read and
117           used, but potentially unsafe settings are ignored. Note that in
118           both these cases, settings on the command line take precedence over
119           the corresponding settings from loaded .nspawn files, if both are
120           specified. Unsafe settings are considered all settings that elevate
121           the container's privileges or grant access to additional resources
122           such as files or directories of the host. For details about the
123           format and contents of .nspawn files, consult systemd.nspawn(5).
124
125           If this option is set to override, the file is searched, read and
126           used the same way, however, the order of precedence is reversed:
127           settings read from the .nspawn file will take precedence over the
128           corresponding command line options, if both are specified.
129
130           If this option is set to trusted, the file is searched, read and
131           used the same way, but regardless of being found in
132           /etc/systemd/nspawn/, /run/systemd/nspawn/ or next to the image
133           file or container root directory, all settings will take effect,
134           however, command line arguments still take precedence over
135           corresponding settings.
136
137           If disabled, no .nspawn file is read and no settings except the
138           ones on the command line are in effect.
139
140   Image Options
141       -D, --directory=
142           Directory to use as file system root for the container.
143
144           If neither --directory=, nor --image= is specified the directory is
145           determined by searching for a directory named the same as the
146           machine name specified with --machine=. See machinectl(1) section
147           "Files and Directories" for the precise search path.
148
149           If neither --directory=, --image=, nor --machine= are specified,
150           the current directory will be used. May not be specified together
151           with --image=.
152
153       --template=
154           Directory or "btrfs" subvolume to use as template for the
155           container's root directory. If this is specified and the
156           container's root directory (as configured by --directory=) does not
157           yet exist it is created as "btrfs" snapshot (if supported) or plain
158           directory (otherwise) and populated from this template tree.
159           Ideally, the specified template path refers to the root of a
160           "btrfs" subvolume, in which case a simple copy-on-write snapshot is
161           taken, and populating the root directory is instant. If the
162           specified template path does not refer to the root of a "btrfs"
163           subvolume (or not even to a "btrfs" file system at all), the tree
164           is copied (though possibly in a 'reflink' copy-on-write scheme — if
165           the file system supports that), which can be substantially more
166           time-consuming. Note that the snapshot taken is of the specified
167           directory or subvolume, including all subdirectories and subvolumes
168           below it, but excluding any sub-mounts. May not be specified
169           together with --image= or --ephemeral.
170
171           Note that this switch leaves hostname, machine ID and all other
172           settings that could identify the instance unmodified.
173
174       -x, --ephemeral
175           If specified, the container is run with a temporary snapshot of its
176           file system that is removed immediately when the container
177           terminates. May not be specified together with --template=.
178
179           Note that this switch leaves hostname, machine ID and all other
180           settings that could identify the instance unmodified. Please note
181           that — as with --template= — taking the temporary snapshot is more
182           efficient on file systems that support subvolume snapshots or
183           'reflinks' natively ("btrfs" or new "xfs") than on more traditional
184           file systems that do not ("ext4"). Note that the snapshot taken is
185           of the specified directory or subvolume, including all
186           subdirectories and subvolumes below it, but excluding any
187           sub-mounts.
188
189           With this option no modifications of the container image are
190           retained. Use --volatile= (described below) for other mechanisms to
191           restrict persistency of container images during runtime.
192
193       -i, --image=
194           Disk image to mount the root directory for the container from.
195           Takes a path to a regular file or to a block device node. The file
196           or block device must contain either:
197
198           •   An MBR partition table with a single partition of type 0x83
199               that is marked bootable.
200
201           •   A GUID partition table (GPT) with a single partition of type
202               0fc63daf-8483-4772-8e79-3d69d8477de4.
203
204           •   A GUID partition table (GPT) with a marked root partition which
205               is mounted as the root directory of the container. Optionally,
206               GPT images may contain a home and/or a server data partition
207               which are mounted to the appropriate places in the container.
208               All these partitions must be identified by the partition types
209               defined by the Discoverable Partitions Specification[2].
210
211           •   No partition table, and a single file system spanning the whole
212               image.
213
214           On GPT images, if an EFI System Partition (ESP) is discovered, it
215           is automatically mounted to /efi (or /boot as fallback) in case a
216           directory by this name exists and is empty.
217
218           Partitions encrypted with LUKS are automatically decrypted. Also,
219           on GPT images dm-verity data integrity hash partitions are set up
220           if the root hash for them is specified using the --root-hash=
221           option.
222
223           Single file system images (i.e. file systems without a surrounding
224           partition table) can be opened using dm-verity if the integrity
225           data is passed using the --root-hash= and --verity-data= (and
226           optionally --root-hash-sig=) options.
227
228           Any other partitions, such as foreign partitions or swap partitions
229           are not mounted. May not be specified together with --directory=,
230           --template=.
231
232       --oci-bundle=
233           Takes the path to an OCI runtime bundle to invoke, as specified in
234           the OCI Runtime Specification[3]. In this case no .nspawn file is
235           loaded, and the root directory and various settings are read from
236           the OCI runtime JSON data (but data passed on the command line
237           takes precedence).
238
239       --read-only
240           Mount the container's root file system (and any other file systems
241           container in the container image) read-only. This has no effect on
242           additional mounts made with --bind=, --tmpfs= and similar options.
243           This mode is implied if the container image file or directory is
244           marked read-only itself. It is also implied if --volatile= is used.
245           In this case the container image on disk is strictly read-only,
246           while changes are permitted but kept non-persistently in memory
247           only. For further details, see below.
248
249       --volatile, --volatile=MODE
250           Boots the container in volatile mode. When no mode parameter is
251           passed or when mode is specified as yes, full volatile mode is
252           enabled. This means the root directory is mounted as a mostly
253           unpopulated "tmpfs" instance, and /usr/ from the OS tree is mounted
254           into it in read-only mode (the system thus starts up with read-only
255           OS image, but pristine state and configuration, any changes are
256           lost on shutdown). When the mode parameter is specified as state,
257           the OS tree is mounted read-only, but /var/ is mounted as a
258           writable "tmpfs" instance into it (the system thus starts up with
259           read-only OS resources and configuration, but pristine state, and
260           any changes to the latter are lost on shutdown). When the mode
261           parameter is specified as overlay the read-only root file system is
262           combined with a writable tmpfs instance through "overlayfs", so
263           that it appears at it normally would, but any changes are applied
264           to the temporary file system only and lost when the container is
265           terminated. When the mode parameter is specified as no (the
266           default), the whole OS tree is made available writable (unless
267           --read-only is specified, see above).
268
269           Note that if one of the volatile modes is chosen, its effect is
270           limited to the root file system (or /var/ in case of state), and
271           any other mounts placed in the hierarchy are unaffected —
272           regardless if they are established automatically (e.g. the EFI
273           system partition that might be mounted to /efi/ or /boot/) or
274           explicitly (e.g. through an additional command line option such as
275           --bind=, see below). This means, even if --volatile=overlay is used
276           changes to /efi/ or /boot/ are prohibited in case such a partition
277           exists in the container image operated on, and even if
278           --volatile=state is used the hypothetical file /etc/foobar is
279           potentially writable if --bind=/etc/foobar if used to mount it from
280           outside the read-only container /etc/ directory.
281
282           The --ephemeral option is closely related to this setting, and
283           provides similar behaviour by making a temporary, ephemeral copy of
284           the whole OS image and executing that. For further details, see
285           above.
286
287           The --tmpfs= and --overlay= options provide similar functionality,
288           but for specific sub-directories of the OS image only. For details,
289           see below.
290
291           This option provides similar functionality for containers as the
292           "systemd.volatile=" kernel command line switch provides for host
293           systems. See kernel-command-line(7) for details.
294
295           Note that setting this option to yes or state will only work
296           correctly with operating systems in the container that can boot up
297           with only /usr/ mounted, and are able to automatically populate
298           /var/ (and /etc/ in case of "--volatile=yes"). Specifically, this
299           means that operating systems that follow the historic split of
300           /bin/ and /lib/ (and related directories) from /usr/ (i.e. where
301           the former are not symlinks into the latter) are not supported by
302           "--volatile=yes" as container payload. The overlay option does not
303           require any particular preparations in the OS, but do note that
304           "overlayfs" behaviour differs from regular file systems in a number
305           of ways, and hence compatibility is limited.
306
307       --root-hash=
308           Takes a data integrity (dm-verity) root hash specified in
309           hexadecimal. This option enables data integrity checks using
310           dm-verity, if the used image contains the appropriate integrity
311           data (see above). The specified hash must match the root hash of
312           integrity data, and is usually at least 256 bits (and hence 64
313           formatted hexadecimal characters) long (in case of SHA256 for
314           example). If this option is not specified, but the image file
315           carries the "user.verity.roothash" extended file attribute (see
316           xattr(7)), then the root hash is read from it, also as formatted
317           hexadecimal characters. If the extended file attribute is not found
318           (or is not supported by the underlying file system), but a file
319           with the .roothash suffix is found next to the image file, bearing
320           otherwise the same name (except if the image has the .raw suffix,
321           in which case the root hash file must not have it in its name), the
322           root hash is read from it and automatically used, also as formatted
323           hexadecimal characters.
324
325           Note that this configures the root hash for the root file system.
326           Disk images may also contain separate file systems for the /usr/
327           hierarchy, which may be Verity protected as well. The root hash for
328           this protection may be configured via the "user.verity.usrhash"
329           extended file attribute or via a .usrhash file adjacent to the disk
330           image, following the same format and logic as for the root hash for
331           the root file system described here. Note that there's currently no
332           switch to configure the root hash for the /usr/ from the command
333           line.
334
335           Also see the RootHash= option in systemd.exec(5).
336
337       --root-hash-sig=
338           Takes a PKCS7 signature of the --root-hash= option. The semantics
339           are the same as for the RootHashSignature= option, see
340           systemd.exec(5).
341
342       --verity-data=
343           Takes the path to a data integrity (dm-verity) file. This option
344           enables data integrity checks using dm-verity, if a root-hash is
345           passed and if the used image itself does not contains the integrity
346           data. The integrity data must be matched by the root hash. If this
347           option is not specified, but a file with the .verity suffix is
348           found next to the image file, bearing otherwise the same name
349           (except if the image has the .raw suffix, in which case the verity
350           data file must not have it in its name), the verity data is read
351           from it and automatically used.
352
353       --pivot-root=
354           Pivot the specified directory to / inside the container, and either
355           unmount the container's old root, or pivot it to another specified
356           directory. Takes one of: a path argument — in which case the
357           specified path will be pivoted to / and the old root will be
358           unmounted; or a colon-separated pair of new root path and pivot
359           destination for the old root. The new root path will be pivoted to
360           /, and the old / will be pivoted to the other directory. Both paths
361           must be absolute, and are resolved in the container's file system
362           namespace.
363
364           This is for containers which have several bootable directories in
365           them; for example, several OSTree[4] deployments. It emulates the
366           behavior of the boot loader and initial RAM disk which normally
367           select which directory to mount as the root and start the
368           container's PID 1 in.
369
370   Execution Options
371       -a, --as-pid2
372           Invoke the shell or specified program as process ID (PID) 2 instead
373           of PID 1 (init). By default, if neither this option nor --boot is
374           used, the selected program is run as the process with PID 1, a mode
375           only suitable for programs that are aware of the special semantics
376           that the process with PID 1 has on UNIX. For example, it needs to
377           reap all processes reparented to it, and should implement sysvinit
378           compatible signal handling (specifically: it needs to reboot on
379           SIGINT, reexecute on SIGTERM, reload configuration on SIGHUP, and
380           so on). With --as-pid2 a minimal stub init process is run as PID 1
381           and the selected program is executed as PID 2 (and hence does not
382           need to implement any special semantics). The stub init process
383           will reap processes as necessary and react appropriately to
384           signals. It is recommended to use this mode to invoke arbitrary
385           commands in containers, unless they have been modified to run
386           correctly as PID 1. Or in other words: this switch should be used
387           for pretty much all commands, except when the command refers to an
388           init or shell implementation, as these are generally capable of
389           running correctly as PID 1. This option may not be combined with
390           --boot.
391
392       -b, --boot
393           Automatically search for an init program and invoke it as PID 1,
394           instead of a shell or a user supplied program. If this option is
395           used, arguments specified on the command line are used as arguments
396           for the init program. This option may not be combined with
397           --as-pid2.
398
399           The following table explains the different modes of invocation and
400           relationship to --as-pid2 (see above):
401
402           Table 1. Invocation Mode
403           ┌──────────────────────┬────────────────────────────┐
404Switch                Explanation                
405           ├──────────────────────┼────────────────────────────┤
406           │Neither --as-pid2 nor │ The passed parameters are  │
407--boot specified      │ interpreted as the command │
408           │                      │ line, which is executed as │
409           │                      │ PID 1 in the container.    │
410           ├──────────────────────┼────────────────────────────┤
411--as-pid2 specified   │ The passed parameters are  │
412           │                      │ interpreted as the command │
413           │                      │ line, which is executed as │
414           │                      │ PID 2 in the container. A  │
415           │                      │ stub init process is run   │
416           │                      │ as PID 1.                  │
417           ├──────────────────────┼────────────────────────────┤
418--boot specified      │ An init program is         │
419           │                      │ automatically searched for │
420           │                      │ and run as PID 1 in the    │
421           │                      │ container. The passed      │
422           │                      │ parameters are used as     │
423           │                      │ invocation parameters for  │
424           │                      │ this process.              │
425           └──────────────────────┴────────────────────────────┘
426           Note that --boot is the default mode of operation if the
427           systemd-nspawn@.service template unit file is used.
428
429       --chdir=
430           Change to the specified working directory before invoking the
431           process in the container. Expects an absolute path in the
432           container's file system namespace.
433
434       -E NAME[=VALUE], --setenv=NAME[=VALUE]
435           Specifies an environment variable to pass to the init process in
436           the container. This may be used to override the default variables
437           or to set additional variables. It may be used more than once to
438           set multiple variables. When "=" and VALUE are omitted, the value
439           of the variable with the same name in the program environment will
440           be used.
441
442       -u, --user=
443           After transitioning into the container, change to the specified
444           user defined in the container's user database. Like all other
445           systemd-nspawn features, this is not a security feature and
446           provides protection against accidental destructive operations only.
447
448       --kill-signal=
449           Specify the process signal to send to the container's PID 1 when
450           nspawn itself receives SIGTERM, in order to trigger an orderly
451           shutdown of the container. Defaults to SIGRTMIN+3 if --boot is used
452           (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly
453           shutdown). If --boot is not used and this option is not specified
454           the container's processes are terminated abruptly via SIGKILL. For
455           a list of valid signals, see signal(7).
456
457       --notify-ready=
458           Configures support for notifications from the container's init
459           process.  --notify-ready= takes a boolean (no and yes). With option
460           no systemd-nspawn notifies systemd with a "READY=1" message when
461           the init process is created. With option yes systemd-nspawn waits
462           for the "READY=1" message from the init process in the container
463           before sending its own to systemd. For more details about
464           notifications see sd_notify(3).
465
466       --suppress-sync=
467           Expects a boolean argument. If true, turns off any form of on-disk
468           file system synchronization for the container payload. This means
469           all system calls such as sync(2), fsync(), syncfs(), ... will
470           execute no operation, and the O_SYNC/O_DSYNC flags to open(2) and
471           related calls will be made unavailable. This is potentially
472           dangerous, as assumed data integrity guarantees to the container
473           payload are not actually enforced (i.e. data assumed to have been
474           written to disk might be lost if the system is shut down
475           abnormally). However, this can dramatically improve container
476           runtime performance – as long as these guarantees are not required
477           or desirable, for example because any data written by the container
478           is of temporary, redundant nature, or just an intermediary artifact
479           that will be further processed and finalized by a later step in a
480           pipeline. Defaults to false.
481
482   System Identity Options
483       -M, --machine=
484           Sets the machine name for this container. This name may be used to
485           identify this container during its runtime (for example in tools
486           like machinectl(1) and similar), and is used to initialize the
487           container's hostname (which the container can choose to override,
488           however). If not specified, the last component of the root
489           directory path of the container is used, possibly suffixed with a
490           random identifier in case --ephemeral mode is selected. If the root
491           directory selected is the host's root directory the host's hostname
492           is used as default instead.
493
494       --hostname=
495           Controls the hostname to set within the container, if different
496           from the machine name. Expects a valid hostname as argument. If
497           this option is used, the kernel hostname of the container will be
498           set to this value, otherwise it will be initialized to the machine
499           name as controlled by the --machine= option described above. The
500           machine name is used for various aspect of identification of the
501           container from the outside, the kernel hostname configurable with
502           this option is useful for the container to identify itself from the
503           inside. It is usually a good idea to keep both forms of
504           identification synchronized, in order to avoid confusion. It is
505           hence recommended to avoid usage of this option, and use --machine=
506           exclusively. Note that regardless whether the container's hostname
507           is initialized from the name set with --hostname= or the one set
508           with --machine=, the container can later override its kernel
509           hostname freely on its own as well.
510
511       --uuid=
512           Set the specified UUID for the container. The init system will
513           initialize /etc/machine-id from this if this file is not set yet.
514           Note that this option takes effect only if /etc/machine-id in the
515           container is unpopulated.
516
517   Property Options
518       -S, --slice=
519           Make the container part of the specified slice, instead of the
520           default machine.slice. This applies only if the machine is run in
521           its own scope unit, i.e. if --keep-unit isn't used.
522
523       --property=
524           Set a unit property on the scope unit to register for the machine.
525           This applies only if the machine is run in its own scope unit, i.e.
526           if --keep-unit isn't used. Takes unit property assignments in the
527           same format as systemctl set-property. This is useful to set memory
528           limits and similar for container.
529
530       --register=
531           Controls whether the container is registered with systemd-
532           machined(8). Takes a boolean argument, which defaults to "yes".
533           This option should be enabled when the container runs a full
534           Operating System (more specifically: a system and service manager
535           as PID 1), and is useful to ensure that the container is accessible
536           via machinectl(1) and shown by tools such as ps(1). If the
537           container does not run a service manager, it is recommended to set
538           this option to "no".
539
540       --keep-unit
541           Instead of creating a transient scope unit to run the container in,
542           simply use the service or scope unit systemd-nspawn has been
543           invoked in. If --register=yes is set this unit is registered with
544           systemd-machined(8). This switch should be used if systemd-nspawn
545           is invoked from within a service unit, and the service unit's sole
546           purpose is to run a single systemd-nspawn container. This option is
547           not available if run from a user session.
548
549           Note that passing --keep-unit disables the effect of --slice= and
550           --property=. Use --keep-unit and --register=no in combination to
551           disable any kind of unit allocation or registration with
552           systemd-machined.
553
554   User Namespacing Options
555       --private-users=
556           Controls user namespacing. If enabled, the container will run with
557           its own private set of UNIX user and group ids (UIDs and GIDs).
558           This involves mapping the private UIDs/GIDs used in the container
559           (starting with the container's root user 0 and up) to a range of
560           UIDs/GIDs on the host that are not used for other purposes (usually
561           in the range beyond the host's UID/GID 65536). The parameter may be
562           specified as follows:
563
564            1. If one or two colon-separated numbers are specified, user
565               namespacing is turned on. The first parameter specifies the
566               first host UID/GID to assign to the container, the second
567               parameter specifies the number of host UIDs/GIDs to assign to
568               the container. If the second parameter is omitted, 65536
569               UIDs/GIDs are assigned.
570
571            2. If the parameter is "yes", user namespacing is turned on. The
572               UID/GID range to use is determined automatically from the file
573               ownership of the root directory of the container's directory
574               tree. To use this option, make sure to prepare the directory
575               tree in advance, and ensure that all files and directories in
576               it are owned by UIDs/GIDs in the range you'd like to use. Also,
577               make sure that used file ACLs exclusively reference UIDs/GIDs
578               in the appropriate range. In this mode, the number of UIDs/GIDs
579               assigned to the container is 65536, and the owner UID/GID of
580               the root directory must be a multiple of 65536.
581
582            3. If the parameter is "no", user namespacing is turned off. This
583               is the default.
584
585            4. If the parameter is "identity", user namespacing is employed
586               with an identity mapping for the first 65536 UIDs/GIDs. This is
587               mostly equivalent to --private-users=0:65536. While it does not
588               provide UID/GID isolation, since all host and container
589               UIDs/GIDs are chosen identically it does provide process
590               capability isolation, and hence is often a good choice if
591               proper user namespacing with distinct UID maps is not
592               appropriate.
593
594            5. The special value "pick" turns on user namespacing. In this
595               case the UID/GID range is automatically chosen. As first step,
596               the file owner UID/GID of the root directory of the container's
597               directory tree is read, and it is checked that no other
598               container is currently using it. If this check is successful,
599               the UID/GID range determined this way is used, similar to the
600               behavior if "yes" is specified. If the check is not successful
601               (and thus the UID/GID range indicated in the root directory's
602               file owner is already used elsewhere) a new – currently unused
603               – UID/GID range of 65536 UIDs/GIDs is randomly chosen between
604               the host UID/GIDs of 524288 and 1878982656, always starting at
605               a multiple of 65536, and, if possible, consistently hashed from
606               the machine name. This setting implies
607               --private-users-ownership=auto (see below), which possibly has
608               the effect that the files and directories in the container's
609               directory tree will be owned by the appropriate users of the
610               range picked. Using this option makes user namespace behavior
611               fully automatic. Note that the first invocation of a previously
612               unused container image might result in picking a new UID/GID
613               range for it, and thus in the (possibly expensive) file
614               ownership adjustment operation. However, subsequent invocations
615               of the container will be cheap (unless of course the picked
616               UID/GID range is assigned to a different use by then).
617
618           It is recommended to assign at least 65536 UIDs/GIDs to each
619           container, so that the usable UID/GID range in the container covers
620           16 bit. For best security, do not assign overlapping UID/GID ranges
621           to multiple containers. It is hence a good idea to use the upper 16
622           bit of the host 32-bit UIDs/GIDs as container identifier, while the
623           lower 16 bit encode the container UID/GID used. This is in fact the
624           behavior enforced by the --private-users=pick option.
625
626           When user namespaces are used, the GID range assigned to each
627           container is always chosen identical to the UID range.
628
629           In most cases, using --private-users=pick is the recommended option
630           as it enhances container security massively and operates fully
631           automatically in most cases.
632
633           Note that the picked UID/GID range is not written to /etc/passwd or
634           /etc/group. In fact, the allocation of the range is not stored
635           persistently anywhere, except in the file ownership of the files
636           and directories of the container.
637
638           Note that when user namespacing is used file ownership on disk
639           reflects this, and all of the container's files and directories are
640           owned by the container's effective user and group IDs. This means
641           that copying files from and to the container image requires
642           correction of the numeric UID/GID values, according to the UID/GID
643           shift applied.
644
645       --private-users-ownership=
646           Controls how to adjust the container image's UIDs and GIDs to match
647           the UID/GID range chosen with --private-users=, see above. Takes
648           one of "off" (to leave the image as is), "chown" (to recursively
649           chown() the container's directory tree as needed), "map" (in order
650           to use transparent ID mapping mounts) or "auto" for automatically
651           using "map" where available and "chown" where not.
652
653           If "chown" is selected, all files and directories in the
654           container's directory tree will be adjusted so that they are owned
655           by the appropriate UIDs/GIDs selected for the container (see
656           above). This operation is potentially expensive, as it involves
657           iterating through the full directory tree of the container. Besides
658           actual file ownership, file ACLs are adjusted as well.
659
660           Typically "map" is the best choice, since it transparently maps
661           UIDs/GIDs in memory as needed without modifying the image, and
662           without requiring an expensive recursive adjustment operation.
663           However, it is not available for all file systems, currently.
664
665           The --private-users-ownership=auto option is implied if
666           --private-users=pick is used. This option has no effect if user
667           namespacing is not used.
668
669       -U
670           If the kernel supports the user namespaces feature, equivalent to
671           --private-users=pick --private-users-ownership=auto, otherwise
672           equivalent to --private-users=no.
673
674           Note that -U is the default if the systemd-nspawn@.service template
675           unit file is used.
676
677           Note: it is possible to undo the effect of
678           --private-users-ownership=chown (or -U) on the file system by
679           redoing the operation with the first UID of 0:
680
681               systemd-nspawn ... --private-users=0 --private-users-ownership=chown
682
683   Networking Options
684       --private-network
685           Disconnect networking of the container from the host. This makes
686           all network interfaces unavailable in the container, with the
687           exception of the loopback device and those specified with
688           --network-interface= and configured with --network-veth. If this
689           option is specified, the CAP_NET_ADMIN capability will be added to
690           the set of capabilities the container retains. The latter may be
691           disabled by using --drop-capability=. If this option is not
692           specified (or implied by one of the options listed below), the
693           container will have full access to the host network.
694
695       --network-interface=
696           Assign the specified network interface to the container. This will
697           remove the specified interface from the calling namespace and place
698           it in the container. When the container terminates, it is moved
699           back to the calling namespace. Note that --network-interface=
700           implies --private-network. This option may be used more than once
701           to add multiple network interfaces to the container.
702
703           Note that any network interface specified this way must already
704           exist at the time the container is started. If the container shall
705           be started automatically at boot via a systemd-nspawn@.service unit
706           file instance, it might hence make sense to add a unit file drop-in
707           to the service instance (e.g.
708           /etc/systemd/system/systemd-nspawn@foobar.service.d/50-network.conf)
709           with contents like the following:
710
711               [Unit]
712               Wants=sys-subsystem-net-devices-ens1.device
713               After=sys-subsystem-net-devices-ens1.device
714
715           This will make sure that activation of the container service will
716           be delayed until the "ens1" network interface has shown up. This is
717           required since hardware probing is fully asynchronous, and network
718           interfaces might be discovered only later during the boot process,
719           after the container would normally be started without these
720           explicit dependencies.
721
722       --network-macvlan=
723           Create a "macvlan" interface of the specified Ethernet network
724           interface and add it to the container. A "macvlan" interface is a
725           virtual interface that adds a second MAC address to an existing
726           physical Ethernet link. The interface in the container will be
727           named after the interface on the host, prefixed with "mv-". Note
728           that --network-macvlan= implies --private-network. This option may
729           be used more than once to add multiple network interfaces to the
730           container.
731
732           As with --network-interface=, the underlying Ethernet network
733           interface must already exist at the time the container is started,
734           and thus similar unit file drop-ins as described above might be
735           useful.
736
737       --network-ipvlan=
738           Create an "ipvlan" interface of the specified Ethernet network
739           interface and add it to the container. An "ipvlan" interface is a
740           virtual interface, similar to a "macvlan" interface, which uses the
741           same MAC address as the underlying interface. The interface in the
742           container will be named after the interface on the host, prefixed
743           with "iv-". Note that --network-ipvlan= implies --private-network.
744           This option may be used more than once to add multiple network
745           interfaces to the container.
746
747           As with --network-interface=, the underlying Ethernet network
748           interface must already exist at the time the container is started,
749           and thus similar unit file drop-ins as described above might be
750           useful.
751
752       -n, --network-veth
753           Create a virtual Ethernet link ("veth") between host and container.
754           The host side of the Ethernet link will be available as a network
755           interface named after the container's name (as specified with
756           --machine=), prefixed with "ve-". The container side of the
757           Ethernet link will be named "host0". The --network-veth option
758           implies --private-network.
759
760           Note that systemd-networkd.service(8) includes by default a network
761           file /usr/lib/systemd/network/80-container-ve.network matching the
762           host-side interfaces created this way, which contains settings to
763           enable automatic address provisioning on the created virtual link
764           via DHCP, as well as automatic IP routing onto the host's external
765           network interfaces. It also contains
766           /usr/lib/systemd/network/80-container-host0.network matching the
767           container-side interface created this way, containing settings to
768           enable client side address assignment via DHCP. In case
769           systemd-networkd is running on both the host and inside the
770           container, automatic IP communication from the container to the
771           host is thus available, with further connectivity to the external
772           network.
773
774           Note that --network-veth is the default if the
775           systemd-nspawn@.service template unit file is used.
776
777           Note that on Linux network interface names may have a length of 15
778           characters at maximum, while container names may have a length up
779           to 64 characters. As this option derives the host-side interface
780           name from the container name the name is possibly truncated. Thus,
781           care needs to be taken to ensure that interface names remain unique
782           in this case, or even better container names are generally not
783           chosen longer than 12 characters, to avoid the truncation. If the
784           name is truncated, systemd-nspawn will automatically append a
785           4-digit hash value to the name to reduce the chance of collisions.
786           However, the hash algorithm is not collision-free. (See
787           systemd.net-naming-scheme(7) for details on older naming algorithms
788           for this interface). Alternatively, the --network-veth-extra=
789           option may be used, which allows free configuration of the
790           host-side interface name independently of the container name — but
791           might require a bit more additional configuration in case bridging
792           in a fashion similar to --network-bridge= is desired.
793
794       --network-veth-extra=
795           Adds an additional virtual Ethernet link between host and
796           container. Takes a colon-separated pair of host interface name and
797           container interface name. The latter may be omitted in which case
798           the container and host sides will be assigned the same name. This
799           switch is independent of --network-veth, and — in contrast — may be
800           used multiple times, and allows configuration of the network
801           interface names. Note that --network-bridge= has no effect on
802           interfaces created with --network-veth-extra=.
803
804       --network-bridge=
805           Adds the host side of the Ethernet link created with --network-veth
806           to the specified Ethernet bridge interface. Expects a valid network
807           interface name of a bridge device as argument. Note that
808           --network-bridge= implies --network-veth. If this option is used,
809           the host side of the Ethernet link will use the "vb-" prefix
810           instead of "ve-". Regardless of the used naming prefix the same
811           network interface name length limits imposed by Linux apply, along
812           with the complications this creates (for details see above).
813
814           As with --network-interface=, the underlying bridge network
815           interface must already exist at the time the container is started,
816           and thus similar unit file drop-ins as described above might be
817           useful.
818
819       --network-zone=
820           Creates a virtual Ethernet link ("veth") to the container and adds
821           it to an automatically managed Ethernet bridge interface. The
822           bridge interface is named after the passed argument, prefixed with
823           "vz-". The bridge interface is automatically created when the first
824           container configured for its name is started, and is automatically
825           removed when the last container configured for its name exits.
826           Hence, each bridge interface configured this way exists only as
827           long as there's at least one container referencing it running. This
828           option is very similar to --network-bridge=, besides this automatic
829           creation/removal of the bridge device.
830
831           This setting makes it easy to place multiple related containers on
832           a common, virtual Ethernet-based broadcast domain, here called a
833           "zone". Each container may only be part of one zone, but each zone
834           may contain any number of containers. Each zone is referenced by
835           its name. Names may be chosen freely (as long as they form valid
836           network interface names when prefixed with "vz-"), and it is
837           sufficient to pass the same name to the --network-zone= switch of
838           the various concurrently running containers to join them in one
839           zone.
840
841           Note that systemd-networkd.service(8) includes by default a network
842           file /usr/lib/systemd/network/80-container-vz.network matching the
843           bridge interfaces created this way, which contains settings to
844           enable automatic address provisioning on the created virtual
845           network via DHCP, as well as automatic IP routing onto the host's
846           external network interfaces. Using --network-zone= is hence in most
847           cases fully automatic and sufficient to connect multiple local
848           containers in a joined broadcast domain to the host, with further
849           connectivity to the external network.
850
851       --network-namespace-path=
852           Takes the path to a file representing a kernel network namespace
853           that the container shall run in. The specified path should refer to
854           a (possibly bind-mounted) network namespace file, as exposed by the
855           kernel below /proc/$PID/ns/net. This makes the container enter the
856           given network namespace. One of the typical use cases is to give a
857           network namespace under /run/netns created by ip-netns(8), for
858           example, --network-namespace-path=/run/netns/foo. Note that this
859           option cannot be used together with other network-related options,
860           such as --private-network or --network-interface=.
861
862       -p, --port=
863           If private networking is enabled, maps an IP port on the host onto
864           an IP port on the container. Takes a protocol specifier (either
865           "tcp" or "udp"), separated by a colon from a host port number in
866           the range 1 to 65535, separated by a colon from a container port
867           number in the range from 1 to 65535. The protocol specifier and its
868           separating colon may be omitted, in which case "tcp" is assumed.
869           The container port number and its colon may be omitted, in which
870           case the same port as the host port is implied. This option is only
871           supported if private networking is used, such as with
872           --network-veth, --network-zone= --network-bridge=.
873
874   Security Options
875       --capability=
876           List one or more additional capabilities to grant the container.
877           Takes a comma-separated list of capability names, see
878           capabilities(7) for more information. Note that the following
879           capabilities will be granted in any way: CAP_AUDIT_CONTROL,
880           CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
881           CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE,
882           CAP_LINUX_IMMUTABLE, CAP_MKNOD, CAP_NET_BIND_SERVICE,
883           CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETFCAP, CAP_SETGID,
884           CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_BOOT,
885           CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_RESOURCE,
886           CAP_SYS_TTY_CONFIG. Also CAP_NET_ADMIN is retained if
887           --private-network is specified. If the special value "all" is
888           passed, all capabilities are retained.
889
890           If the special value of "help" is passed, the program will print
891           known capability names and exit.
892
893           This option sets the bounding set of capabilities which also limits
894           the ambient capabilities as given with the --ambient-capability=.
895
896       --drop-capability=
897           Specify one or more additional capabilities to drop for the
898           container. This allows running the container with fewer
899           capabilities than the default (see above).
900
901           If the special value of "help" is passed, the program will print
902           known capability names and exit.
903
904           This option sets the bounding set of capabilities which also limits
905           the ambient capabilities as given with the --ambient-capability=.
906
907       --ambient-capability=
908           Specify one or more additional capabilities to pass in the
909           inheritable and ambient set to the program started within the
910           container. The value "all" is not supported for this setting.
911
912           All capabilities specified here must be in the set allowed with the
913           --capability= and --drop-capability= options. Otherwise, an error
914           message will be shown.
915
916           This option cannot be combined with the boot mode of the container
917           (as requested via --boot).
918
919           If the special value of "help" is passed, the program will print
920           known capability names and exit.
921
922       --no-new-privileges=
923           Takes a boolean argument. Specifies the value of the
924           PR_SET_NO_NEW_PRIVS flag for the container payload. Defaults to
925           off. When turned on the payload code of the container cannot
926           acquire new privileges, i.e. the "setuid" file bit as well as file
927           system capabilities will not have an effect anymore. See prctl(2)
928           for details about this flag.
929
930       --system-call-filter=
931           Alter the system call filter applied to containers. Takes a
932           space-separated list of system call names or group names (the
933           latter prefixed with "@", as listed by the syscall-filter command
934           of systemd-analyze(1)). Passed system calls will be permitted. The
935           list may optionally be prefixed by "~", in which case all listed
936           system calls are prohibited. If this command line option is used
937           multiple times the configured lists are combined. If both a
938           positive and a negative list (that is one system call list without
939           and one with the "~" prefix) are configured, the negative list
940           takes precedence over the positive list. Note that systemd-nspawn
941           always implements a system call allow list (as opposed to a deny
942           list!), and this command line option hence adds or removes entries
943           from the default allow list, depending on the "~" prefix. Note that
944           the applied system call filter is also altered implicitly if
945           additional capabilities are passed using the --capabilities=.
946
947       -Z, --selinux-context=
948           Sets the SELinux security context to be used to label processes in
949           the container.
950
951       -L, --selinux-apifs-context=
952           Sets the SELinux security context to be used to label files in the
953           virtual API file systems in the container.
954
955   Resource Options
956       --rlimit=
957           Sets the specified POSIX resource limit for the container payload.
958           Expects an assignment of the form "LIMIT=SOFT:HARD" or
959           "LIMIT=VALUE", where LIMIT should refer to a resource limit type,
960           such as RLIMIT_NOFILE or RLIMIT_NICE. The SOFT and HARD fields
961           should refer to the numeric soft and hard resource limit values. If
962           the second form is used, VALUE may specify a value that is used
963           both as soft and hard limit. In place of a numeric value the
964           special string "infinity" may be used to turn off resource limiting
965           for the specific type of resource. This command line option may be
966           used multiple times to control limits on multiple limit types. If
967           used multiple times for the same limit type, the last use wins. For
968           details about resource limits see setrlimit(2). By default resource
969           limits for the container's init process (PID 1) are set to the same
970           values the Linux kernel originally passed to the host init system.
971           Note that some resource limits are enforced on resources counted
972           per user, in particular RLIMIT_NPROC. This means that unless user
973           namespacing is deployed (i.e.  --private-users= is used, see
974           above), any limits set will be applied to the resource usage of the
975           same user on all local containers as well as the host. This means
976           particular care needs to be taken with these limits as they might
977           be triggered by possibly less trusted code. Example:
978           "--rlimit=RLIMIT_NOFILE=8192:16384".
979
980       --oom-score-adjust=
981           Changes the OOM ("Out Of Memory") score adjustment value for the
982           container payload. This controls /proc/self/oom_score_adj which
983           influences the preference with which this container is terminated
984           when memory becomes scarce. For details see proc(5). Takes an
985           integer in the range -1000...1000.
986
987       --cpu-affinity=
988           Controls the CPU affinity of the container payload. Takes a comma
989           separated list of CPU numbers or number ranges (the latter's start
990           and end value separated by dashes). See sched_setaffinity(2) for
991           details.
992
993       --personality=
994           Control the architecture ("personality") reported by uname(2) in
995           the container. Currently, only "x86" and "x86-64" are supported.
996           This is useful when running a 32-bit container on a 64-bit host. If
997           this setting is not used, the personality reported in the container
998           is the same as the one reported on the host.
999
1000   Integration Options
1001       --resolv-conf=
1002           Configures how /etc/resolv.conf inside of the container shall be
1003           handled (i.e. DNS configuration synchronization from host to
1004           container). Takes one of "off", "copy-host", "copy-static",
1005           "copy-uplink", "copy-stub", "replace-host", "replace-static",
1006           "replace-uplink", "replace-stub", "bind-host", "bind-static",
1007           "bind-uplink", "bind-stub", "delete" or "auto".
1008
1009           If set to "off" the /etc/resolv.conf file in the container is left
1010           as it is included in the image, and neither modified nor bind
1011           mounted over.
1012
1013           If set to "copy-host", the /etc/resolv.conf file from the host is
1014           copied into the container, unless the file exists already and is
1015           not a regular file (e.g. a symlink). Similar, if "replace-host" is
1016           used the file is copied, replacing any existing inode, including
1017           symlinks. Similar, if "bind-host" is used, the file is bind mounted
1018           from the host into the container.
1019
1020           If set to "copy-static", "replace-static" or "bind-static" the
1021           static resolv.conf file supplied with systemd-resolved.service(8)
1022           (specifically: /usr/lib/systemd/resolv.conf) is copied or bind
1023           mounted into the container.
1024
1025           If set to "copy-uplink", "replace-uplink" or "bind-uplink" the
1026           uplink resolv.conf file managed by systemd-resolved.service
1027           (specifically: /run/systemd/resolve/resolv.conf) is copied or bind
1028           mounted into the container.
1029
1030           If set to "copy-stub", "replace-stub" or "bind-stub" the stub
1031           resolv.conf file managed by systemd-resolved.service (specifically:
1032           /run/systemd/resolve/stub-resolv.conf) is copied or bind mounted
1033           into the container.
1034
1035           If set to "delete" the /etc/resolv.conf file in the container is
1036           deleted if it exists.
1037
1038           Finally, if set to "auto" the file is left as it is if private
1039           networking is turned on (see --private-network). Otherwise, if
1040           systemd-resolved.service is running its stub resolv.conf file is
1041           used, and if not the host's /etc/resolv.conf file. In the latter
1042           cases the file is copied if the image is writable, and bind mounted
1043           otherwise.
1044
1045           It's recommended to use "copy-..."  or "replace-..."  if the
1046           container shall be able to make changes to the DNS configuration on
1047           its own, deviating from the host's settings. Otherwise "bind" is
1048           preferable, as it means direct changes to /etc/resolv.conf in the
1049           container are not allowed, as it is a read-only bind mount (but
1050           note that if the container has enough privileges, it might simply
1051           go ahead and unmount the bind mount anyway). Note that both if the
1052           file is bind mounted and if it is copied no further propagation of
1053           configuration is generally done after the one-time early
1054           initialization (this is because the file is usually updated through
1055           copying and renaming). Defaults to "auto".
1056
1057       --timezone=
1058           Configures how /etc/localtime inside of the container (i.e. local
1059           timezone synchronization from host to container) shall be handled.
1060           Takes one of "off", "copy", "bind", "symlink", "delete" or "auto".
1061           If set to "off" the /etc/localtime file in the container is left as
1062           it is included in the image, and neither modified nor bind mounted
1063           over. If set to "copy" the /etc/localtime file of the host is
1064           copied into the container. Similarly, if "bind" is used, the file
1065           is bind mounted from the host into the container. If set to
1066           "symlink", a symlink is created pointing from /etc/localtime in the
1067           container to the timezone file in the container that matches the
1068           timezone setting on the host. If set to "delete", the file in the
1069           container is deleted, should it exist. If set to "auto" and the
1070           /etc/localtime file of the host is a symlink, then "symlink" mode
1071           is used, and "copy" otherwise, except if the image is read-only in
1072           which case "bind" is used instead. Defaults to "auto".
1073
1074       --link-journal=
1075           Control whether the container's journal shall be made visible to
1076           the host system. If enabled, allows viewing the container's journal
1077           files from the host (but not vice versa). Takes one of "no",
1078           "host", "try-host", "guest", "try-guest", "auto". If "no", the
1079           journal is not linked. If "host", the journal files are stored on
1080           the host file system (beneath /var/log/journal/machine-id) and the
1081           subdirectory is bind-mounted into the container at the same
1082           location. If "guest", the journal files are stored on the guest
1083           file system (beneath /var/log/journal/machine-id) and the
1084           subdirectory is symlinked into the host at the same location.
1085           "try-host" and "try-guest" do the same but do not fail if the host
1086           does not have persistent journaling enabled. If "auto" (the
1087           default), and the right subdirectory of /var/log/journal exists, it
1088           will be bind mounted into the container. If the subdirectory does
1089           not exist, no linking is performed. Effectively, booting a
1090           container once with "guest" or "host" will link the journal
1091           persistently if further on the default of "auto" is used.
1092
1093           Note that --link-journal=try-guest is the default if the
1094           systemd-nspawn@.service template unit file is used.
1095
1096       -j
1097           Equivalent to --link-journal=try-guest.
1098
1099   Mount Options
1100       --bind=, --bind-ro=
1101           Bind mount a file or directory from the host into the container.
1102           Takes one of: a path argument — in which case the specified path
1103           will be mounted from the host to the same path in the container, or
1104           a colon-separated pair of paths — in which case the first specified
1105           path is the source in the host, and the second path is the
1106           destination in the container, or a colon-separated triple of source
1107           path, destination path and mount options. The source path may
1108           optionally be prefixed with a "+" character. If so, the source path
1109           is taken relative to the image's root directory. This permits
1110           setting up bind mounts within the container image. The source path
1111           may be specified as empty string, in which case a temporary
1112           directory below the host's /var/tmp/ directory is used. It is
1113           automatically removed when the container is shut down. The
1114           --bind-ro= option creates read-only bind mounts. Backslash escapes
1115           are interpreted, so "\:" may be used to embed colons in either
1116           path. This option may be specified multiple times for creating
1117           multiple independent bind mount points.
1118
1119           Mount options are comma-separated.  rbind and norbind control
1120           whether to create a recursive or a regular bind mount. Defaults to
1121           "rbind".  idmap and noidmap control if the bind mount should use
1122           filesystem id mappings. Using this option requires support by the
1123           source filesystem for id mappings. Defaults to "noidmap".
1124
1125           Note that when this option is used in combination with
1126           --private-users, the resulting mount points will be owned by the
1127           nobody user. That's because the mount and its files and directories
1128           continue to be owned by the relevant host users and groups, which
1129           do not exist in the container, and thus show up under the wildcard
1130           UID 65534 (nobody). If such bind mounts are created, it is
1131           recommended to make them read-only, using --bind-ro=. Alternatively
1132           you can use the "idmap" mount option to map the filesystem ids.
1133
1134       --bind-user=
1135           Binds the home directory of the specified user on the host into the
1136           container. Takes the name of an existing user on the host as
1137           argument. May be used multiple times to bind multiple users into
1138           the container. This does three things:
1139
1140            1. The user's home directory is bind mounted from the host into
1141               /run/hosts/home/.
1142
1143            2. An additional UID/GID mapping is added that maps the host
1144               user's UID/GID to a container UID/GID, allocated from the
1145               60514...60577 range.
1146
1147            3. A JSON user and group record is generated in /run/userdb/ that
1148               describes the mapped user. It contains a minimized
1149               representation of the host's user record, adjusted to the
1150               UID/GID and home directory path assigned to the user in the
1151               container. The nss-systemd(8) glibc NSS module will pick up
1152               these records from there and make them available in the
1153               container's user/group databases.
1154
1155           The combination of the three operations above ensures that it is
1156           possible to log into the container using the same account
1157           information as on the host. The user is only mapped transiently,
1158           while the container is running, and the mapping itself does not
1159           result in persistent changes to the container (except maybe for log
1160           messages generated at login time, and similar). Note that in
1161           particular the UID/GID assignment in the container is not made
1162           persistently. If the user is mapped transiently, it is best to not
1163           allow the user to make persistent changes to the container. If the
1164           user leaves files or directories owned by the user, and those
1165           UIDs/GIDs are reused during later container invocations (possibly
1166           with a different --bind-user= mapping), those files and directories
1167           will be accessible to the "new" user.
1168
1169           The user/group record mapping only works if the container contains
1170           systemd 249 or newer, with nss-systemd properly configured in
1171           nsswitch.conf. See nss-systemd(8) for details.
1172
1173           Note that the user record propagated from the host into the
1174           container will contain the UNIX password hash of the user, so that
1175           seamless logins in the container are possible. If the container is
1176           less trusted than the host it's hence important to use a strong
1177           UNIX password hash function (e.g. yescrypt or similar, with the
1178           "$y$" hash prefix).
1179
1180           When binding a user from the host into the container checks are
1181           executed to ensure that the username is not yet known in the
1182           container. Moreover, it is checked that the UID/GID allocated for
1183           it is not currently defined in the user/group databases of the
1184           container. Both checks directly access the container's /etc/passwd
1185           and /etc/group, and thus might not detect existing accounts in
1186           other databases.
1187
1188           This operation is only supported in combination with
1189           --private-users=/-U.
1190
1191       --inaccessible=
1192           Make the specified path inaccessible in the container. This
1193           over-mounts the specified path (which must exist in the container)
1194           with a file node of the same type that is empty and has the most
1195           restrictive access mode supported. This is an effective way to mask
1196           files, directories and other file system objects from the container
1197           payload. This option may be used more than once in case all
1198           specified paths are masked.
1199
1200       --tmpfs=
1201           Mount a tmpfs file system into the container. Takes a single
1202           absolute path argument that specifies where to mount the tmpfs
1203           instance to (in which case the directory access mode will be chosen
1204           as 0755, owned by root/root), or optionally a colon-separated pair
1205           of path and mount option string that is used for mounting (in which
1206           case the kernel default for access mode and owner will be chosen,
1207           unless otherwise specified). Backslash escapes are interpreted in
1208           the path, so "\:" may be used to embed colons in the path.
1209
1210           Note that this option cannot be used to replace the root file
1211           system of the container with a temporary file system. However, the
1212           --volatile= option described below provides similar functionality,
1213           with a focus on implementing stateless operating system images.
1214
1215       --overlay=, --overlay-ro=
1216           Combine multiple directory trees into one overlay file system and
1217           mount it into the container. Takes a list of colon-separated paths
1218           to the directory trees to combine and the destination mount point.
1219
1220           Backslash escapes are interpreted in the paths, so "\:" may be used
1221           to embed colons in the paths.
1222
1223           If three or more paths are specified, then the last specified path
1224           is the destination mount point in the container, all paths
1225           specified before refer to directory trees on the host and are
1226           combined in the specified order into one overlay file system. The
1227           left-most path is hence the lowest directory tree, the
1228           second-to-last path the highest directory tree in the stacking
1229           order. If --overlay-ro= is used instead of --overlay=, a read-only
1230           overlay file system is created. If a writable overlay file system
1231           is created, all changes made to it are written to the highest
1232           directory tree in the stacking order, i.e. the second-to-last
1233           specified.
1234
1235           If only two paths are specified, then the second specified path is
1236           used both as the top-level directory tree in the stacking order as
1237           seen from the host, as well as the mount point for the overlay file
1238           system in the container. At least two paths have to be specified.
1239
1240           The source paths may optionally be prefixed with "+" character. If
1241           so they are taken relative to the image's root directory. The
1242           uppermost source path may also be specified as an empty string, in
1243           which case a temporary directory below the host's /var/tmp/ is
1244           used. The directory is removed automatically when the container is
1245           shut down. This behaviour is useful in order to make read-only
1246           container directories writable while the container is running. For
1247           example, use "--overlay=+/var::/var" in order to automatically
1248           overlay a writable temporary directory on a read-only /var/
1249           directory.
1250
1251           For details about overlay file systems, see overlayfs.txt[5]. Note
1252           that the semantics of overlay file systems are substantially
1253           different from normal file systems, in particular regarding
1254           reported device and inode information. Device and inode information
1255           may change for a file while it is being written to, and processes
1256           might see out-of-date versions of files at times. Note that this
1257           switch automatically derives the "workdir=" mount option for the
1258           overlay file system from the top-level directory tree, making it a
1259           sibling of it. It is hence essential that the top-level directory
1260           tree is not a mount point itself (since the working directory must
1261           be on the same file system as the top-most directory tree). Also
1262           note that the "lowerdir=" mount option receives the paths to stack
1263           in the opposite order of this switch.
1264
1265           Note that this option cannot be used to replace the root file
1266           system of the container with an overlay file system. However, the
1267           --volatile= option described above provides similar functionality,
1268           with a focus on implementing stateless operating system images.
1269
1270   Input/Output Options
1271       --console=MODE
1272           Configures how to set up standard input, output and error output
1273           for the container payload, as well as the /dev/console device for
1274           the container. Takes one of interactive, read-only, passive, pipe
1275           or autopipe. If interactive, a pseudo-TTY is allocated and made
1276           available as /dev/console in the container. It is then
1277           bi-directionally connected to the standard input and output passed
1278           to systemd-nspawn.  read-only is similar but only the output of the
1279           container is propagated and no input from the caller is read. If
1280           passive, a pseudo TTY is allocated, but it is not connected
1281           anywhere. In pipe mode no pseudo TTY is allocated, but the standard
1282           input, output and error output file descriptors passed to
1283           systemd-nspawn are passed on — as they are — to the container
1284           payload, see the following paragraph. Finally, autopipe mode
1285           operates like interactive when systemd-nspawn is invoked on a
1286           terminal, and like pipe otherwise. Defaults to interactive if
1287           systemd-nspawn is invoked from a terminal, and read-only otherwise.
1288
1289           In pipe mode, /dev/console will not exist in the container. This
1290           means that the container payload generally cannot be a full init
1291           system as init systems tend to require /dev/console to be
1292           available. On the other hand, in this mode container invocations
1293           can be used within shell pipelines. This is because intermediary
1294           pseudo TTYs do not permit independent bidirectional propagation of
1295           the end-of-file (EOF) condition, which is necessary for shell
1296           pipelines to work correctly.  Note that the pipe mode should be
1297           used carefully, as passing arbitrary file descriptors to less
1298           trusted container payloads might open up unwanted interfaces for
1299           access by the container payload. For example, if a passed file
1300           descriptor refers to a TTY of some form, APIs such as TIOCSTI may
1301           be used to synthesize input that might be used for escaping the
1302           container. Hence pipe mode should only be used if the payload is
1303           sufficiently trusted or when the standard input/output/error output
1304           file descriptors are known safe, for example pipes.
1305
1306       --pipe, -P
1307           Equivalent to --console=pipe.
1308
1309   Credentials
1310       --load-credential=ID:PATH, --set-credential=ID:VALUE
1311           Pass a credential to the container. These two options correspond to
1312           the LoadCredential= and SetCredential= settings in unit files. See
1313           systemd.exec(5) for details about these concepts, as well as the
1314           syntax of the option's arguments.
1315
1316           Note: when systemd-nspawn runs as systemd system service it can
1317           propagate the credentials it received via
1318           LoadCredential=/SetCredential= to the container payload. A systemd
1319           service manager running as PID 1 in the container can further
1320           propagate them to the services it itself starts. It is thus
1321           possible to easily propagate credentials from a parent service
1322           manager to a container manager service and from there into its
1323           payload. This can even be done recursively.
1324
1325           In order to embed binary data into the credential data for
1326           --set-credential= use C-style escaping (i.e.  "\n" to embed a
1327           newline, or "\x00" to embed a NUL byte. Note that the invoking
1328           shell might already apply unescaping once, hence this might require
1329           double escaping!).
1330
1331           The systemd-sysusers.service(8) and systemd-firstboot(1) services
1332           read credentials configured this way for the purpose of configuring
1333           the container's root user's password and shell, as well as system
1334           locale, keymap and timezone during the first boot process of the
1335           container. This is particularly useful in combination with
1336           --volatile=yes where every single boot appears as first boot, since
1337           configuration applied to /etc/ is lost on container reboot cycles.
1338           See the respective man pages for details. Example:
1339
1340               # systemd-nspawn -i image.raw \
1341                       --volatile=yes \
1342                       --set-credential=firstboot.locale:de_DE.UTF-8 \
1343                       --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' \
1344                       -b
1345
1346           The above command line will invoke the specified image file
1347           image.raw in volatile mode, i.e. with empty /etc/ and /var/. The
1348           container payload will recognize this as a first boot, and will
1349           invoke systemd-firstboot.service, which then reads the two passed
1350           credentials to configure the system's initial locale and root
1351           password.
1352
1353   Other
1354       --no-pager
1355           Do not pipe output into a pager.
1356
1357       -h, --help
1358           Print a short help text and exit.
1359
1360       --version
1361           Print a short version string and exit.
1362

ENVIRONMENT

1364       $SYSTEMD_LOG_LEVEL
1365           The maximum log level of emitted messages (messages with a higher
1366           log level, i.e. less important ones, will be suppressed). Either
1367           one of (in order of decreasing importance) emerg, alert, crit, err,
1368           warning, notice, info, debug, or an integer in the range 0...7. See
1369           syslog(3) for more information.
1370
1371       $SYSTEMD_LOG_COLOR
1372           A boolean. If true, messages written to the tty will be colored
1373           according to priority.
1374
1375           This setting is only useful when messages are written directly to
1376           the terminal, because journalctl(1) and other tools that display
1377           logs will color messages based on the log level on their own.
1378
1379       $SYSTEMD_LOG_TIME
1380           A boolean. If true, console log messages will be prefixed with a
1381           timestamp.
1382
1383           This setting is only useful when messages are written directly to
1384           the terminal or a file, because journalctl(1) and other tools that
1385           display logs will attach timestamps based on the entry metadata on
1386           their own.
1387
1388       $SYSTEMD_LOG_LOCATION
1389           A boolean. If true, messages will be prefixed with a filename and
1390           line number in the source code where the message originates.
1391
1392           Note that the log location is often attached as metadata to journal
1393           entries anyway. Including it directly in the message text can
1394           nevertheless be convenient when debugging programs.
1395
1396       $SYSTEMD_LOG_TID
1397           A boolean. If true, messages will be prefixed with the current
1398           numerical thread ID (TID).
1399
1400           Note that the this information is attached as metadata to journal
1401           entries anyway. Including it directly in the message text can
1402           nevertheless be convenient when debugging programs.
1403
1404       $SYSTEMD_LOG_TARGET
1405           The destination for log messages. One of console (log to the
1406           attached tty), console-prefixed (log to the attached tty but with
1407           prefixes encoding the log level and "facility", see syslog(3), kmsg
1408           (log to the kernel circular log buffer), journal (log to the
1409           journal), journal-or-kmsg (log to the journal if available, and to
1410           kmsg otherwise), auto (determine the appropriate log target
1411           automatically, the default), null (disable log output).
1412
1413       $SYSTEMD_PAGER
1414           Pager to use when --no-pager is not given; overrides $PAGER. If
1415           neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
1416           pager implementations are tried in turn, including less(1) and
1417           more(1), until one is found. If no pager implementation is
1418           discovered no pager is invoked. Setting this environment variable
1419           to an empty string or the value "cat" is equivalent to passing
1420           --no-pager.
1421
1422       $SYSTEMD_LESS
1423           Override the options passed to less (by default "FRSXMK").
1424
1425           Users might want to change two options in particular:
1426
1427           K
1428               This option instructs the pager to exit immediately when Ctrl+C
1429               is pressed. To allow less to handle Ctrl+C itself to switch
1430               back to the pager command prompt, unset this option.
1431
1432               If the value of $SYSTEMD_LESS does not include "K", and the
1433               pager that is invoked is less, Ctrl+C will be ignored by the
1434               executable, and needs to be handled by the pager.
1435
1436           X
1437               This option instructs the pager to not send termcap
1438               initialization and deinitialization strings to the terminal. It
1439               is set by default to allow command output to remain visible in
1440               the terminal even after the pager exits. Nevertheless, this
1441               prevents some pager functionality from working, in particular
1442               paged output cannot be scrolled with the mouse.
1443
1444           See less(1) for more discussion.
1445
1446       $SYSTEMD_LESSCHARSET
1447           Override the charset passed to less (by default "utf-8", if the
1448           invoking terminal is determined to be UTF-8 compatible).
1449
1450       $SYSTEMD_PAGERSECURE
1451           Takes a boolean argument. When true, the "secure" mode of the pager
1452           is enabled; if false, disabled. If $SYSTEMD_PAGERSECURE is not set
1453           at all, secure mode is enabled if the effective UID is not the same
1454           as the owner of the login session, see geteuid(2) and
1455           sd_pid_get_owner_uid(3). In secure mode, LESSSECURE=1 will be set
1456           when invoking the pager, and the pager shall disable commands that
1457           open or create new files or start new subprocesses. When
1458           $SYSTEMD_PAGERSECURE is not set at all, pagers which are not known
1459           to implement secure mode will not be used. (Currently only less(1)
1460           implements secure mode.)
1461
1462           Note: when commands are invoked with elevated privileges, for
1463           example under sudo(8) or pkexec(1), care must be taken to ensure
1464           that unintended interactive features are not enabled. "Secure" mode
1465           for the pager may be enabled automatically as describe above.
1466           Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited
1467           environment allows the user to invoke arbitrary commands. Note that
1468           if the $SYSTEMD_PAGER or $PAGER variables are to be honoured,
1469           $SYSTEMD_PAGERSECURE must be set too. It might be reasonable to
1470           completely disable the pager using --no-pager instead.
1471
1472       $SYSTEMD_COLORS
1473           Takes a boolean argument. When true, systemd and related utilities
1474           will use colors in their output, otherwise the output will be
1475           monochrome. Additionally, the variable can take one of the
1476           following special values: "16", "256" to restrict the use of colors
1477           to the base 16 or 256 ANSI colors, respectively. This can be
1478           specified to override the automatic decision based on $TERM and
1479           what the console is connected to.
1480
1481       $SYSTEMD_URLIFY
1482           The value must be a boolean. Controls whether clickable links
1483           should be generated in the output for terminal emulators supporting
1484           this. This can be specified to override the decision that systemd
1485           makes based on $TERM and other conditions.
1486

EXAMPLES

1488       Example 1. Download a Fedora image and start a shell in it
1489
1490           # machinectl pull-raw --verify=no \
1491                 https://download.fedoraproject.org/pub/fedora/linux/releases/36/Cloud/x86_64/images/Fedora-Cloud-Base-36-1.5.x86_64.raw.xz \
1492                 Fedora-Cloud-Base-36-1.5.x86-64
1493           # systemd-nspawn -M Fedora-Cloud-Base-36-1.5.x86-64
1494
1495       This downloads an image using machinectl(1) and opens a shell in it.
1496
1497       Example 2. Build and boot a minimal Fedora distribution in a container
1498
1499           # dnf -y --releasever=36 --installroot=/var/lib/machines/f36 \
1500                 --repo=fedora --repo=updates --setopt=install_weak_deps=False install \
1501                 passwd dnf fedora-release vim-minimal systemd systemd-networkd
1502           # systemd-nspawn -bD /var/lib/machines/f36
1503
1504       This installs a minimal Fedora distribution into the directory
1505       /var/lib/machines/f36 and then boots that OS in a namespace container.
1506       Because the installation is located underneath the standard
1507       /var/lib/machines/ directory, it is also possible to start the machine
1508       using systemd-nspawn -M f36.
1509
1510       Example 3. Spawn a shell in a container of a minimal Debian unstable
1511       distribution
1512
1513           # debootstrap unstable ~/debian-tree/
1514           # systemd-nspawn -D ~/debian-tree/
1515
1516       This installs a minimal Debian unstable distribution into the directory
1517       ~/debian-tree/ and then spawns a shell from this image in a namespace
1518       container.
1519
1520       debootstrap supports Debian[7], Ubuntu[8], and Tanglu[9] out of the
1521       box, so the same command can be used to install any of those. For other
1522       distributions from the Debian family, a mirror has to be specified, see
1523       debootstrap(8).
1524
1525       Example 4. Boot a minimal Arch Linux distribution in a container
1526
1527           # pacstrap -c ~/arch-tree/ base
1528           # systemd-nspawn -bD ~/arch-tree/
1529
1530       This installs a minimal Arch Linux distribution into the directory
1531       ~/arch-tree/ and then boots an OS in a namespace container in it.
1532
1533       Example 5. Install the OpenSUSE Tumbleweed rolling distribution
1534
1535           # zypper --root=/var/lib/machines/tumbleweed ar -c \
1536                 https://download.opensuse.org/tumbleweed/repo/oss tumbleweed
1537           # zypper --root=/var/lib/machines/tumbleweed refresh
1538           # zypper --root=/var/lib/machines/tumbleweed install --no-recommends \
1539                 systemd shadow zypper openSUSE-release vim
1540           # systemd-nspawn -M tumbleweed passwd root
1541           # systemd-nspawn -M tumbleweed -b
1542
1543       Example 6. Boot into an ephemeral snapshot of the host system
1544
1545           # systemd-nspawn -D / -xb
1546
1547       This runs a copy of the host system in a snapshot which is removed
1548       immediately when the container exits. All file system changes made
1549       during runtime will be lost on shutdown, hence.
1550
1551       Example 7. Run a container with SELinux sandbox security contexts
1552
1553           # chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
1554           # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \
1555                 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh
1556
1557       Example 8. Run a container with an OSTree deployment
1558
1559           # systemd-nspawn -b -i ~/image.raw \
1560                 --pivot-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \
1561                 --bind=+/sysroot/ostree/deploy/$OS/var:/var
1562

EXIT STATUS

1564       The exit code of the program executed in the container is returned.
1565

SEE ALSO

1567       systemd(1), systemd.nspawn(5), chroot(1), dnf(8), debootstrap(8),
1568       pacman(8), zypper(8), systemd.slice(5), machinectl(1), btrfs(8)
1569

NOTES

1571        1. Container Interface
1572           https://systemd.io/CONTAINER_INTERFACE
1573
1574        2. Discoverable Partitions Specification
1575           https://systemd.io/DISCOVERABLE_PARTITIONS
1576
1577        3. OCI Runtime Specification
1578           https://github.com/opencontainers/runtime-spec/blob/master/spec.md
1579
1580        4. OSTree
1581           https://ostree.readthedocs.io/en/latest/
1582
1583        5. overlayfs.txt
1584           https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt
1585
1586        6. Fedora
1587           https://getfedora.org
1588
1589        7. Debian
1590           https://www.debian.org
1591
1592        8. Ubuntu
1593           https://www.ubuntu.com
1594
1595        9. Tanglu
1596           https://www.tanglu.org
1597
1598       10. Arch Linux
1599           https://www.archlinux.org
1600
1601       11. OpenSUSE Tumbleweed
1602           https://software.opensuse.org/distributions/tumbleweed
1603
1604
1605
1606systemd 250                                                  SYSTEMD-NSPAWN(1)
Impressum