1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ 4<!ENTITY % entities SYSTEM "custom-entities.ent" > 5%entities; 6]> 7<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 8 9<refentry id="systemd-nspawn" 10 xmlns:xi="http://www.w3.org/2001/XInclude"> 11 12 <refentryinfo> 13 <title>systemd-nspawn</title> 14 <productname>systemd</productname> 15 </refentryinfo> 16 17 <refmeta> 18 <refentrytitle>systemd-nspawn</refentrytitle> 19 <manvolnum>1</manvolnum> 20 </refmeta> 21 22 <refnamediv> 23 <refname>systemd-nspawn</refname> 24 <refpurpose>Spawn a command or OS in a light-weight container</refpurpose> 25 </refnamediv> 26 27 <refsynopsisdiv> 28 <cmdsynopsis> 29 <command>systemd-nspawn</command> 30 <arg choice="opt" rep="repeat">OPTIONS</arg> 31 <arg choice="opt"><replaceable>COMMAND</replaceable> 32 <arg choice="opt" rep="repeat">ARGS</arg> 33 </arg> 34 </cmdsynopsis> 35 <cmdsynopsis> 36 <command>systemd-nspawn</command> 37 <arg choice="plain">--boot</arg> 38 <arg choice="opt" rep="repeat">OPTIONS</arg> 39 <arg choice="opt" rep="repeat">ARGS</arg> 40 </cmdsynopsis> 41 </refsynopsisdiv> 42 43 <refsect1> 44 <title>Description</title> 45 46 <para><command>systemd-nspawn</command> may be used to run a command or OS in a light-weight namespace 47 container. In many ways it is similar to <citerefentry 48 project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but more powerful 49 since it fully virtualizes the file system hierarchy, as well as the process tree, the various IPC subsystems and 50 the host and domain name.</para> 51 52 <para><command>systemd-nspawn</command> may be invoked on any directory tree containing an operating system tree, 53 using the <option>--directory=</option> command line option. By using the <option>--machine=</option> option an OS 54 tree is automatically searched for in a couple of locations, most importantly in 55 <filename>/var/lib/machines/</filename>, the suggested directory to place OS container images installed on the 56 system.</para> 57 58 <para>In contrast to <citerefentry 59 project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command> 60 may be used to boot full Linux-based operating systems in a container.</para> 61 62 <para><command>systemd-nspawn</command> limits access to various kernel interfaces in the container to read-only, 63 such as <filename>/sys/</filename>, <filename>/proc/sys/</filename> or <filename>/sys/fs/selinux/</filename>. The 64 host's network interfaces and the system clock may not be changed from within the container. Device nodes may not 65 be created. The host system cannot be rebooted and kernel modules may not be loaded from within the 66 container.</para> 67 68 <para>Use a tool like <citerefentry 69 project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry 70 project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or 71 <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> to 72 set up an OS directory tree suitable as file system hierarchy for <command>systemd-nspawn</command> containers. See 73 the Examples section below for details on suitable invocation of these commands.</para> 74 75 <para>As a safety check <command>systemd-nspawn</command> will verify the existence of 76 <filename>/usr/lib/os-release</filename> or <filename>/etc/os-release</filename> in the container tree before 77 starting the container (see 78 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It might be 79 necessary to add this file to the container tree manually if the OS of the container is too old to contain this 80 file out-of-the-box.</para> 81 82 <para><command>systemd-nspawn</command> may be invoked directly from the interactive command line or run as system 83 service in the background. In this mode each container instance runs as its own service instance; a default 84 template unit file <filename>systemd-nspawn@.service</filename> is provided to make this easy, taking the container 85 name as instance identifier. Note that different default options apply when <command>systemd-nspawn</command> is 86 invoked by the template unit file than interactively on the command line. Most importantly the template unit file 87 makes use of the <option>--boot</option> which is not the default in case <command>systemd-nspawn</command> is 88 invoked from the interactive command line. Further differences with the defaults are documented along with the 89 various supported options below.</para> 90 91 <para>The <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool may 92 be used to execute a number of operations on containers. In particular it provides easy-to-use commands to run 93 containers as system services using the <filename>systemd-nspawn@.service</filename> template unit 94 file.</para> 95 96 <para>Along with each container a settings file with the <filename>.nspawn</filename> suffix may exist, containing 97 additional settings to apply when running the container. See 98 <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 99 details. Settings files override the default options used by the <filename>systemd-nspawn@.service</filename> 100 template unit file, making it usually unnecessary to alter this template file directly.</para> 101 102 <para>Note that <command>systemd-nspawn</command> will mount file systems private to the container to 103 <filename>/dev/</filename>, <filename>/run/</filename> and similar. These will not be visible outside of the 104 container, and their contents will be lost when the container exits.</para> 105 106 <para>Note that running two <command>systemd-nspawn</command> containers from the same directory tree will not make 107 processes in them see each other. The PID namespace separation of the two containers is complete and the containers 108 will share very few runtime objects except for the underlying file system. Use 109 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s 110 <command>login</command> or <command>shell</command> commands to request an additional login session in a running 111 container.</para> 112 113 <para><command>systemd-nspawn</command> implements the <ulink 114 url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> specification.</para> 115 116 <para>While running, containers invoked with <command>systemd-nspawn</command> are registered with the 117 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry> service that 118 keeps track of running containers, and provides programming interfaces to interact with them.</para> 119 </refsect1> 120 121 <refsect1> 122 <title>Options</title> 123 124 <para>If option <option>-b</option> is specified, the arguments 125 are used as arguments for the init program. Otherwise, 126 <replaceable>COMMAND</replaceable> specifies the program to launch 127 in the container, and the remaining arguments are used as 128 arguments for this program. If <option>--boot</option> is not used and 129 no arguments are specified, a shell is launched in the 130 container.</para> 131 132 <para>The following options are understood:</para> 133 134 <variablelist> 135 136 <varlistentry> 137 <term><option>-q</option></term> 138 <term><option>--quiet</option></term> 139 140 <listitem><para>Turns off any status output by the tool 141 itself. When this switch is used, the only output from nspawn 142 will be the console output of the container OS 143 itself.</para></listitem> 144 </varlistentry> 145 146 <varlistentry> 147 <term><option>--settings=</option><replaceable>MODE</replaceable></term> 148 149 <listitem><para>Controls whether 150 <command>systemd-nspawn</command> shall search for and use 151 additional per-container settings from 152 <filename>.nspawn</filename> files. Takes a boolean or the 153 special values <option>override</option> or 154 <option>trusted</option>.</para> 155 156 <para>If enabled (the default), a settings file named after the 157 machine (as specified with the <option>--machine=</option> 158 setting, or derived from the directory or image file name) 159 with the suffix <filename>.nspawn</filename> is searched in 160 <filename>/etc/systemd/nspawn/</filename> and 161 <filename>/run/systemd/nspawn/</filename>. If it is found 162 there, its settings are read and used. If it is not found 163 there, it is subsequently searched in the same directory as the 164 image file or in the immediate parent of the root directory of 165 the container. In this case, if the file is found, its settings 166 will be also read and used, but potentially unsafe settings 167 are ignored. Note that in both these cases, settings on the 168 command line take precedence over the corresponding settings 169 from loaded <filename>.nspawn</filename> files, if both are 170 specified. Unsafe settings are considered all settings that 171 elevate the container's privileges or grant access to 172 additional resources such as files or directories of the 173 host. For details about the format and contents of 174 <filename>.nspawn</filename> files, consult 175 <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> 176 177 <para>If this option is set to <option>override</option>, the 178 file is searched, read and used the same way, however, the order of 179 precedence is reversed: settings read from the 180 <filename>.nspawn</filename> file will take precedence over 181 the corresponding command line options, if both are 182 specified.</para> 183 184 <para>If this option is set to <option>trusted</option>, the 185 file is searched, read and used the same way, but regardless 186 of being found in <filename>/etc/systemd/nspawn/</filename>, 187 <filename>/run/systemd/nspawn/</filename> or next to the image 188 file or container root directory, all settings will take 189 effect, however, command line arguments still take precedence 190 over corresponding settings.</para> 191 192 <para>If disabled, no <filename>.nspawn</filename> file is read 193 and no settings except the ones on the command line are in 194 effect.</para></listitem> 195 </varlistentry> 196 197 </variablelist> 198 199 <refsect2> 200 <title>Image Options</title> 201 202 <variablelist> 203 204 <varlistentry> 205 <term><option>-D</option></term> 206 <term><option>--directory=</option></term> 207 208 <listitem><para>Directory to use as file system root for the 209 container.</para> 210 211 <para>If neither <option>--directory=</option>, nor 212 <option>--image=</option> is specified the directory is 213 determined by searching for a directory named the same as the 214 machine name specified with <option>--machine=</option>. See 215 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> 216 section "Files and Directories" for the precise search path.</para> 217 218 <para>If neither <option>--directory=</option>, 219 <option>--image=</option>, nor <option>--machine=</option> 220 are specified, the current directory will 221 be used. May not be specified together with 222 <option>--image=</option>.</para></listitem> 223 </varlistentry> 224 225 <varlistentry> 226 <term><option>--template=</option></term> 227 228 <listitem><para>Directory or <literal>btrfs</literal> subvolume to use as template for the 229 container's root directory. If this is specified and the container's root directory (as configured by 230 <option>--directory=</option>) does not yet exist it is created as <literal>btrfs</literal> snapshot 231 (if supported) or plain directory (otherwise) and populated from this template tree. Ideally, the 232 specified template path refers to the root of a <literal>btrfs</literal> subvolume, in which case a 233 simple copy-on-write snapshot is taken, and populating the root directory is instant. If the 234 specified template path does not refer to the root of a <literal>btrfs</literal> subvolume (or not 235 even to a <literal>btrfs</literal> file system at all), the tree is copied (though possibly in a 236 'reflink' copy-on-write scheme — if the file system supports that), which can be substantially more 237 time-consuming. Note that the snapshot taken is of the specified directory or subvolume, including 238 all subdirectories and subvolumes below it, but excluding any sub-mounts. May not be specified 239 together with <option>--image=</option> or <option>--ephemeral</option>.</para> 240 241 <para>Note that this switch leaves hostname, machine ID and 242 all other settings that could identify the instance 243 unmodified.</para></listitem> 244 </varlistentry> 245 246 <varlistentry> 247 <term><option>-x</option></term> 248 <term><option>--ephemeral</option></term> 249 250 <listitem><para>If specified, the container is run with a temporary snapshot of its file system that is removed 251 immediately when the container terminates. May not be specified together with 252 <option>--template=</option>.</para> 253 <para>Note that this switch leaves hostname, machine ID and all other settings that could identify 254 the instance unmodified. Please note that — as with <option>--template=</option> — taking the 255 temporary snapshot is more efficient on file systems that support subvolume snapshots or 'reflinks' 256 natively (<literal>btrfs</literal> or new <literal>xfs</literal>) than on more traditional file 257 systems that do not (<literal>ext4</literal>). Note that the snapshot taken is of the specified 258 directory or subvolume, including all subdirectories and subvolumes below it, but excluding any 259 sub-mounts.</para> 260 261 <para>With this option no modifications of the container image are retained. Use 262 <option>--volatile=</option> (described below) for other mechanisms to restrict persistency of 263 container images during runtime.</para> 264 </listitem> 265 </varlistentry> 266 267 <varlistentry> 268 <term><option>-i</option></term> 269 <term><option>--image=</option></term> 270 271 <listitem><para>Disk image to mount the root directory for the 272 container from. Takes a path to a regular file or to a block 273 device node. The file or block device must contain 274 either:</para> 275 276 <itemizedlist> 277 <listitem><para>An MBR partition table with a single 278 partition of type 0x83 that is marked 279 bootable.</para></listitem> 280 281 <listitem><para>A GUID partition table (GPT) with a single 282 partition of type 283 0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem> 284 285 <listitem><para>A GUID partition table (GPT) with a marked 286 root partition which is mounted as the root directory of the 287 container. Optionally, GPT images may contain a home and/or 288 a server data partition which are mounted to the appropriate 289 places in the container. All these partitions must be 290 identified by the partition types defined by the <ulink 291 url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable 292 Partitions Specification</ulink>.</para></listitem> 293 294 <listitem><para>No partition table, and a single file system spanning the whole image.</para></listitem> 295 </itemizedlist> 296 297 <para>On GPT images, if an EFI System Partition (ESP) is discovered, it is automatically mounted to 298 <filename>/efi</filename> (or <filename>/boot</filename> as fallback) in case a directory by this name exists 299 and is empty.</para> 300 301 <para>Partitions encrypted with LUKS are automatically decrypted. Also, on GPT images dm-verity data integrity 302 hash partitions are set up if the root hash for them is specified using the <option>--root-hash=</option> 303 option.</para> 304 305 <para>Single file system images (i.e. file systems without a surrounding partition table) can be opened using 306 dm-verity if the integrity data is passed using the <option>--root-hash=</option> and 307 <option>--verity-data=</option> (and optionally <option>--root-hash-sig=</option>) options.</para> 308 309 <para>Any other partitions, such as foreign partitions or swap partitions are not mounted. May not be specified 310 together with <option>--directory=</option>, <option>--template=</option>.</para></listitem> 311 </varlistentry> 312 313 <varlistentry> 314 <term><option>--oci-bundle=</option></term> 315 316 <listitem><para>Takes the path to an OCI runtime bundle to invoke, as specified in the <ulink 317 url="https://github.com/opencontainers/runtime-spec/blob/master/spec.md">OCI Runtime Specification</ulink>. In 318 this case no <filename>.nspawn</filename> file is loaded, and the root directory and various settings are read 319 from the OCI runtime JSON data (but data passed on the command line takes precedence).</para></listitem> 320 </varlistentry> 321 322 <varlistentry> 323 <term><option>--read-only</option></term> 324 325 <listitem><para>Mount the container's root file system (and any other file systems container in the container 326 image) read-only. This has no effect on additional mounts made with <option>--bind=</option>, 327 <option>--tmpfs=</option> and similar options. This mode is implied if the container image file or directory is 328 marked read-only itself. It is also implied if <option>--volatile=</option> is used. In this case the container 329 image on disk is strictly read-only, while changes are permitted but kept non-persistently in memory only. For 330 further details, see below.</para></listitem> 331 </varlistentry> 332 333 <varlistentry> 334 <term><option>--volatile</option></term> 335 <term><option>--volatile=</option><replaceable>MODE</replaceable></term> 336 337 <listitem><para>Boots the container in volatile mode. When no mode parameter is passed or when mode is 338 specified as <option>yes</option>, full volatile mode is enabled. This means the root directory is mounted as a 339 mostly unpopulated <literal>tmpfs</literal> instance, and <filename>/usr/</filename> from the OS tree is 340 mounted into it in read-only mode (the system thus starts up with read-only OS image, but pristine state and 341 configuration, any changes are lost on shutdown). When the mode parameter is specified as 342 <option>state</option>, the OS tree is mounted read-only, but <filename>/var/</filename> is mounted as a 343 writable <literal>tmpfs</literal> instance into it (the system thus starts up with read-only OS resources and 344 configuration, but pristine state, and any changes to the latter are lost on shutdown). When the mode parameter 345 is specified as <option>overlay</option> the read-only root file system is combined with a writable 346 <filename>tmpfs</filename> instance through <literal>overlayfs</literal>, so that it appears at it normally 347 would, but any changes are applied to the temporary file system only and lost when the container is 348 terminated. When the mode parameter is specified as <option>no</option> (the default), the whole OS tree is 349 made available writable (unless <option>--read-only</option> is specified, see above).</para> 350 351 <para>Note that if one of the volatile modes is chosen, its effect is limited to the root file system 352 (or <filename>/var/</filename> in case of <option>state</option>), and any other mounts placed in the 353 hierarchy are unaffected — regardless if they are established automatically (e.g. the EFI system 354 partition that might be mounted to <filename>/efi/</filename> or <filename>/boot/</filename>) or 355 explicitly (e.g. through an additional command line option such as <option>--bind=</option>, see 356 below). This means, even if <option>--volatile=overlay</option> is used changes to 357 <filename>/efi/</filename> or <filename>/boot/</filename> are prohibited in case such a partition 358 exists in the container image operated on, and even if <option>--volatile=state</option> is used the 359 hypothetical file <filename index="false">/etc/foobar</filename> is potentially writable if 360 <option>--bind=/etc/foobar</option> if used to mount it from outside the read-only container 361 <filename>/etc/</filename> directory.</para> 362 363 <para>The <option>--ephemeral</option> option is closely related to this setting, and provides similar 364 behaviour by making a temporary, ephemeral copy of the whole OS image and executing that. For further details, 365 see above.</para> 366 367 <para>The <option>--tmpfs=</option> and <option>--overlay=</option> options provide similar functionality, but 368 for specific sub-directories of the OS image only. For details, see below.</para> 369 370 <para>This option provides similar functionality for containers as the <literal>systemd.volatile=</literal> 371 kernel command line switch provides for host systems. See 372 <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> for 373 details.</para> 374 375 <para>Note that setting this option to <option>yes</option> or <option>state</option> will only work 376 correctly with operating systems in the container that can boot up with only 377 <filename>/usr/</filename> mounted, and are able to automatically populate <filename>/var/</filename> 378 (and <filename>/etc/</filename> in case of <literal>--volatile=yes</literal>). Specifically, this 379 means that operating systems that follow the historic split of <filename>/bin/</filename> and 380 <filename>/lib/</filename> (and related directories) from <filename>/usr/</filename> (i.e. where the 381 former are not symlinks into the latter) are not supported by <literal>--volatile=yes</literal> as 382 container payload. The <option>overlay</option> option does not require any particular preparations 383 in the OS, but do note that <literal>overlayfs</literal> behaviour differs from regular file systems 384 in a number of ways, and hence compatibility is limited.</para></listitem> 385 </varlistentry> 386 387 <varlistentry> 388 <term><option>--root-hash=</option></term> 389 390 <listitem><para>Takes a data integrity (dm-verity) root hash specified in hexadecimal. This option enables data 391 integrity checks using dm-verity, if the used image contains the appropriate integrity data (see above). The 392 specified hash must match the root hash of integrity data, and is usually at least 256 bits (and hence 64 393 formatted hexadecimal characters) long (in case of SHA256 for example). If this option is not specified, but 394 the image file carries the <literal>user.verity.roothash</literal> extended file attribute (see <citerefentry 395 project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>), then the root 396 hash is read from it, also as formatted hexadecimal characters. If the extended file attribute is not found (or 397 is not supported by the underlying file system), but a file with the <filename>.roothash</filename> suffix is 398 found next to the image file, bearing otherwise the same name (except if the image has the 399 <filename>.raw</filename> suffix, in which case the root hash file must not have it in its name), the root hash 400 is read from it and automatically used, also as formatted hexadecimal characters.</para> 401 402 <para>Note that this configures the root hash for the root file system. Disk images may also contain 403 separate file systems for the <filename>/usr/</filename> hierarchy, which may be Verity protected as 404 well. The root hash for this protection may be configured via the 405 <literal>user.verity.usrhash</literal> extended file attribute or via a <filename>.usrhash</filename> 406 file adjacent to the disk image, following the same format and logic as for the root hash for the 407 root file system described here. Note that there's currently no switch to configure the root hash for 408 the <filename>/usr/</filename> from the command line.</para> 409 410 <para>Also see the <varname>RootHash=</varname> option in 411 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> 412 </listitem> 413 </varlistentry> 414 415 <varlistentry> 416 <term><option>--root-hash-sig=</option></term> 417 418 <listitem><para>Takes a PKCS7 signature of the <option>--root-hash=</option> option. 419 The semantics are the same as for the <varname>RootHashSignature=</varname> option, see 420 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 421 </para></listitem> 422 </varlistentry> 423 424 <varlistentry> 425 <term><option>--verity-data=</option></term> 426 427 <listitem><para>Takes the path to a data integrity (dm-verity) file. This option enables data integrity checks 428 using dm-verity, if a root-hash is passed and if the used image itself does not contains the integrity data. 429 The integrity data must be matched by the root hash. If this option is not specified, but a file with the 430 <filename>.verity</filename> suffix is found next to the image file, bearing otherwise the same name (except if 431 the image has the <filename>.raw</filename> suffix, in which case the verity data file must not have it in its name), 432 the verity data is read from it and automatically used.</para></listitem> 433 </varlistentry> 434 435 <varlistentry> 436 <term><option>--pivot-root=</option></term> 437 438 <listitem><para>Pivot the specified directory to <filename>/</filename> inside the container, and either unmount the 439 container's old root, or pivot it to another specified directory. Takes one of: a path argument — in which case the 440 specified path will be pivoted to <filename>/</filename> and the old root will be unmounted; or a colon-separated pair 441 of new root path and pivot destination for the old root. The new root path will be pivoted to <filename>/</filename>, 442 and the old <filename>/</filename> will be pivoted to the other directory. Both paths must be absolute, and are resolved 443 in the container's file system namespace.</para> 444 445 <para>This is for containers which have several bootable directories in them; for example, several 446 <ulink url="https://ostree.readthedocs.io/en/latest/">OSTree</ulink> deployments. It emulates the behavior of 447 the boot loader and initial RAM disk which normally select which directory to mount as the root and start the 448 container's PID 1 in.</para></listitem> 449 </varlistentry> 450 </variablelist> 451 452 </refsect2><refsect2> 453 <title>Execution Options</title> 454 455 <variablelist> 456 <varlistentry> 457 <term><option>-a</option></term> 458 <term><option>--as-pid2</option></term> 459 460 <listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By 461 default, if neither this option nor <option>--boot</option> is used, the selected program is run as the process 462 with PID 1, a mode only suitable for programs that are aware of the special semantics that the process with 463 PID 1 has on UNIX. For example, it needs to reap all processes reparented to it, and should implement 464 <command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute 465 on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init 466 process is run as PID 1 and the selected program is executed as PID 2 (and hence does not need to implement any 467 special semantics). The stub init process will reap processes as necessary and react appropriately to 468 signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been 469 modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, 470 except when the command refers to an init or shell implementation, as these are generally capable of running 471 correctly as PID 1. This option may not be combined with <option>--boot</option>.</para> 472 </listitem> 473 </varlistentry> 474 475 <varlistentry> 476 <term><option>-b</option></term> 477 <term><option>--boot</option></term> 478 479 <listitem><para>Automatically search for an init program and invoke it as PID 1, instead of a shell or a user 480 supplied program. If this option is used, arguments specified on the command line are used as arguments for the 481 init program. This option may not be combined with <option>--as-pid2</option>.</para> 482 483 <para>The following table explains the different modes of invocation and relationship to 484 <option>--as-pid2</option> (see above):</para> 485 486 <table> 487 <title>Invocation Mode</title> 488 <tgroup cols='2' align='left' colsep='1' rowsep='1'> 489 <colspec colname="switch" /> 490 <colspec colname="explanation" /> 491 <thead> 492 <row> 493 <entry>Switch</entry> 494 <entry>Explanation</entry> 495 </row> 496 </thead> 497 <tbody> 498 <row> 499 <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry> 500 <entry>The passed parameters are interpreted as the command line, which is executed as PID 1 in the container.</entry> 501 </row> 502 503 <row> 504 <entry><option>--as-pid2</option> specified</entry> 505 <entry>The passed parameters are interpreted as the command line, which is executed as PID 2 in the container. A stub init process is run as PID 1.</entry> 506 </row> 507 508 <row> 509 <entry><option>--boot</option> specified</entry> 510 <entry>An init program is automatically searched for and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry> 511 </row> 512 513 </tbody> 514 </tgroup> 515 </table> 516 517 <para>Note that <option>--boot</option> is the default mode of operation if the 518 <filename>systemd-nspawn@.service</filename> template unit file is used.</para> 519 </listitem> 520 </varlistentry> 521 522 <varlistentry> 523 <term><option>--chdir=</option></term> 524 525 <listitem><para>Change to the specified working directory before invoking the process in the container. Expects 526 an absolute path in the container's file system namespace.</para></listitem> 527 </varlistentry> 528 529 <varlistentry> 530 <term><option>-E <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term> 531 <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term> 532 533 <listitem><para>Specifies an environment variable to pass to the init process in the container. This 534 may be used to override the default variables or to set additional variables. It may be used more 535 than once to set multiple variables. When <literal>=</literal> and <replaceable>VALUE</replaceable> 536 are omitted, the value of the variable with the same name in the program environment will be used. 537 </para></listitem> 538 </varlistentry> 539 540 <varlistentry> 541 <term><option>-u</option></term> 542 <term><option>--user=</option></term> 543 544 <listitem><para>After transitioning into the container, change to the specified user defined in the 545 container's user database. Like all other systemd-nspawn features, this is not a security feature and 546 provides protection against accidental destructive operations only.</para></listitem> 547 </varlistentry> 548 549 <varlistentry> 550 <term><option>--kill-signal=</option></term> 551 552 <listitem><para>Specify the process signal to send to the container's PID 1 when nspawn itself receives 553 <constant>SIGTERM</constant>, in order to trigger an orderly shutdown of the container. Defaults to 554 <constant>SIGRTMIN+3</constant> if <option>--boot</option> is used (on systemd-compatible init systems 555 <constant>SIGRTMIN+3</constant> triggers an orderly shutdown). If <option>--boot</option> is not used and this 556 option is not specified the container's processes are terminated abruptly via <constant>SIGKILL</constant>. For 557 a list of valid signals, see <citerefentry 558 project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> 559 </varlistentry> 560 561 <varlistentry> 562 <term><option>--notify-ready=</option></term> 563 564 <listitem><para>Configures support for notifications from the container's init process. 565 <option>--notify-ready=</option> takes a boolean (<option>no</option> and <option>yes</option>). 566 With option <option>no</option> systemd-nspawn notifies systemd 567 with a <literal>READY=1</literal> message when the init process is created. 568 With option <option>yes</option> systemd-nspawn waits for the 569 <literal>READY=1</literal> message from the init process in the container 570 before sending its own to systemd. For more details about notifications 571 see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> 572 </varlistentry> 573 574 <varlistentry> 575 <term><option>--suppress-sync=</option></term> 576 577 <listitem><para>Expects a boolean argument. If true, turns off any form of on-disk file system 578 synchronization for the container payload. This means all system calls such as <citerefentry 579 project='man-pages'><refentrytitle>sync</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 580 <function>fsync()</function>, <function>syncfs()</function>, … will execute no operation, and the 581 <constant>O_SYNC</constant>/<constant>O_DSYNC</constant> flags to <citerefentry 582 project='man-pages'><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry> and 583 related calls will be made unavailable. This is potentially dangerous, as assumed data integrity 584 guarantees to the container payload are not actually enforced (i.e. data assumed to have been written 585 to disk might be lost if the system is shut down abnormally). However, this can dramatically improve 586 container runtime performance – as long as these guarantees are not required or desirable, for 587 example because any data written by the container is of temporary, redundant nature, or just an 588 intermediary artifact that will be further processed and finalized by a later step in a 589 pipeline. Defaults to false.</para></listitem> 590 </varlistentry> 591 </variablelist> 592 593 </refsect2><refsect2> 594 <title>System Identity Options</title> 595 596 <variablelist> 597 <varlistentry> 598 <term><option>-M</option></term> 599 <term><option>--machine=</option></term> 600 601 <listitem><para>Sets the machine name for this container. This 602 name may be used to identify this container during its runtime 603 (for example in tools like 604 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> 605 and similar), and is used to initialize the container's 606 hostname (which the container can choose to override, 607 however). If not specified, the last component of the root 608 directory path of the container is used, possibly suffixed 609 with a random identifier in case <option>--ephemeral</option> 610 mode is selected. If the root directory selected is the host's 611 root directory the host's hostname is used as default 612 instead.</para></listitem> 613 </varlistentry> 614 615 <varlistentry> 616 <term><option>--hostname=</option></term> 617 618 <listitem><para>Controls the hostname to set within the container, if different from the machine name. Expects 619 a valid hostname as argument. If this option is used, the kernel hostname of the container will be set to this 620 value, otherwise it will be initialized to the machine name as controlled by the <option>--machine=</option> 621 option described above. The machine name is used for various aspect of identification of the container from the 622 outside, the kernel hostname configurable with this option is useful for the container to identify itself from 623 the inside. It is usually a good idea to keep both forms of identification synchronized, in order to avoid 624 confusion. It is hence recommended to avoid usage of this option, and use <option>--machine=</option> 625 exclusively. Note that regardless whether the container's hostname is initialized from the name set with 626 <option>--hostname=</option> or the one set with <option>--machine=</option>, the container can later override 627 its kernel hostname freely on its own as well.</para> 628 </listitem> 629 </varlistentry> 630 631 <varlistentry> 632 <term><option>--uuid=</option></term> 633 634 <listitem><para>Set the specified UUID for the container. The 635 init system will initialize 636 <filename>/etc/machine-id</filename> from this if this file is 637 not set yet. Note that this option takes effect only if 638 <filename>/etc/machine-id</filename> in the container is 639 unpopulated.</para></listitem> 640 </varlistentry> 641 </variablelist> 642 643 </refsect2><refsect2> 644 <title>Property Options</title> 645 646 <variablelist> 647 <varlistentry> 648 <term><option>-S</option></term> 649 <term><option>--slice=</option></term> 650 651 <listitem><para>Make the container part of the specified slice, instead of the default 652 <filename>machine.slice</filename>. This applies only if the machine is run in its own scope unit, i.e. if 653 <option>--keep-unit</option> isn't used.</para> 654 </listitem> 655 </varlistentry> 656 657 <varlistentry> 658 <term><option>--property=</option></term> 659 660 <listitem><para>Set a unit property on the scope unit to register for the machine. This applies only if the 661 machine is run in its own scope unit, i.e. if <option>--keep-unit</option> isn't used. Takes unit property 662 assignments in the same format as <command>systemctl set-property</command>. This is useful to set memory 663 limits and similar for container.</para> 664 </listitem> 665 </varlistentry> 666 667 <varlistentry> 668 <term><option>--register=</option></term> 669 670 <listitem><para>Controls whether the container is registered with 671 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes a 672 boolean argument, which defaults to <literal>yes</literal>. This option should be enabled when the container 673 runs a full Operating System (more specifically: a system and service manager as PID 1), and is useful to 674 ensure that the container is accessible via 675 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and shown by 676 tools such as <citerefentry 677 project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If the container 678 does not run a service manager, it is recommended to set this option to 679 <literal>no</literal>.</para></listitem> 680 </varlistentry> 681 682 <varlistentry> 683 <term><option>--keep-unit</option></term> 684 685 <listitem><para>Instead of creating a transient scope unit to run the container in, simply use the service or 686 scope unit <command>systemd-nspawn</command> has been invoked in. If <option>--register=yes</option> is set 687 this unit is registered with 688 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This 689 switch should be used if <command>systemd-nspawn</command> is invoked from within a service unit, and the 690 service unit's sole purpose is to run a single <command>systemd-nspawn</command> container. This option is not 691 available if run from a user session.</para> 692 <para>Note that passing <option>--keep-unit</option> disables the effect of <option>--slice=</option> and 693 <option>--property=</option>. Use <option>--keep-unit</option> and <option>--register=no</option> in 694 combination to disable any kind of unit allocation or registration with 695 <command>systemd-machined</command>.</para></listitem> 696 </varlistentry> 697 </variablelist> 698 699 </refsect2><refsect2> 700 <title>User Namespacing Options</title> 701 702 <variablelist> 703 <varlistentry> 704 <term><option>--private-users=</option></term> 705 706 <listitem><para>Controls user namespacing. If enabled, the container will run with its own private set of UNIX 707 user and group ids (UIDs and GIDs). This involves mapping the private UIDs/GIDs used in the container (starting 708 with the container's root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other 709 purposes (usually in the range beyond the host's UID/GID 65536). The parameter may be specified as follows:</para> 710 711 <orderedlist> 712 <listitem><para>If one or two colon-separated numbers are specified, user namespacing is turned on. The first 713 parameter specifies the first host UID/GID to assign to the container, the second parameter specifies the 714 number of host UIDs/GIDs to assign to the container. If the second parameter is omitted, 65536 UIDs/GIDs are 715 assigned.</para></listitem> 716 717 <listitem><para>If the parameter is <literal>yes</literal>, user namespacing is turned on. The 718 UID/GID range to use is determined automatically from the file ownership of the root directory of 719 the container's directory tree. To use this option, make sure to prepare the directory tree in 720 advance, and ensure that all files and directories in it are owned by UIDs/GIDs in the range you'd 721 like to use. Also, make sure that used file ACLs exclusively reference UIDs/GIDs in the appropriate 722 range. In this mode, the number of UIDs/GIDs assigned to the container is 65536, and the owner 723 UID/GID of the root directory must be a multiple of 65536.</para></listitem> 724 725 <listitem><para>If the parameter is <literal>no</literal>, user namespacing is turned off. This is 726 the default.</para> 727 </listitem> 728 729 <listitem><para>If the parameter is <literal>identity</literal>, user namespacing is employed with 730 an identity mapping for the first 65536 UIDs/GIDs. This is mostly equivalent to 731 <option>--private-users=0:65536</option>. While it does not provide UID/GID isolation, since all 732 host and container UIDs/GIDs are chosen identically it does provide process capability isolation, 733 and hence is often a good choice if proper user namespacing with distinct UID maps is not 734 appropriate.</para></listitem> 735 736 <listitem><para>The special value <literal>pick</literal> turns on user namespacing. In this case 737 the UID/GID range is automatically chosen. As first step, the file owner UID/GID of the root 738 directory of the container's directory tree is read, and it is checked that no other container is 739 currently using it. If this check is successful, the UID/GID range determined this way is used, 740 similar to the behavior if <literal>yes</literal> is specified. If the check is not successful (and 741 thus the UID/GID range indicated in the root directory's file owner is already used elsewhere) a 742 new – currently unused – UID/GID range of 65536 UIDs/GIDs is randomly chosen between the host 743 UID/GIDs of 524288 and 1878982656, always starting at a multiple of 65536, and, if possible, 744 consistently hashed from the machine name. This setting implies 745 <option>--private-users-ownership=auto</option> (see below), which possibly has the effect that the 746 files and directories in the container's directory tree will be owned by the appropriate users of 747 the range picked. Using this option makes user namespace behavior fully automatic. Note that the 748 first invocation of a previously unused container image might result in picking a new UID/GID range 749 for it, and thus in the (possibly expensive) file ownership adjustment operation. However, 750 subsequent invocations of the container will be cheap (unless of course the picked UID/GID range is 751 assigned to a different use by then).</para></listitem> 752 </orderedlist> 753 754 <para>It is recommended to assign at least 65536 UIDs/GIDs to each container, so that the usable UID/GID range in the 755 container covers 16 bit. For best security, do not assign overlapping UID/GID ranges to multiple containers. It is 756 hence a good idea to use the upper 16 bit of the host 32-bit UIDs/GIDs as container identifier, while the lower 16 757 bit encode the container UID/GID used. This is in fact the behavior enforced by the 758 <option>--private-users=pick</option> option.</para> 759 760 <para>When user namespaces are used, the GID range assigned to each container is always chosen identical to the 761 UID range.</para> 762 763 <para>In most cases, using <option>--private-users=pick</option> is the recommended option as it enhances 764 container security massively and operates fully automatically in most cases.</para> 765 766 <para>Note that the picked UID/GID range is not written to <filename>/etc/passwd</filename> or 767 <filename>/etc/group</filename>. In fact, the allocation of the range is not stored persistently anywhere, 768 except in the file ownership of the files and directories of the container.</para> 769 770 <para>Note that when user namespacing is used file ownership on disk reflects this, and all of the container's 771 files and directories are owned by the container's effective user and group IDs. This means that copying files 772 from and to the container image requires correction of the numeric UID/GID values, according to the UID/GID 773 shift applied.</para></listitem> 774 </varlistentry> 775 776 <varlistentry> 777 <term><option>--private-users-ownership=</option></term> 778 779 <listitem><para>Controls how to adjust the container image's UIDs and GIDs to match the UID/GID range 780 chosen with <option>--private-users=</option>, see above. Takes one of <literal>off</literal> (to 781 leave the image as is), <literal>chown</literal> (to recursively <function>chown()</function> the 782 container's directory tree as needed), <literal>map</literal> (in order to use transparent ID mapping 783 mounts) or <literal>auto</literal> for automatically using <literal>map</literal> where available and 784 <literal>chown</literal> where not.</para> 785 786 <para>If <literal>chown</literal> is selected, all files and directories in the container's directory 787 tree will be adjusted so that they are owned by the appropriate UIDs/GIDs selected for the container 788 (see above). This operation is potentially expensive, as it involves iterating through the full 789 directory tree of the container. Besides actual file ownership, file ACLs are adjusted as 790 well.</para> 791 792 <para>Typically <literal>map</literal> is the best choice, since it transparently maps UIDs/GIDs in 793 memory as needed without modifying the image, and without requiring an expensive recursive adjustment 794 operation. However, it is not available for all file systems, currently.</para> 795 796 <para>The <option>--private-users-ownership=auto</option> option is implied if 797 <option>--private-users=pick</option> is used. This option has no effect if user namespacing is not 798 used.</para></listitem> 799 </varlistentry> 800 801 <varlistentry> 802 <term><option>-U</option></term> 803 804 <listitem><para>If the kernel supports the user namespaces feature, equivalent to 805 <option>--private-users=pick --private-users-ownership=auto</option>, otherwise equivalent to 806 <option>--private-users=no</option>.</para> 807 808 <para>Note that <option>-U</option> is the default if the 809 <filename>systemd-nspawn@.service</filename> template unit file is used.</para> 810 811 <para>Note: it is possible to undo the effect of <option>--private-users-ownership=chown</option> (or 812 <option>-U</option>) on the file system by redoing the operation with the first UID of 0:</para> 813 814 <programlisting>systemd-nspawn … --private-users=0 --private-users-ownership=chown</programlisting> 815 </listitem> 816 </varlistentry> 817 818 </variablelist> 819 820 </refsect2><refsect2> 821 <title>Networking Options</title> 822 823 <variablelist> 824 825 <varlistentry> 826 <term><option>--private-network</option></term> 827 828 <listitem><para>Disconnect networking of the container from 829 the host. This makes all network interfaces unavailable in the 830 container, with the exception of the loopback device and those 831 specified with <option>--network-interface=</option> and 832 configured with <option>--network-veth</option>. If this 833 option is specified, the <constant>CAP_NET_ADMIN</constant> capability will be 834 added to the set of capabilities the container retains. The 835 latter may be disabled by using <option>--drop-capability=</option>. 836 If this option is not specified (or implied by one of the options 837 listed below), the container will have full access to the host network. 838 </para></listitem> 839 </varlistentry> 840 841 <varlistentry> 842 <term><option>--network-interface=</option></term> 843 844 <listitem><para>Assign the specified network interface to the container. This will remove the 845 specified interface from the calling namespace and place it in the container. When the container 846 terminates, it is moved back to the calling namespace. Note that 847 <option>--network-interface=</option> implies <option>--private-network</option>. This option may be 848 used more than once to add multiple network interfaces to the container.</para> 849 850 <para>Note that any network interface specified this way must already exist at the time the container 851 is started. If the container shall be started automatically at boot via a 852 <filename>systemd-nspawn@.service</filename> unit file instance, it might hence make sense to add a 853 unit file drop-in to the service instance 854 (e.g. <filename>/etc/systemd/system/systemd-nspawn@foobar.service.d/50-network.conf</filename>) with 855 contents like the following:</para> 856 857 <programlisting>[Unit] 858Wants=sys-subsystem-net-devices-ens1.device 859After=sys-subsystem-net-devices-ens1.device</programlisting> 860 861 <para>This will make sure that activation of the container service will be delayed until the 862 <literal>ens1</literal> network interface has shown up. This is required since hardware probing is 863 fully asynchronous, and network interfaces might be discovered only later during the boot process, 864 after the container would normally be started without these explicit dependencies.</para> 865 </listitem> 866 </varlistentry> 867 868 <varlistentry> 869 <term><option>--network-macvlan=</option></term> 870 871 <listitem><para>Create a <literal>macvlan</literal> interface of the specified Ethernet network 872 interface and add it to the container. A <literal>macvlan</literal> interface is a virtual interface 873 that adds a second MAC address to an existing physical Ethernet link. The interface in the container 874 will be named after the interface on the host, prefixed with <literal>mv-</literal>. Note that 875 <option>--network-macvlan=</option> implies <option>--private-network</option>. This option may be 876 used more than once to add multiple network interfaces to the container.</para> 877 878 <para>As with <option>--network-interface=</option>, the underlying Ethernet network interface must 879 already exist at the time the container is started, and thus similar unit file drop-ins as described 880 above might be useful.</para></listitem> 881 </varlistentry> 882 883 <varlistentry> 884 <term><option>--network-ipvlan=</option></term> 885 886 <listitem><para>Create an <literal>ipvlan</literal> interface of the specified Ethernet network 887 interface and add it to the container. An <literal>ipvlan</literal> interface is a virtual interface, 888 similar to a <literal>macvlan</literal> interface, which uses the same MAC address as the underlying 889 interface. The interface in the container will be named after the interface on the host, prefixed 890 with <literal>iv-</literal>. Note that <option>--network-ipvlan=</option> implies 891 <option>--private-network</option>. This option may be used more than once to add multiple network 892 interfaces to the container.</para> 893 894 <para>As with <option>--network-interface=</option>, the underlying Ethernet network interface must 895 already exist at the time the container is started, and thus similar unit file drop-ins as described 896 above might be useful.</para></listitem> 897 </varlistentry> 898 899 <varlistentry> 900 <term><option>-n</option></term> 901 <term><option>--network-veth</option></term> 902 903 <listitem><para>Create a virtual Ethernet link (<literal>veth</literal>) between host and container. The host 904 side of the Ethernet link will be available as a network interface named after the container's name (as 905 specified with <option>--machine=</option>), prefixed with <literal>ve-</literal>. The container side of the 906 Ethernet link will be named <literal>host0</literal>. The <option>--network-veth</option> option implies 907 <option>--private-network</option>.</para> 908 909 <para>Note that 910 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 911 includes by default a network file <filename>/usr/lib/systemd/network/80-container-ve.network</filename> 912 matching the host-side interfaces created this way, which contains settings to enable automatic address 913 provisioning on the created virtual link via DHCP, as well as automatic IP routing onto the host's external 914 network interfaces. It also contains <filename>/usr/lib/systemd/network/80-container-host0.network</filename> 915 matching the container-side interface created this way, containing settings to enable client side address 916 assignment via DHCP. In case <filename>systemd-networkd</filename> is running on both the host and inside the 917 container, automatic IP communication from the container to the host is thus available, with further 918 connectivity to the external network.</para> 919 920 <para>Note that <option>--network-veth</option> is the default if the 921 <filename>systemd-nspawn@.service</filename> template unit file is used.</para> 922 923 <para>Note that on Linux network interface names may have a length of 15 characters at maximum, while 924 container names may have a length up to 64 characters. As this option derives the host-side interface 925 name from the container name the name is possibly truncated. Thus, care needs to be taken to ensure 926 that interface names remain unique in this case, or even better container names are generally not 927 chosen longer than 12 characters, to avoid the truncation. If the name is truncated, 928 <command>systemd-nspawn</command> will automatically append a 4-digit hash value to the name to 929 reduce the chance of collisions. However, the hash algorithm is not collision-free. (See 930 <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry> 931 for details on older naming algorithms for this interface). Alternatively, the 932 <option>--network-veth-extra=</option> option may be used, which allows free configuration of the 933 host-side interface name independently of the container name — but might require a bit more 934 additional configuration in case bridging in a fashion similar to <option>--network-bridge=</option> 935 is desired.</para> 936 </listitem> 937 </varlistentry> 938 939 <varlistentry> 940 <term><option>--network-veth-extra=</option></term> 941 942 <listitem><para>Adds an additional virtual Ethernet link 943 between host and container. Takes a colon-separated pair of 944 host interface name and container interface name. The latter 945 may be omitted in which case the container and host sides will 946 be assigned the same name. This switch is independent of 947 <option>--network-veth</option>, and — in contrast — may be 948 used multiple times, and allows configuration of the network 949 interface names. Note that <option>--network-bridge=</option> 950 has no effect on interfaces created with 951 <option>--network-veth-extra=</option>.</para></listitem> 952 </varlistentry> 953 954 <varlistentry> 955 <term><option>--network-bridge=</option></term> 956 957 <listitem><para>Adds the host side of the Ethernet link created with <option>--network-veth</option> 958 to the specified Ethernet bridge interface. Expects a valid network interface name of a bridge device 959 as argument. Note that <option>--network-bridge=</option> implies <option>--network-veth</option>. If 960 this option is used, the host side of the Ethernet link will use the <literal>vb-</literal> prefix 961 instead of <literal>ve-</literal>. Regardless of the used naming prefix the same network interface 962 name length limits imposed by Linux apply, along with the complications this creates (for details see 963 above).</para> 964 965 <para>As with <option>--network-interface=</option>, the underlying bridge network interface must 966 already exist at the time the container is started, and thus similar unit file drop-ins as described 967 above might be useful.</para></listitem> 968 </varlistentry> 969 970 <varlistentry> 971 <term><option>--network-zone=</option></term> 972 973 <listitem><para>Creates a virtual Ethernet link (<literal>veth</literal>) to the container and adds it to an 974 automatically managed Ethernet bridge interface. The bridge interface is named after the passed argument, 975 prefixed with <literal>vz-</literal>. The bridge interface is automatically created when the first container 976 configured for its name is started, and is automatically removed when the last container configured for its 977 name exits. Hence, each bridge interface configured this way exists only as long as there's at least one 978 container referencing it running. This option is very similar to <option>--network-bridge=</option>, besides 979 this automatic creation/removal of the bridge device.</para> 980 981 <para>This setting makes it easy to place multiple related containers on a common, virtual Ethernet-based 982 broadcast domain, here called a "zone". Each container may only be part of one zone, but each zone may contain 983 any number of containers. Each zone is referenced by its name. Names may be chosen freely (as long as they form 984 valid network interface names when prefixed with <literal>vz-</literal>), and it is sufficient to pass the same 985 name to the <option>--network-zone=</option> switch of the various concurrently running containers to join 986 them in one zone.</para> 987 988 <para>Note that 989 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 990 includes by default a network file <filename>/usr/lib/systemd/network/80-container-vz.network</filename> 991 matching the bridge interfaces created this way, which contains settings to enable automatic address 992 provisioning on the created virtual network via DHCP, as well as automatic IP routing onto the host's external 993 network interfaces. Using <option>--network-zone=</option> is hence in most cases fully automatic and 994 sufficient to connect multiple local containers in a joined broadcast domain to the host, with further 995 connectivity to the external network.</para> 996 </listitem> 997 </varlistentry> 998 999 <varlistentry> 1000 <term><option>--network-namespace-path=</option></term> 1001 1002 <listitem><para>Takes the path to a file representing a kernel 1003 network namespace that the container shall run in. The specified path 1004 should refer to a (possibly bind-mounted) network namespace file, as 1005 exposed by the kernel below <filename>/proc/$PID/ns/net</filename>. 1006 This makes the container enter the given network namespace. One of the 1007 typical use cases is to give a network namespace under 1008 <filename>/run/netns</filename> created by <citerefentry 1009 project='man-pages'><refentrytitle>ip-netns</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 1010 for example, <option>--network-namespace-path=/run/netns/foo</option>. 1011 Note that this option cannot be used together with other 1012 network-related options, such as <option>--private-network</option> 1013 or <option>--network-interface=</option>.</para></listitem> 1014 </varlistentry> 1015 1016 <varlistentry> 1017 <term><option>-p</option></term> 1018 <term><option>--port=</option></term> 1019 1020 <listitem><para>If private networking is enabled, maps an IP 1021 port on the host onto an IP port on the container. Takes a 1022 protocol specifier (either <literal>tcp</literal> or 1023 <literal>udp</literal>), separated by a colon from a host port 1024 number in the range 1 to 65535, separated by a colon from a 1025 container port number in the range from 1 to 65535. The 1026 protocol specifier and its separating colon may be omitted, in 1027 which case <literal>tcp</literal> is assumed. The container 1028 port number and its colon may be omitted, in which case the 1029 same port as the host port is implied. This option is only 1030 supported if private networking is used, such as with 1031 <option>--network-veth</option>, <option>--network-zone=</option> 1032 <option>--network-bridge=</option>.</para></listitem> 1033 </varlistentry> 1034 </variablelist> 1035 1036 </refsect2><refsect2> 1037 <title>Security Options</title> 1038 1039 <variablelist> 1040 <varlistentry> 1041 <term><option>--capability=</option></term> 1042 1043 <listitem><para>List one or more additional capabilities to grant the container. Takes a 1044 comma-separated list of capability names, see <citerefentry 1045 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> 1046 for more information. Note that the following capabilities will be granted in any way: 1047 <constant>CAP_AUDIT_CONTROL</constant>, <constant>CAP_AUDIT_WRITE</constant>, 1048 <constant>CAP_CHOWN</constant>, <constant>CAP_DAC_OVERRIDE</constant>, 1049 <constant>CAP_DAC_READ_SEARCH</constant>, <constant>CAP_FOWNER</constant>, 1050 <constant>CAP_FSETID</constant>, <constant>CAP_IPC_OWNER</constant>, <constant>CAP_KILL</constant>, 1051 <constant>CAP_LEASE</constant>, <constant>CAP_LINUX_IMMUTABLE</constant>, 1052 <constant>CAP_MKNOD</constant>, <constant>CAP_NET_BIND_SERVICE</constant>, 1053 <constant>CAP_NET_BROADCAST</constant>, <constant>CAP_NET_RAW</constant>, 1054 <constant>CAP_SETFCAP</constant>, <constant>CAP_SETGID</constant>, <constant>CAP_SETPCAP</constant>, 1055 <constant>CAP_SETUID</constant>, <constant>CAP_SYS_ADMIN</constant>, 1056 <constant>CAP_SYS_BOOT</constant>, <constant>CAP_SYS_CHROOT</constant>, 1057 <constant>CAP_SYS_NICE</constant>, <constant>CAP_SYS_PTRACE</constant>, 1058 <constant>CAP_SYS_RESOURCE</constant>, <constant>CAP_SYS_TTY_CONFIG</constant>. Also 1059 <constant>CAP_NET_ADMIN</constant> is retained if <option>--private-network</option> is specified. 1060 If the special value <literal>all</literal> is passed, all capabilities are retained.</para> 1061 1062 <para>If the special value of <literal>help</literal> is passed, the program will print known 1063 capability names and exit.</para> 1064 1065 <para>This option sets the bounding set of capabilities which 1066 also limits the ambient capabilities as given with the 1067 <option>--ambient-capability=</option>.</para></listitem> 1068 </varlistentry> 1069 1070 <varlistentry> 1071 <term><option>--drop-capability=</option></term> 1072 1073 <listitem><para>Specify one or more additional capabilities to 1074 drop for the container. This allows running the container with 1075 fewer capabilities than the default (see 1076 above).</para> 1077 1078 <para>If the special value of <literal>help</literal> is passed, the program will print known 1079 capability names and exit.</para> 1080 1081 <para>This option sets the bounding set of capabilities which 1082 also limits the ambient capabilities as given with the 1083 <option>--ambient-capability=</option>.</para></listitem> 1084 </varlistentry> 1085 1086 <varlistentry> 1087 <term><option>--ambient-capability=</option></term> 1088 1089 <listitem><para>Specify one or more additional capabilities to 1090 pass in the inheritable and ambient set to the program started 1091 within the container. The value <literal>all</literal> is not 1092 supported for this setting.</para> 1093 1094 <para>All capabilities specified here must be in the set 1095 allowed with the <option>--capability=</option> and 1096 <option>--drop-capability=</option> options. Otherwise, an 1097 error message will be shown.</para> 1098 1099 <para>This option cannot be combined with the boot mode of the 1100 container (as requested via <option>--boot</option>).</para> 1101 1102 <para>If the special value of <literal>help</literal> is 1103 passed, the program will print known capability names and 1104 exit.</para></listitem> 1105 </varlistentry> 1106 1107 <varlistentry> 1108 <term><option>--no-new-privileges=</option></term> 1109 1110 <listitem><para>Takes a boolean argument. Specifies the value of the 1111 <constant>PR_SET_NO_NEW_PRIVS</constant> flag for the container payload. Defaults to off. When turned 1112 on the payload code of the container cannot acquire new privileges, i.e. the "setuid" file bit as 1113 well as file system capabilities will not have an effect anymore. See <citerefentry 1114 project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1115 details about this flag. </para></listitem> 1116 </varlistentry> 1117 1118 <varlistentry> 1119 <term><option>--system-call-filter=</option></term> <listitem><para>Alter the system call filter 1120 applied to containers. Takes a space-separated list of system call names or group names (the latter 1121 prefixed with <literal>@</literal>, as listed by the <command>syscall-filter</command> command of 1122 <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>). Passed 1123 system calls will be permitted. The list may optionally be prefixed by <literal>~</literal>, in which 1124 case all listed system calls are prohibited. If this command line option is used multiple times the 1125 configured lists are combined. If both a positive and a negative list (that is one system call list 1126 without and one with the <literal>~</literal> prefix) are configured, the negative list takes 1127 precedence over the positive list. Note that <command>systemd-nspawn</command> always implements a 1128 system call allow list (as opposed to a deny list!), and this command line option hence adds or 1129 removes entries from the default allow list, depending on the <literal>~</literal> prefix. Note that 1130 the applied system call filter is also altered implicitly if additional capabilities are passed using 1131 the <command>--capabilities=</command>.</para></listitem> 1132 </varlistentry> 1133 1134 <varlistentry> 1135 <term><option>-Z</option></term> 1136 <term><option>--selinux-context=</option></term> 1137 1138 <listitem><para>Sets the SELinux security context to be used 1139 to label processes in the container.</para> 1140 </listitem> 1141 </varlistentry> 1142 1143 <varlistentry> 1144 <term><option>-L</option></term> 1145 <term><option>--selinux-apifs-context=</option></term> 1146 1147 <listitem><para>Sets the SELinux security context to be used 1148 to label files in the virtual API file systems in the 1149 container.</para> 1150 </listitem> 1151 </varlistentry> 1152 </variablelist> 1153 1154 </refsect2><refsect2> 1155 <title>Resource Options</title> 1156 1157 <variablelist> 1158 1159 <varlistentry> 1160 <term><option>--rlimit=</option></term> 1161 1162 <listitem><para>Sets the specified POSIX resource limit for the container payload. Expects an assignment of the 1163 form 1164 <literal><replaceable>LIMIT</replaceable>=<replaceable>SOFT</replaceable>:<replaceable>HARD</replaceable></literal> 1165 or <literal><replaceable>LIMIT</replaceable>=<replaceable>VALUE</replaceable></literal>, where 1166 <replaceable>LIMIT</replaceable> should refer to a resource limit type, such as 1167 <constant>RLIMIT_NOFILE</constant> or <constant>RLIMIT_NICE</constant>. The <replaceable>SOFT</replaceable> and 1168 <replaceable>HARD</replaceable> fields should refer to the numeric soft and hard resource limit values. If the 1169 second form is used, <replaceable>VALUE</replaceable> may specify a value that is used both as soft and hard 1170 limit. In place of a numeric value the special string <literal>infinity</literal> may be used to turn off 1171 resource limiting for the specific type of resource. This command line option may be used multiple times to 1172 control limits on multiple limit types. If used multiple times for the same limit type, the last use 1173 wins. For details about resource limits see <citerefentry 1174 project='man-pages'><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>. By default 1175 resource limits for the container's init process (PID 1) are set to the same values the Linux kernel originally 1176 passed to the host init system. Note that some resource limits are enforced on resources counted per user, in 1177 particular <constant>RLIMIT_NPROC</constant>. This means that unless user namespacing is deployed 1178 (i.e. <option>--private-users=</option> is used, see above), any limits set will be applied to the resource 1179 usage of the same user on all local containers as well as the host. This means particular care needs to be 1180 taken with these limits as they might be triggered by possibly less trusted code. Example: 1181 <literal>--rlimit=RLIMIT_NOFILE=8192:16384</literal>.</para></listitem> 1182 </varlistentry> 1183 1184 <varlistentry> 1185 <term><option>--oom-score-adjust=</option></term> 1186 1187 <listitem><para>Changes the OOM ("Out Of Memory") score adjustment value for the container payload. This controls 1188 <filename>/proc/self/oom_score_adj</filename> which influences the preference with which this container is 1189 terminated when memory becomes scarce. For details see <citerefentry 1190 project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Takes an 1191 integer in the range -1000…1000.</para></listitem> 1192 </varlistentry> 1193 1194 <varlistentry> 1195 <term><option>--cpu-affinity=</option></term> 1196 1197 <listitem><para>Controls the CPU affinity of the container payload. Takes a comma separated list of CPU numbers 1198 or number ranges (the latter's start and end value separated by dashes). See <citerefentry 1199 project='man-pages'><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> for 1200 details.</para></listitem> 1201 </varlistentry> 1202 1203 <varlistentry> 1204 <term><option>--personality=</option></term> 1205 1206 <listitem><para>Control the architecture ("personality") 1207 reported by 1208 <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> 1209 in the container. Currently, only <literal>x86</literal> and 1210 <literal>x86-64</literal> are supported. This is useful when 1211 running a 32-bit container on a 64-bit host. If this setting 1212 is not used, the personality reported in the container is the 1213 same as the one reported on the host.</para></listitem> 1214 </varlistentry> 1215 </variablelist> 1216 1217 </refsect2><refsect2> 1218 <title>Integration Options</title> 1219 1220 <variablelist> 1221 <varlistentry> 1222 <term><option>--resolv-conf=</option></term> 1223 1224 <listitem><para>Configures how <filename>/etc/resolv.conf</filename> inside of the container shall be 1225 handled (i.e. DNS configuration synchronization from host to container). Takes one of 1226 <literal>off</literal>, <literal>copy-host</literal>, <literal>copy-static</literal>, 1227 <literal>copy-uplink</literal>, <literal>copy-stub</literal>, <literal>replace-host</literal>, 1228 <literal>replace-static</literal>, <literal>replace-uplink</literal>, 1229 <literal>replace-stub</literal>, <literal>bind-host</literal>, <literal>bind-static</literal>, 1230 <literal>bind-uplink</literal>, <literal>bind-stub</literal>, <literal>delete</literal> or 1231 <literal>auto</literal>.</para> 1232 1233 <para>If set to <literal>off</literal> the <filename>/etc/resolv.conf</filename> file in the 1234 container is left as it is included in the image, and neither modified nor bind mounted over.</para> 1235 1236 <para>If set to <literal>copy-host</literal>, the <filename>/etc/resolv.conf</filename> file from the 1237 host is copied into the container, unless the file exists already and is not a regular file (e.g. a 1238 symlink). Similar, if <literal>replace-host</literal> is used the file is copied, replacing any 1239 existing inode, including symlinks. Similar, if <literal>bind-host</literal> is used, the file is 1240 bind mounted from the host into the container.</para> 1241 1242 <para>If set to <literal>copy-static</literal>, <literal>replace-static</literal> or 1243 <literal>bind-static</literal> the static <filename>resolv.conf</filename> file supplied with 1244 <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 1245 (specifically: <filename>/usr/lib/systemd/resolv.conf</filename>) is copied or bind mounted into the 1246 container.</para> 1247 1248 <para>If set to <literal>copy-uplink</literal>, <literal>replace-uplink</literal> or 1249 <literal>bind-uplink</literal> the uplink <filename>resolv.conf</filename> file managed by 1250 <filename>systemd-resolved.service</filename> (specifically: 1251 <filename>/run/systemd/resolve/resolv.conf</filename>) is copied or bind mounted into the 1252 container.</para> 1253 1254 <para>If set to <literal>copy-stub</literal>, <literal>replace-stub</literal> or 1255 <literal>bind-stub</literal> the stub <filename>resolv.conf</filename> file managed by 1256 <filename>systemd-resolved.service</filename> (specifically: 1257 <filename>/run/systemd/resolve/stub-resolv.conf</filename>) is copied or bind mounted into the 1258 container.</para> 1259 1260 <para>If set to <literal>delete</literal> the <filename>/etc/resolv.conf</filename> file in the 1261 container is deleted if it exists.</para> 1262 1263 <para>Finally, if set to <literal>auto</literal> the file is left as it is if private networking is 1264 turned on (see <option>--private-network</option>). Otherwise, if 1265 <filename>systemd-resolved.service</filename> is running its stub <filename>resolv.conf</filename> 1266 file is used, and if not the host's <filename>/etc/resolv.conf</filename> file. In the latter cases 1267 the file is copied if the image is writable, and bind mounted otherwise.</para> 1268 1269 <para>It's recommended to use <literal>copy-…</literal> or <literal>replace-…</literal> if the 1270 container shall be able to make changes to the DNS configuration on its own, deviating from the 1271 host's settings. Otherwise <literal>bind</literal> is preferable, as it means direct changes to 1272 <filename>/etc/resolv.conf</filename> in the container are not allowed, as it is a read-only bind 1273 mount (but note that if the container has enough privileges, it might simply go ahead and unmount the 1274 bind mount anyway). Note that both if the file is bind mounted and if it is copied no further 1275 propagation of configuration is generally done after the one-time early initialization (this is 1276 because the file is usually updated through copying and renaming). Defaults to 1277 <literal>auto</literal>.</para></listitem> 1278 </varlistentry> 1279 1280 <varlistentry> 1281 <term><option>--timezone=</option></term> 1282 1283 <listitem><para>Configures how <filename>/etc/localtime</filename> inside of the container 1284 (i.e. local timezone synchronization from host to container) shall be handled. Takes one of 1285 <literal>off</literal>, <literal>copy</literal>, <literal>bind</literal>, <literal>symlink</literal>, 1286 <literal>delete</literal> or <literal>auto</literal>. If set to <literal>off</literal> the 1287 <filename>/etc/localtime</filename> file in the container is left as it is included in the image, and 1288 neither modified nor bind mounted over. If set to <literal>copy</literal> the 1289 <filename>/etc/localtime</filename> file of the host is copied into the container. Similarly, if 1290 <literal>bind</literal> is used, the file is bind mounted from the host into the container. If set to 1291 <literal>symlink</literal>, a symlink is created pointing from <filename>/etc/localtime</filename> in 1292 the container to the timezone file in the container that matches the timezone setting on the host. If 1293 set to <literal>delete</literal>, the file in the container is deleted, should it exist. If set to 1294 <literal>auto</literal> and the <filename>/etc/localtime</filename> file of the host is a symlink, 1295 then <literal>symlink</literal> mode is used, and <literal>copy</literal> otherwise, except if the 1296 image is read-only in which case <literal>bind</literal> is used instead. Defaults to 1297 <literal>auto</literal>.</para></listitem> 1298 </varlistentry> 1299 1300 <varlistentry> 1301 <term><option>--link-journal=</option></term> 1302 1303 <listitem><para>Control whether the container's journal shall 1304 be made visible to the host system. If enabled, allows viewing 1305 the container's journal files from the host (but not vice 1306 versa). Takes one of <literal>no</literal>, 1307 <literal>host</literal>, <literal>try-host</literal>, 1308 <literal>guest</literal>, <literal>try-guest</literal>, 1309 <literal>auto</literal>. If <literal>no</literal>, the journal 1310 is not linked. If <literal>host</literal>, the journal files 1311 are stored on the host file system (beneath 1312 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) 1313 and the subdirectory is bind-mounted into the container at the 1314 same location. If <literal>guest</literal>, the journal files 1315 are stored on the guest file system (beneath 1316 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) 1317 and the subdirectory is symlinked into the host at the same 1318 location. <literal>try-host</literal> and 1319 <literal>try-guest</literal> do the same but do not fail if 1320 the host does not have persistent journaling enabled. If 1321 <literal>auto</literal> (the default), and the right 1322 subdirectory of <filename>/var/log/journal</filename> exists, 1323 it will be bind mounted into the container. If the 1324 subdirectory does not exist, no linking is performed. 1325 Effectively, booting a container once with 1326 <literal>guest</literal> or <literal>host</literal> will link 1327 the journal persistently if further on the default of 1328 <literal>auto</literal> is used.</para> 1329 1330 <para>Note that <option>--link-journal=try-guest</option> is the default if the 1331 <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem> 1332 </varlistentry> 1333 1334 <varlistentry> 1335 <term><option>-j</option></term> 1336 1337 <listitem><para>Equivalent to 1338 <option>--link-journal=try-guest</option>.</para></listitem> 1339 </varlistentry> 1340 1341 </variablelist> 1342 1343 </refsect2><refsect2> 1344 <title>Mount Options</title> 1345 1346 <variablelist> 1347 1348 <varlistentry> 1349 <term><option>--bind=</option></term> 1350 <term><option>--bind-ro=</option></term> 1351 1352 <listitem><para>Bind mount a file or directory from the host into the container. Takes one of: a path 1353 argument — in which case the specified path will be mounted from the host to the same path in the container, or 1354 a colon-separated pair of paths — in which case the first specified path is the source in the host, and the 1355 second path is the destination in the container, or a colon-separated triple of source path, destination path 1356 and mount options. The source path may optionally be prefixed with a <literal>+</literal> character. If so, the 1357 source path is taken relative to the image's root directory. This permits setting up bind mounts within the 1358 container image. The source path may be specified as empty string, in which case a temporary directory below 1359 the host's <filename>/var/tmp/</filename> directory is used. It is automatically removed when the container is 1360 shut down. The <option>--bind-ro=</option> option creates read-only bind mounts. Backslash escapes are interpreted, 1361 so <literal>\:</literal> may be used to embed colons in either path. This option may be specified 1362 multiple times for creating multiple independent bind mount points.</para> 1363 1364 <para>Mount options are comma-separated. <option>rbind</option> and <option>norbind</option> control whether 1365 to create a recursive or a regular bind mount. Defaults to "rbind". <option>idmap</option> and <option>noidmap</option> 1366 control if the bind mount should use filesystem id mappings. Using this option requires support by the source filesystem 1367 for id mappings. Defaults to "noidmap".</para> 1368 1369 <para>Note that when this option is used in combination with <option>--private-users</option>, the resulting 1370 mount points will be owned by the <constant>nobody</constant> user. That's because the mount and its files and 1371 directories continue to be owned by the relevant host users and groups, which do not exist in the container, 1372 and thus show up under the wildcard UID 65534 (nobody). If such bind mounts are created, it is recommended to 1373 make them read-only, using <option>--bind-ro=</option>. Alternatively you can use the "idmap" mount option to 1374 map the filesystem ids.</para></listitem> 1375 </varlistentry> 1376 1377 <varlistentry> 1378 <term><option>--bind-user=</option></term> 1379 1380 <listitem><para>Binds the home directory of the specified user on the host into the container. Takes 1381 the name of an existing user on the host as argument. May be used multiple times to bind multiple 1382 users into the container. This does three things:</para> 1383 1384 <orderedlist> 1385 <listitem><para>The user's home directory is bind mounted from the host into 1386 <filename>/run/hosts/home/</filename>.</para></listitem> 1387 1388 <listitem><para>An additional UID/GID mapping is added that maps the host user's UID/GID to a 1389 container UID/GID, allocated from the 60514…60577 range.</para></listitem> 1390 1391 <listitem><para>A JSON user and group record is generated in <filename>/run/userdb/</filename> that 1392 describes the mapped user. It contains a minimized representation of the host's user record, 1393 adjusted to the UID/GID and home directory path assigned to the user in the container. The 1394 <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> 1395 glibc NSS module will pick up these records from there and make them available in the container's 1396 user/group databases.</para></listitem> 1397 </orderedlist> 1398 1399 <para>The combination of the three operations above ensures that it is possible to log into the 1400 container using the same account information as on the host. The user is only mapped transiently, 1401 while the container is running, and the mapping itself does not result in persistent changes to the 1402 container (except maybe for log messages generated at login time, and similar). Note that in 1403 particular the UID/GID assignment in the container is not made persistently. If the user is mapped 1404 transiently, it is best to not allow the user to make persistent changes to the container. If the 1405 user leaves files or directories owned by the user, and those UIDs/GIDs are reused during later 1406 container invocations (possibly with a different <option>--bind-user=</option> mapping), those files 1407 and directories will be accessible to the "new" user.</para> 1408 1409 <para>The user/group record mapping only works if the container contains systemd 249 or newer, with 1410 <command>nss-systemd</command> properly configured in <filename>nsswitch.conf</filename>. See 1411 <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for 1412 details.</para> 1413 1414 <para>Note that the user record propagated from the host into the container will contain the UNIX 1415 password hash of the user, so that seamless logins in the container are possible. If the container is 1416 less trusted than the host it's hence important to use a strong UNIX password hash function 1417 (e.g. yescrypt or similar, with the <literal>$y$</literal> hash prefix).</para> 1418 1419 <para>When binding a user from the host into the container checks are executed to ensure that the 1420 username is not yet known in the container. Moreover, it is checked that the UID/GID allocated for it 1421 is not currently defined in the user/group databases of the container. Both checks directly access 1422 the container's <filename>/etc/passwd</filename> and <filename>/etc/group</filename>, and thus might 1423 not detect existing accounts in other databases.</para> 1424 1425 <para>This operation is only supported in combination with 1426 <option>--private-users=</option>/<option>-U</option>.</para></listitem> 1427 </varlistentry> 1428 1429 <varlistentry> 1430 <term><option>--inaccessible=</option></term> 1431 1432 <listitem><para>Make the specified path inaccessible in the container. This over-mounts the specified path 1433 (which must exist in the container) with a file node of the same type that is empty and has the most 1434 restrictive access mode supported. This is an effective way to mask files, directories and other file system 1435 objects from the container payload. This option may be used more than once in case all specified paths are 1436 masked.</para></listitem> 1437 </varlistentry> 1438 1439 <varlistentry> 1440 <term><option>--tmpfs=</option></term> 1441 1442 <listitem><para>Mount a tmpfs file system into the container. Takes a single absolute path argument that 1443 specifies where to mount the tmpfs instance to (in which case the directory access mode will be chosen as 0755, 1444 owned by root/root), or optionally a colon-separated pair of path and mount option string that is used for 1445 mounting (in which case the kernel default for access mode and owner will be chosen, unless otherwise 1446 specified). Backslash escapes are interpreted in the path, so <literal>\:</literal> may be used to embed colons 1447 in the path.</para> 1448 1449 <para>Note that this option cannot be used to replace the root file system of the container with a temporary 1450 file system. However, the <option>--volatile=</option> option described below provides similar 1451 functionality, with a focus on implementing stateless operating system images.</para></listitem> 1452 </varlistentry> 1453 1454 <varlistentry> 1455 <term><option>--overlay=</option></term> 1456 <term><option>--overlay-ro=</option></term> 1457 1458 <listitem><para>Combine multiple directory trees into one 1459 overlay file system and mount it into the container. Takes a 1460 list of colon-separated paths to the directory trees to 1461 combine and the destination mount point.</para> 1462 1463 <para>Backslash escapes are interpreted in the paths, so 1464 <literal>\:</literal> may be used to embed colons in the paths. 1465 </para> 1466 1467 <para>If three or more paths are specified, then the last 1468 specified path is the destination mount point in the 1469 container, all paths specified before refer to directory trees 1470 on the host and are combined in the specified order into one 1471 overlay file system. The left-most path is hence the lowest 1472 directory tree, the second-to-last path the highest directory 1473 tree in the stacking order. If <option>--overlay-ro=</option> 1474 is used instead of <option>--overlay=</option>, a read-only 1475 overlay file system is created. If a writable overlay file 1476 system is created, all changes made to it are written to the 1477 highest directory tree in the stacking order, i.e. the 1478 second-to-last specified.</para> 1479 1480 <para>If only two paths are specified, then the second 1481 specified path is used both as the top-level directory tree in 1482 the stacking order as seen from the host, as well as the mount 1483 point for the overlay file system in the container. At least 1484 two paths have to be specified.</para> 1485 1486 <para>The source paths may optionally be prefixed with <literal>+</literal> character. If so they are 1487 taken relative to the image's root directory. The uppermost source path may also be specified as an 1488 empty string, in which case a temporary directory below the host's <filename>/var/tmp/</filename> is 1489 used. The directory is removed automatically when the container is shut down. This behaviour is 1490 useful in order to make read-only container directories writable while the container is running. For 1491 example, use <literal>--overlay=+/var::/var</literal> in order to automatically overlay a writable 1492 temporary directory on a read-only <filename>/var/</filename> directory.</para> 1493 1494 <para>For details about overlay file systems, see <ulink 1495 url="https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt">overlayfs.txt</ulink>. Note 1496 that the semantics of overlay file systems are substantially 1497 different from normal file systems, in particular regarding 1498 reported device and inode information. Device and inode 1499 information may change for a file while it is being written 1500 to, and processes might see out-of-date versions of files at 1501 times. Note that this switch automatically derives the 1502 <literal>workdir=</literal> mount option for the overlay file 1503 system from the top-level directory tree, making it a sibling 1504 of it. It is hence essential that the top-level directory tree 1505 is not a mount point itself (since the working directory must 1506 be on the same file system as the top-most directory 1507 tree). Also note that the <literal>lowerdir=</literal> mount 1508 option receives the paths to stack in the opposite order of 1509 this switch.</para> 1510 1511 <para>Note that this option cannot be used to replace the root file system of the container with an overlay 1512 file system. However, the <option>--volatile=</option> option described above provides similar functionality, 1513 with a focus on implementing stateless operating system images.</para></listitem> 1514 </varlistentry> 1515 </variablelist> 1516 1517 </refsect2><refsect2> 1518 <title>Input/Output Options</title> 1519 1520 <variablelist> 1521 <varlistentry> 1522 <term><option>--console=</option><replaceable>MODE</replaceable></term> 1523 1524 <listitem><para>Configures how to set up standard input, output and error output for the container 1525 payload, as well as the <filename>/dev/console</filename> device for the container. Takes one of 1526 <option>interactive</option>, <option>read-only</option>, <option>passive</option>, 1527 <option>pipe</option> or <option>autopipe</option>. If <option>interactive</option>, a pseudo-TTY is 1528 allocated and made available as <filename>/dev/console</filename> in the container. It is then 1529 bi-directionally connected to the standard input and output passed to 1530 <command>systemd-nspawn</command>. <option>read-only</option> is similar but only the output of the 1531 container is propagated and no input from the caller is read. If <option>passive</option>, a pseudo 1532 TTY is allocated, but it is not connected anywhere. In <option>pipe</option> mode no pseudo TTY is 1533 allocated, but the standard input, output and error output file descriptors passed to 1534 <command>systemd-nspawn</command> are passed on — as they are — to the container payload, see the 1535 following paragraph. Finally, <option>autopipe</option> mode operates like 1536 <option>interactive</option> when <command>systemd-nspawn</command> is invoked on a terminal, and 1537 like <option>pipe</option> otherwise. Defaults to <option>interactive</option> if 1538 <command>systemd-nspawn</command> is invoked from a terminal, and <option>read-only</option> 1539 otherwise.</para> 1540 1541 <para>In <option>pipe</option> mode, <filename>/dev/console</filename> will not exist in the 1542 container. This means that the container payload generally cannot be a full init system as init 1543 systems tend to require <filename>/dev/console</filename> to be available. On the other hand, in this 1544 mode container invocations can be used within shell pipelines. This is because intermediary pseudo 1545 TTYs do not permit independent bidirectional propagation of the end-of-file (EOF) condition, which is 1546 necessary for shell pipelines to work correctly. <emphasis>Note that the <option>pipe</option> mode 1547 should be used carefully</emphasis>, as passing arbitrary file descriptors to less trusted container 1548 payloads might open up unwanted interfaces for access by the container payload. For example, if a 1549 passed file descriptor refers to a TTY of some form, APIs such as <constant>TIOCSTI</constant> may be 1550 used to synthesize input that might be used for escaping the container. Hence <option>pipe</option> 1551 mode should only be used if the payload is sufficiently trusted or when the standard 1552 input/output/error output file descriptors are known safe, for example pipes.</para></listitem> 1553 </varlistentry> 1554 1555 <varlistentry> 1556 <term><option>--pipe</option></term> 1557 <term><option>-P</option></term> 1558 1559 <listitem><para>Equivalent to <option>--console=pipe</option>.</para></listitem> 1560 </varlistentry> 1561 </variablelist> 1562 1563 </refsect2><refsect2> 1564 <title>Credentials</title> 1565 1566 <variablelist> 1567 <varlistentry> 1568 <term><option>--load-credential=</option><replaceable>ID</replaceable>:<replaceable>PATH</replaceable></term> 1569 <term><option>--set-credential=</option><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term> 1570 1571 <listitem><para>Pass a credential to the container. These two options correspond to the 1572 <varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See 1573 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 1574 details about these concepts, as well as the syntax of the option's arguments.</para> 1575 1576 <para>Note: when <command>systemd-nspawn</command> runs as systemd system service it can propagate 1577 the credentials it received via <varname>LoadCredential=</varname>/<varname>SetCredential=</varname> 1578 to the container payload. A systemd service manager running as PID 1 in the container can further 1579 propagate them to the services it itself starts. It is thus possible to easily propagate credentials 1580 from a parent service manager to a container manager service and from there into its payload. This 1581 can even be done recursively.</para> 1582 1583 <para>In order to embed binary data into the credential data for <option>--set-credential=</option> 1584 use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to 1585 embed a <constant>NUL</constant> byte. Note that the invoking shell might already apply unescaping 1586 once, hence this might require double escaping!).</para> 1587 1588 <para>The 1589 <citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 1590 and 1591 <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> 1592 services read credentials configured this way for the purpose of configuring the container's root 1593 user's password and shell, as well as system locale, keymap and timezone during the first boot 1594 process of the container. This is particularly useful in combination with 1595 <option>--volatile=yes</option> where every single boot appears as first boot, since configuration 1596 applied to <filename>/etc/</filename> is lost on container reboot cycles. See the respective man 1597 pages for details. Example:</para> 1598 1599 <programlisting># systemd-nspawn -i image.raw \ 1600 --volatile=yes \ 1601 --set-credential=firstboot.locale:de_DE.UTF-8 \ 1602 --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' \ 1603 -b</programlisting> 1604 1605 <para>The above command line will invoke the specified image file <filename>image.raw</filename> in 1606 volatile mode, i.e. with empty <filename>/etc/</filename> and <filename>/var/</filename>. The 1607 container payload will recognize this as a first boot, and will invoke 1608 <filename>systemd-firstboot.service</filename>, which then reads the two passed credentials to 1609 configure the system's initial locale and root password.</para> 1610 </listitem> 1611 </varlistentry> 1612 1613 </variablelist> 1614 1615 </refsect2><refsect2> 1616 <title>Other</title> 1617 1618 <variablelist> 1619 <xi:include href="standard-options.xml" xpointer="no-pager" /> 1620 <xi:include href="standard-options.xml" xpointer="help" /> 1621 <xi:include href="standard-options.xml" xpointer="version" /> 1622 </variablelist> 1623 </refsect2> 1624 </refsect1> 1625 1626 <xi:include href="common-variables.xml" /> 1627 1628 <refsect1> 1629 <title>Examples</title> 1630 1631 <example> 1632 <title>Download a 1633 <ulink url="https://getfedora.org">Fedora</ulink> image and start a shell in it</title> 1634 1635 <programlisting># machinectl pull-raw --verify=no \ 1636 https://download.fedoraproject.org/pub/fedora/linux/releases/&fedora_latest_version;/Cloud/x86_64/images/Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz \ 1637 Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64 1638# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64</programlisting> 1639 1640 <para>This downloads an image using 1641 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> 1642 and opens a shell in it.</para> 1643 </example> 1644 1645 <example> 1646 <title>Build and boot a minimal Fedora distribution in a container</title> 1647 1648 <programlisting># dnf -y --releasever=&fedora_latest_version; --installroot=/var/lib/machines/f&fedora_latest_version; \ 1649 --repo=fedora --repo=updates --setopt=install_weak_deps=False install \ 1650 passwd dnf fedora-release vim-minimal systemd systemd-networkd 1651# systemd-nspawn -bD /var/lib/machines/f&fedora_latest_version;</programlisting> 1652 1653 <para>This installs a minimal Fedora distribution into the 1654 directory <filename index="false">/var/lib/machines/f&fedora_latest_version;</filename> 1655 and then boots that OS in a namespace container. Because the installation 1656 is located underneath the standard <filename>/var/lib/machines/</filename> 1657 directory, it is also possible to start the machine using 1658 <command>systemd-nspawn -M f&fedora_latest_version;</command>.</para> 1659 </example> 1660 1661 <example> 1662 <title>Spawn a shell in a container of a minimal Debian unstable distribution</title> 1663 1664 <programlisting># debootstrap unstable ~/debian-tree/ 1665# systemd-nspawn -D ~/debian-tree/</programlisting> 1666 1667 <para>This installs a minimal Debian unstable distribution into 1668 the directory <filename>~/debian-tree/</filename> and then 1669 spawns a shell from this image in a namespace container.</para> 1670 1671 <para><command>debootstrap</command> supports 1672 <ulink url="https://www.debian.org">Debian</ulink>, 1673 <ulink url="https://www.ubuntu.com">Ubuntu</ulink>, 1674 and <ulink url="https://www.tanglu.org">Tanglu</ulink> 1675 out of the box, so the same command can be used to install any of those. For other 1676 distributions from the Debian family, a mirror has to be specified, see 1677 <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. 1678 </para> 1679 </example> 1680 1681 <example> 1682 <title>Boot a minimal 1683 <ulink url="https://www.archlinux.org">Arch Linux</ulink> distribution in a container</title> 1684 1685 <programlisting># pacstrap -c ~/arch-tree/ base 1686# systemd-nspawn -bD ~/arch-tree/</programlisting> 1687 1688 <para>This installs a minimal Arch Linux distribution into the 1689 directory <filename>~/arch-tree/</filename> and then boots an OS 1690 in a namespace container in it.</para> 1691 </example> 1692 1693 <example> 1694 <title>Install the 1695 <ulink url="https://software.opensuse.org/distributions/tumbleweed">OpenSUSE Tumbleweed</ulink> 1696 rolling distribution</title> 1697 1698 <programlisting># zypper --root=/var/lib/machines/tumbleweed ar -c \ 1699 https://download.opensuse.org/tumbleweed/repo/oss tumbleweed 1700# zypper --root=/var/lib/machines/tumbleweed refresh 1701# zypper --root=/var/lib/machines/tumbleweed install --no-recommends \ 1702 systemd shadow zypper openSUSE-release vim 1703# systemd-nspawn -M tumbleweed passwd root 1704# systemd-nspawn -M tumbleweed -b</programlisting> 1705 </example> 1706 1707 <example> 1708 <title>Boot into an ephemeral snapshot of the host system</title> 1709 1710 <programlisting># systemd-nspawn -D / -xb</programlisting> 1711 1712 <para>This runs a copy of the host system in a snapshot which is removed immediately when the container 1713 exits. All file system changes made during runtime will be lost on shutdown, hence.</para> 1714 </example> 1715 1716 <example> 1717 <title>Run a container with SELinux sandbox security contexts</title> 1718 1719 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container 1720# systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 \ 1721 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting> 1722 </example> 1723 1724 <example> 1725 <title>Run a container with an OSTree deployment</title> 1726 1727 <programlisting># systemd-nspawn -b -i ~/image.raw \ 1728 --pivot-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \ 1729 --bind=+/sysroot/ostree/deploy/$OS/var:/var</programlisting> 1730 </example> 1731 </refsect1> 1732 1733 <refsect1> 1734 <title>Exit status</title> 1735 1736 <para>The exit code of the program executed in the container is 1737 returned.</para> 1738 </refsect1> 1739 1740 <refsect1> 1741 <title>See Also</title> 1742 <para> 1743 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 1744 <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 1745 <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 1746 <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 1747 <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 1748 <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 1749 <citerefentry project='mankier'><refentrytitle>zypper</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 1750 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 1751 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 1752 <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> 1753 </para> 1754 </refsect1> 1755 1756</refentry> 1757