<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details.</para>
- <para>Note that setting this option to <option>yes</option> or <option>state</option> will only work correctly
- with operating systems in the container that can boot up with only <filename>/usr</filename> mounted, and are
- able to automatically populate <filename>/var</filename>, and also <filename>/etc</filename> in case of
- <literal>--volatile=yes</literal>. The <option>overlay</option> option does not require any particular
- preparations in the OS, but do note that <literal>overlayfs</literal> behaviour differs from regular file
- systems in a number of ways, and hence compatibility is limited.</para></listitem>
+ <para>Note that setting this option to <option>yes</option> or <option>state</option> will only work
+ correctly with operating systems in the container that can boot up with only
+ <filename>/usr/</filename> mounted, and are able to automatically populate <filename>/var/</filename>
+ (and <filename>/etc/</filename> in case of <literal>--volatile=yes</literal>). Specifically, this
+ means that operating systems that follow the historic split of <filename>/bin/</filename> and
+ <filename>/lib/</filename> (and related directories) from <filename>/usr/</filename> (i.e. where the
+ former are not symlinks into the latter) are not supported by <literal>--volatile=yes</literal> as
+ container payload. The <option>overlay</option> option does not require any particular preparations
+ in the OS, but do note that <literal>overlayfs</literal> behaviour differs from regular file systems
+ in a number of ways, and hence compatibility is limited.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>--private-users-chown</option></term>
- <listitem><para>If specified, all files and directories in the container's directory tree will adjusted so that
- they are owned to the appropriate UIDs/GIDs selected for the container (see above). This operation is
- potentially expensive, as it involves descending and iterating through the full directory tree of the
- container. Besides actual file ownership, file ACLs are adjusted as well.</para>
+ <listitem><para>If specified, all files and directories in the container's directory tree will be
+ adjusted so that they are owned by the appropriate UIDs/GIDs selected for the container (see above).
+ This operation is potentially expensive, as it involves iterating through the full directory tree of
+ the container. Besides actual file ownership, file ACLs are adjusted as well.</para>
<para>This option is implied if <option>--private-users=pick</option> is used. This option has no effect if
user namespacing is not used.</para></listitem>
<varlistentry>
<term><option>--console=</option><replaceable>MODE</replaceable></term>
- <listitem><para>Configures how to set up standard input, output and error output for the container payload, as
- well as the <filename>/dev/console</filename> device for the container. Takes one of
- <option>interactive</option>, <option>read-only</option>, <option>passive</option> or <option>pipe</option>. If
- <option>interactive</option> a pseudo-TTY is allocated and made available as <filename>/dev/console</filename>
- in the container. It is then bi-directionally connected to the standard input and output passed to
- <command>systemd-nspawn</command>. <option>read-only</option> is similar but only the output of the container
- is propagated and no input from the caller is read. In <option>passive</option> mode a pseudo TTY is allocated,
- but it is not connected anywhere. Finally, in <option>pipe</option> mode no pseudo TTY is allocated, but the
- passed standard input, output and error output file descriptors are passed on — as they are — to the container
- payload. In this mode <filename>/dev/console</filename> will not exist in the container. Note that in this mode
- the container payload generally cannot be a full init system as init systems tend to require
- <filename>/dev/console</filename> to be available. On the other hand, in this mode container invocations can be
- used within shell pipelines. This is because intermediary pseudo TTYs do not permit independent bidirectional
- propagation of the end-of-file (EOF) condition, which is necessary for shell pipelines to work
- correctly.</para>
-
- <para>Note that the <option>pipe</option> mode should be used carefully, as passing arbitrary file descriptors
- to less trusted container payloads might open up unwanted interfaces for access by the container payload. For
- example, if a passed file descriptor refers to a TTY of some form, APIs such as <constant>TIOCSTI</constant>
- may be used to synthesize input that might be used for escaping the container. Hence <option>pipe</option> mode
- should only be used if the payload is sufficiently trusted or when the standard input/output/error output file
- descriptors are known safe, for example pipes. Defaults to <option>interactive</option> if
+ <listitem><para>Configures how to set up standard input, output and error output for the container
+ payload, as well as the <filename>/dev/console</filename> device for the container. Takes one of
+ <option>interactive</option>, <option>read-only</option>, <option>passive</option>, or
+ <option>pipe</option>. If <option>interactive</option>, a pseudo-TTY is allocated and made available
+ as <filename>/dev/console</filename> in the container. It is then bi-directionally connected to the
+ standard input and output passed to <command>systemd-nspawn</command>. <option>read-only</option> is
+ similar but only the output of the container is propagated and no input from the caller is read. If
+ <option>passive</option>, a pseudo TTY is allocated, but it is not connected anywhere. Finally, in
+ <option>pipe</option> mode no pseudo TTY is allocated, but the standard input, output and error
+ output file descriptors passed to <command>systemd-nspawn</command> are passed on — as they are — to
+ the container payload, see the following paragraph. Defaults to <option>interactive</option> if
<command>systemd-nspawn</command> is invoked from a terminal, and <option>read-only</option>
- otherwise.</para></listitem>
+ otherwise.</para>
+
+ <para>In <option>pipe</option> mode, <filename>/dev/console</filename> will not exist in the
+ container. This means that the container payload generally cannot be a full init system as init
+ systems tend to require <filename>/dev/console</filename> to be available. On the other hand, in this
+ mode container invocations can be used within shell pipelines. This is because intermediary pseudo
+ TTYs do not permit independent bidirectional propagation of the end-of-file (EOF) condition, which is
+ necessary for shell pipelines to work correctly. <emphasis>Note that the <option>pipe</option> mode
+ should be used carefully</emphasis>, as passing arbitrary file descriptors to less trusted container
+ payloads might open up unwanted interfaces for access by the container payload. For example, if a
+ passed file descriptor refers to a TTY of some form, APIs such as <constant>TIOCSTI</constant> may be
+ used to synthesize input that might be used for escaping the container. Hence <option>pipe</option>
+ mode should only be used if the payload is sufficiently trusted or when the standard
+ input/output/error output file descriptors are known safe, for example pipes.</para></listitem>
</varlistentry>
<varlistentry>
<ulink url="https://getfedora.org">Fedora</ulink> image and start a shell in it</title>
<programlisting># machinectl pull-raw --verify=no \
- 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
-# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64</programlisting>
+ 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 \
+ Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64
+# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64</programlisting>
<para>This downloads an image using
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
# 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>
+ directory <filename index="false">/var/lib/machines/f&fedora_latest_version;</filename>
and then boots an OS in a namespace container in it. Because the installation
is located underneath the standard <filename>/var/lib/machines/</filename>
directory, it is also possible to start the machine using
<title>Boot a minimal
<ulink url="https://www.archlinux.org">Arch Linux</ulink> distribution in a container</title>
- <programlisting># pacstrap -c -d ~/arch-tree/ base
+ <programlisting># pacstrap -c ~/arch-tree/ base
# systemd-nspawn -bD ~/arch-tree/</programlisting>
<para>This installs a minimal Arch Linux distribution into the