<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY fedora_latest_version "30">
-<!ENTITY fedora_cloud_release "1.2">
+<!ENTITY fedora_latest_version "32">
+<!ENTITY fedora_cloud_release "1.6">
]>
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
container.</para>
<para><command>systemd-nspawn</command> implements the <ulink
- url="https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container Interface</ulink>
- specification.</para>
+ url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> specification.</para>
<para>While running, containers invoked with <command>systemd-nspawn</command> are registered with the
<citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry> service that
all subdirectories and subvolumes below it, but excluding any sub-mounts. May not be specified
together with <option>--image=</option> or <option>--ephemeral</option>.</para>
- <para>Note that this switch leaves host name, machine ID and
+ <para>Note that this switch leaves hostname, machine ID and
all other settings that could identify the instance
unmodified.</para></listitem>
</varlistentry>
<listitem><para>If specified, the container is run with a temporary snapshot of its file system that is removed
immediately when the container terminates. May not be specified together with
<option>--template=</option>.</para>
- <para>Note that this switch leaves host name, machine ID and all other settings that could identify
+ <para>Note that this switch leaves hostname, machine ID and all other settings that could identify
the instance unmodified. Please note that — as with <option>--template=</option> — taking the
temporary snapshot is more efficient on file systems that support subvolume snapshots or 'reflinks'
natively (<literal>btrfs</literal> or new <literal>xfs</literal>) than on more traditional file
a server data partition which are mounted to the appropriate
places in the container. All these partitions must be
identified by the partition types defined by the <ulink
- url="https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
+ url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable
Partitions Specification</ulink>.</para></listitem>
<listitem><para>No partition table, and a single file system spanning the whole image.</para></listitem>
hash partitions are set up if the root hash for them is specified using the <option>--root-hash=</option>
option.</para>
+ <para>Single file system images (i.e. file systems without a surrounding partition table) can be opened using
+ dm-verity if the integrity data is passed using the <option>--root-hash=</option> and
+ <option>--verity-data=</option> (and optionally <option>--root-hash-sig=</option>) options.</para>
+
<para>Any other partitions, such as foreign partitions or swap partitions are not mounted. May not be specified
together with <option>--directory=</option>, <option>--template=</option>.</para></listitem>
</varlistentry>
project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>), then the root
hash is read from it, also as formatted hexadecimal characters. If the extended file attribute is not found (or
is not supported by the underlying file system), but a file with the <filename>.roothash</filename> suffix is
- found next to the image file, bearing otherwise the same name, the root hash is read from it and automatically
- used, also as formatted hexadecimal characters.</para></listitem>
+ found next to the image file, bearing otherwise the same name (except if the image has the
+ <filename>.raw</filename> suffix, in which case the root hash file must not have it in its name), the root hash
+ is read from it and automatically used, also as formatted hexadecimal characters.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--root-hash-sig=</option></term>
+
+ <listitem><para>Takes a PKCS7 formatted binary signature of the <option>--root-hash=</option> option as a path
+ to a DER encoded signature file or as an ASCII base64 string encoding of the DER encoded signature, prefixed
+ by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root hash hex
+ string is valid and done by a public key present in the kernel keyring. If this option is not specified, but a
+ file with the <filename>.roothash.p7s</filename> suffix is found next to the image file, bearing otherwise the
+ same name (except if the image has the <filename>.raw</filename> suffix, in which case the signature file must
+ not have it in its name), the signature is read from it and automatically used.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--verity-data=</option></term>
+
+ <listitem><para>Takes the path to a data integrity (dm-verity) file. This option enables data integrity checks
+ using dm-verity, if a root-hash is passed and if the used image itself does not contains the integrity data.
+ The integrity data must be matched by the root hash. If this option is not specified, but a file with the
+ <filename>.verity</filename> suffix is found next to the image file, bearing otherwise the same name (except if
+ the image has the <filename>.raw</filename> suffix, in which case the verity data file must not have it in its name),
+ the verity data is read from it and automatically used.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option></term>
<term><option>--user=</option></term>
- <listitem><para>After transitioning into the container, change
- to the specified user-defined in the container's user
- database. Like all other systemd-nspawn features, this is not
- a security feature and provides protection against accidental
- destructive operations only.</para></listitem>
+ <listitem><para>After transitioning into the container, change to the specified user defined in the
+ container's user database. Like all other systemd-nspawn features, this is not a security feature and
+ provides protection against accidental destructive operations only.</para></listitem>
</varlistentry>
<varlistentry>
With option <option>yes</option> systemd-nspawn waits for the
<literal>READY=1</literal> message from the init process in the container
before sending its own to systemd. For more details about notifications
- see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).</para></listitem>
+ see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
</varlistentry>
</variablelist>
container, with the exception of the loopback device and those
specified with <option>--network-interface=</option> and
configured with <option>--network-veth</option>. If this
- option is specified, the CAP_NET_ADMIN capability will be
+ option is specified, the <constant>CAP_NET_ADMIN</constant> capability will be
added to the set of capabilities the container retains. The
latter may be disabled by using <option>--drop-capability=</option>.
If this option is not specified (or implied by one of the options
container names may have a length up to 64 characters. As this option derives the host-side interface
name from the container name the name is possibly truncated. Thus, care needs to be taken to ensure
that interface names remain unique in this case, or even better container names are generally not
- chosen longer than 12 characters, to avoid the truncation. Alternatively, the
+ chosen longer than 12 characters, to avoid the truncation. If the name is truncated,
+ <command>systemd-nspawn</command> will automatically append a 4-digit hash value to the name to
+ reduce the chance of collisions. However, the hash algorithm is not collision-free. (See
+ <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details on older naming algorithms for this interface). Alternatively, the
<option>--network-veth-extra=</option> option may be used, which allows free configuration of the
host-side interface name independently of the container name — but might require a bit more
additional configuration in case bridging in a fashion similar to <option>--network-bridge=</option>
<varlistentry>
<term><option>--capability=</option></term>
- <listitem><para>List one or more additional capabilities to grant the container.
- Takes a comma-separated list of capability names, see
- <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <listitem><para>List one or more additional capabilities to grant the container. Takes a
+ comma-separated list of capability names, see <citerefentry
+ project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more information. Note that the following capabilities will be granted in any way:
- CAP_AUDIT_CONTROL, CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
- CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
- CAP_MKNOD, CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETFCAP,
- CAP_SETGID, CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_BOOT, CAP_SYS_CHROOT,
- CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_RESOURCE, CAP_SYS_TTY_CONFIG. Also CAP_NET_ADMIN
- is retained if <option>--private-network</option> is specified. If the special value
- <literal>all</literal> is passed, all capabilities are retained.</para>
+ <constant>CAP_AUDIT_CONTROL</constant>, <constant>CAP_AUDIT_WRITE</constant>,
+ <constant>CAP_CHOWN</constant>, <constant>CAP_DAC_OVERRIDE</constant>,
+ <constant>CAP_DAC_READ_SEARCH</constant>, <constant>CAP_FOWNER</constant>,
+ <constant>CAP_FSETID</constant>, <constant>CAP_IPC_OWNER</constant>, <constant>CAP_KILL</constant>,
+ <constant>CAP_LEASE</constant>, <constant>CAP_LINUX_IMMUTABLE</constant>,
+ <constant>CAP_MKNOD</constant>, <constant>CAP_NET_BIND_SERVICE</constant>,
+ <constant>CAP_NET_BROADCAST</constant>, <constant>CAP_NET_RAW</constant>,
+ <constant>CAP_SETFCAP</constant>, <constant>CAP_SETGID</constant>, <constant>CAP_SETPCAP</constant>,
+ <constant>CAP_SETUID</constant>, <constant>CAP_SYS_ADMIN</constant>,
+ <constant>CAP_SYS_BOOT</constant>, <constant>CAP_SYS_CHROOT</constant>,
+ <constant>CAP_SYS_NICE</constant>, <constant>CAP_SYS_PTRACE</constant>,
+ <constant>CAP_SYS_RESOURCE</constant>, <constant>CAP_SYS_TTY_CONFIG</constant>. Also
+ <constant>CAP_NET_ADMIN</constant> is retained if <option>--private-network</option> is specified.
+ If the special value <literal>all</literal> is passed, all capabilities are retained.</para>
<para>If the special value of <literal>help</literal> is passed, the program will print known
capability names and exit.</para></listitem>
<varlistentry>
<term><option>--no-new-privileges=</option></term>
- <listitem><para>Takes a boolean argument. Specifies the value of the <constant>PR_SET_NO_NEW_PRIVS</constant>
- flag for the container payload. Defaults to off. When turned on the payload code of the container cannot
- acquire new privileges, i.e. the "setuid" file bit as well as file system capabilities will not have an effect
- anymore. See <citerefentry
- project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details
- about this flag. </para></listitem>
+ <listitem><para>Takes a boolean argument. Specifies the value of the
+ <constant>PR_SET_NO_NEW_PRIVS</constant> flag for the container payload. Defaults to off. When turned
+ on the payload code of the container cannot acquire new privileges, i.e. the "setuid" file bit as
+ well as file system capabilities will not have an effect anymore. See <citerefentry
+ project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+ details about this flag. </para></listitem>
</varlistentry>
<varlistentry>
- <term><option>--system-call-filter=</option></term>
-
- <listitem><para>Alter the system call filter applied to containers. Takes a space-separated list of system call
- names or group names (the latter prefixed with <literal>@</literal>, as listed by the
- <command>syscall-filter</command> command of
+ <term><option>--system-call-filter=</option></term> <listitem><para>Alter the system call filter
+ applied to containers. Takes a space-separated list of system call names or group names (the latter
+ prefixed with <literal>@</literal>, as listed by the <command>syscall-filter</command> command of
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>). Passed
- system calls will be permitted. The list may optionally be prefixed by <literal>~</literal>, in which case all
- listed system calls are prohibited. If this command line option is used multiple times the configured lists are
- combined. If both a positive and a negative list (that is one system call list without and one with the
- <literal>~</literal> prefix) are configured, the negative list takes precedence over the positive list. Note
- that <command>systemd-nspawn</command> always implements a system call whitelist (as opposed to a blacklist),
- and this command line option hence adds or removes entries from the default whitelist, depending on the
- <literal>~</literal> prefix. Note that the applied system call filter is also altered implicitly if additional
- capabilities are passed using the <command>--capabilities=</command>.</para></listitem>
+ system calls will be permitted. The list may optionally be prefixed by <literal>~</literal>, in which
+ case all listed system calls are prohibited. If this command line option is used multiple times the
+ configured lists are combined. If both a positive and a negative list (that is one system call list
+ without and one with the <literal>~</literal> prefix) are configured, the negative list takes
+ precedence over the positive list. Note that <command>systemd-nspawn</command> always implements a
+ system call allow list (as opposed to a deny list!), and this command line option hence adds or
+ removes entries from the default allow list, depending on the <literal>~</literal> prefix. Note that
+ the applied system call filter is also altered implicitly if additional capabilities are passed using
+ the <command>--capabilities=</command>.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>--resolv-conf=</option></term>
- <listitem><para>Configures how <filename>/etc/resolv.conf</filename> inside of the container (i.e. DNS
- configuration synchronization from host to container) shall be handled. Takes one of <literal>off</literal>,
- <literal>copy-host</literal>, <literal>copy-static</literal>, <literal>bind-host</literal>,
- <literal>bind-static</literal>, <literal>delete</literal> or <literal>auto</literal>. If set to
- <literal>off</literal> the <filename>/etc/resolv.conf</filename> file in the container is left as it is
- included in the image, and neither modified nor bind mounted over. If set to <literal>copy-host</literal>, the
- <filename>/etc/resolv.conf</filename> file from the host is copied into the container. Similar, if
- <literal>bind-host</literal> is used, the file is bind mounted from the host into the container. If set to
- <literal>copy-static</literal> the static <filename>resolv.conf</filename> file supplied with
- <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> is
- copied into the container, and correspondingly <literal>bind-static</literal> bind mounts it there. If set to
- <literal>delete</literal> the <filename>/etc/resolv.conf</filename> file in the container is deleted if it
- exists. Finally, if set to <literal>auto</literal> the file is left as it is if private networking is turned on
- (see <option>--private-network</option>). Otherwise, if <filename>systemd-resolved.service</filename> is
- connectible its static <filename>resolv.conf</filename> file is used, and if not the host's
- <filename>/etc/resolv.conf</filename> file is used. In the latter cases the file is copied if the image is
- writable, and bind mounted otherwise. It's recommended to use <literal>copy</literal> if the container shall be
- able to make changes to the DNS configuration on its own, deviating from the host's settings. Otherwise
- <literal>bind</literal> is preferable, as it means direct changes to <filename>/etc/resolv.conf</filename> in
- the container are not allowed, as it is a read-only bind mount (but note that if the container has enough
- privileges, it might simply go ahead and unmount the bind mount anyway). Note that both if the file is bind
- mounted and if it is copied no further propagation of configuration is generally done after the one-time early
- initialization (this is because the file is usually updated through copying and renaming). Defaults to
+ <listitem><para>Configures how <filename>/etc/resolv.conf</filename> inside of the container shall be
+ handled (i.e. DNS configuration synchronization from host to container). Takes one of
+ <literal>off</literal>, <literal>copy-host</literal>, <literal>copy-static</literal>,
+ <literal>copy-uplink</literal>, <literal>copy-stub</literal>, <literal>replace-host</literal>,
+ <literal>replace-static</literal>, <literal>replace-uplink</literal>,
+ <literal>replace-stub</literal>, <literal>bind-host</literal>, <literal>bind-static</literal>,
+ <literal>bind-uplink</literal>, <literal>bind-stub</literal>, <literal>delete</literal> or
+ <literal>auto</literal>.</para>
+
+ <para>If set to <literal>off</literal> the <filename>/etc/resolv.conf</filename> file in the
+ container is left as it is included in the image, and neither modified nor bind mounted over.</para>
+
+ <para>If set to <literal>copy-host</literal>, the <filename>/etc/resolv.conf</filename> file from the
+ host is copied into the container, unless the file exists already and is not a regular file (e.g. a
+ symlink). Similar, if <literal>replace-host</literal> is used the file is copied, replacing any
+ existing inode, including symlinks. Similar, if <literal>bind-host</literal> is used, the file is
+ bind mounted from the host into the container.</para>
+
+ <para>If set to <literal>copy-static</literal>, <literal>replace-static</literal> or
+ <literal>bind-static</literal> the static <filename>resolv.conf</filename> file supplied with
+ <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ (specifically: <filename>/usr/lib/systemd/resolv.conf</filename>) is copied or bind mounted into the
+ container.</para>
+
+ <para>If set to <literal>copy-uplink</literal>, <literal>replace-uplink</literal> or
+ <literal>bind-uplink</literal> the uplink <filename>resolv.conf</filename> file managed by
+ <filename>systemd-resolved.service</filename> (specifically:
+ <filename>/run/systemd/resolve/resolv.conf</filename>) is copied or bind mounted into the
+ container.</para>
+
+ <para>If set to <literal>copy-stub</literal>, <literal>replace-stub</literal> or
+ <literal>bind-stub</literal> the stub <filename>resolv.conf</filename> file managed by
+ <filename>systemd-resolved.service</filename> (specifically:
+ <filename>/run/systemd/resolve/stub-resolv.conf</filename>) is copied or bind mounted into the
+ container.</para>
+
+ <para>If set to <literal>delete</literal> the <filename>/etc/resolv.conf</filename> file in the
+ container is deleted if it exists.</para>
+
+ <para>Finally, if set to <literal>auto</literal> the file is left as it is if private networking is
+ turned on (see <option>--private-network</option>). Otherwise, if
+ <filename>systemd-resolved.service</filename> is running its stub <filename>resolv.conf</filename>
+ file is used, and if not the host's <filename>/etc/resolv.conf</filename> file. In the latter cases
+ the file is copied if the image is writable, and bind mounted otherwise.</para>
+
+ <para>It's recommended to use <literal>copy-…</literal> or <literal>replace-…</literal> if the
+ container shall be able to make changes to the DNS configuration on its own, deviating from the
+ host's settings. Otherwise <literal>bind</literal> is preferable, as it means direct changes to
+ <filename>/etc/resolv.conf</filename> in the container are not allowed, as it is a read-only bind
+ mount (but note that if the container has enough privileges, it might simply go ahead and unmount the
+ bind mount anyway). Note that both if the file is bind mounted and if it is copied no further
+ propagation of configuration is generally done after the one-time early initialization (this is
+ because the file is usually updated through copying and renaming). Defaults to
<literal>auto</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--timezone=</option></term>
- <listitem><para>Configures how <filename>/etc/localtime</filename> inside of the container (i.e. local timezone
- synchronization from host to container) shall be handled. Takes one of <literal>off</literal>,
- <literal>copy</literal>, <literal>bind</literal>, <literal>symlink</literal>, <literal>delete</literal> or
- <literal>auto</literal>. If set to <literal>off</literal> the <filename>/etc/localtime</filename> file in the
- container is left as it is included in the image, and neither modified nor bind mounted over. If set to
- <literal>copy</literal> the <filename>/etc/localtime</filename> file of the host is copied into the
- container. Similar, if <literal>bind</literal> is used, it is bind mounted from the host into the container. If
- set to <literal>symlink</literal> a symlink from <filename>/etc/localtime</filename> in the container is
- created pointing to the matching the timezone file of the container that matches the timezone setting on the
- host. If set to <literal>delete</literal> the file in the container is deleted, should it exist. If set to
- <literal>auto</literal> and the <filename>/etc/localtime</filename> file of the host is a symlink, then
- <literal>symlink</literal> mode is used, and <literal>copy</literal> otherwise, except if the image is
- read-only in which case <literal>bind</literal> is used instead. Defaults to
+ <listitem><para>Configures how <filename>/etc/localtime</filename> inside of the container
+ (i.e. local timezone synchronization from host to container) shall be handled. Takes one of
+ <literal>off</literal>, <literal>copy</literal>, <literal>bind</literal>, <literal>symlink</literal>,
+ <literal>delete</literal> or <literal>auto</literal>. If set to <literal>off</literal> the
+ <filename>/etc/localtime</filename> file in the container is left as it is included in the image, and
+ neither modified nor bind mounted over. If set to <literal>copy</literal> the
+ <filename>/etc/localtime</filename> file of the host is copied into the container. Similarly, if
+ <literal>bind</literal> is used, the file is bind mounted from the host into the container. If set to
+ <literal>symlink</literal>, a symlink is created pointing from <filename>/etc/localtime</filename> in
+ the container to the timezone file in the container that matches the timezone setting on the host. If
+ set to <literal>delete</literal>, the file in the container is deleted, should it exist. If set to
+ <literal>auto</literal> and the <filename>/etc/localtime</filename> file of the host is a symlink,
+ then <literal>symlink</literal> mode is used, and <literal>copy</literal> otherwise, except if the
+ image is read-only in which case <literal>bind</literal> is used instead. Defaults to
<literal>auto</literal>.</para></listitem>
</varlistentry>
<programlisting># dnf -y --releasever=&fedora_latest_version; --installroot=/var/lib/machines/f&fedora_latest_version; \
--disablerepo='*' --enablerepo=fedora --enablerepo=updates install \
- systemd passwd dnf fedora-release vim-minimal
+ systemd passwd dnf fedora-release vim-minimal glibc-minimal-langpack
# systemd-nspawn -bD /var/lib/machines/f&fedora_latest_version;</programlisting>
<para>This installs a minimal Fedora distribution into the
- directory <filename noindex='true'>/var/lib/machines/f&fedora_latest_version;</filename>
- and then boots an OS in a namespace container in it. Because the installation
+ directory <filename index="false">/var/lib/machines/f&fedora_latest_version;</filename>
+ and then boots that OS in a namespace container. Because the installation
is located underneath the standard <filename>/var/lib/machines/</filename>
directory, it is also possible to start the machine using
<command>systemd-nspawn -M f&fedora_latest_version;</command>.</para>
<para>This installs a minimal Debian unstable distribution into
the directory <filename>~/debian-tree/</filename> and then
- spawns a shell in a namespace container in it.</para>
+ spawns a shell from this image in a namespace container.</para>
<para><command>debootstrap</command> supports
<ulink url="https://www.debian.org">Debian</ulink>,
projects / thirdparty / systemd.git / blobdiff