<para>As a safety check <command>systemd-nspawn</command> will verify the existence of
<filename>/usr/lib/os-release</filename> or <filename>/etc/os-release</filename> in the container tree before
- starting the container (see
+ booting a container (see
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It might be
necessary to add this file to the container tree manually if the OS of the container is too old to contain this
file out-of-the-box.</para>
template unit file <filename>systemd-nspawn@.service</filename> is provided to make this easy, taking the container
name as instance identifier. Note that different default options apply when <command>systemd-nspawn</command> is
invoked by the template unit file than interactively on the command line. Most importantly the template unit file
- makes use of the <option>--boot</option> which is not the default in case <command>systemd-nspawn</command> is
- invoked from the interactive command line. Further differences with the defaults are documented along with the
+ makes use of the <option>--boot</option> option which is not the default in case <command>systemd-nspawn</command>
+ is invoked from the interactive command line. Further differences with the defaults are documented along with the
various supported options below.</para>
<para>The <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool may
<para>Note that running two <command>systemd-nspawn</command> containers from the same directory tree will not make
processes in them see each other. The PID namespace separation of the two containers is complete and the containers
- will share very few runtime objects except for the underlying file system. Use
+ will share very few runtime objects except for the underlying file system. Rather use
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>login</command> or <command>shell</command> commands to request an additional login session in a running
container.</para>
<refsect1>
<title>Options</title>
- <para>If option <option>-b</option> is specified, the arguments
+ <para>If option <option>--boot</option> is specified, the arguments
are used as arguments for the init program. Otherwise,
<replaceable>COMMAND</replaceable> specifies the program to launch
in the container, and the remaining arguments are used as
<listitem><para>Set a unit property on the scope unit to register for the machine. This applies only if the
machine is run in its own scope unit, i.e. if <option>--keep-unit</option> isn't used. Takes unit property
assignments in the same format as <command>systemctl set-property</command>. This is useful to set memory
- limits and similar for container.</para>
+ limits and similar for the container.</para>
</listitem>
</varlistentry>
the UID/GID range is automatically chosen. As first step, the file owner UID/GID of the root
directory of the container's directory tree is read, and it is checked that no other container is
currently using it. If this check is successful, the UID/GID range determined this way is used,
- similar to the behavior if <literal>yes</literal> is specified. If the check is not successful (and
- thus the UID/GID range indicated in the root directory's file owner is already used elsewhere) a
- new – currently unused – UID/GID range of 65536 UIDs/GIDs is randomly chosen between the host
+ similarly to the behavior if <literal>yes</literal> is specified. If the check is not successful
+ (and thus the UID/GID range indicated in the root directory's file owner is already used elsewhere)
+ a new – currently unused – UID/GID range of 65536 UIDs/GIDs is randomly chosen between the host
UID/GIDs of 524288 and 1878982656, always starting at a multiple of 65536, and, if possible,
consistently hashed from the machine name. This setting implies
<option>--private-users-ownership=auto</option> (see below), which possibly has the effect that the
<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
+ symlink). Similarly, if <literal>replace-host</literal> is used the file is copied, replacing any
+ existing inode, including symlinks. Similarly, 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
source path is taken relative to the image's root directory. This permits setting up bind mounts within the
container image. The source path may be specified as empty string, in which case a temporary directory below
the host's <filename>/var/tmp/</filename> directory is used. It is automatically removed when the container is
- shut down. The <option>--bind-ro=</option> option creates read-only bind mounts. Backslash escapes are interpreted,
+ shut down. If the source path is not absolute, it is resolved relative to the current working directory.
+ The <option>--bind-ro=</option> option creates read-only bind mounts. Backslash escapes are interpreted,
so <literal>\:</literal> may be used to embed colons in either path. This option may be specified
multiple times for creating multiple independent bind mount points.</para>
<term><option>--overlay=</option></term>
<term><option>--overlay-ro=</option></term>
- <listitem><para>Combine multiple directory trees into one
- overlay file system and mount it into the container. Takes a
- list of colon-separated paths to the directory trees to
- combine and the destination mount point.</para>
+ <listitem><para>Combine multiple directory trees into one overlay file system and mount it into the
+ container. Takes a list of colon-separated paths to the directory trees to combine and the
+ destination mount point.</para>
- <para>Backslash escapes are interpreted in the paths, so
- <literal>\:</literal> may be used to embed colons in the paths.
+ <para>Backslash escapes are interpreted in the paths, so <literal>\:</literal> may be used to embed
+ colons in the paths.</para>
+
+ <para>If three or more paths are specified, then the last specified path is the destination mount
+ point in the container, all paths specified before refer to directory trees on the host and are
+ combined in the specified order into one overlay file system. The left-most path is hence the lowest
+ directory tree, the second-to-last path the highest directory tree in the stacking order. If
+ <option>--overlay-ro=</option> is used instead of <option>--overlay=</option>, a read-only overlay
+ file system is created. If a writable overlay file system is created, all changes made to it are
+ written to the highest directory tree in the stacking order, i.e. the second-to-last specified.
</para>
- <para>If three or more paths are specified, then the last
- specified path is the destination mount point in the
- container, all paths specified before refer to directory trees
- on the host and are combined in the specified order into one
- overlay file system. The left-most path is hence the lowest
- directory tree, the second-to-last path the highest directory
- tree in the stacking order. If <option>--overlay-ro=</option>
- is used instead of <option>--overlay=</option>, a read-only
- overlay file system is created. If a writable overlay file
- system is created, all changes made to it are written to the
- highest directory tree in the stacking order, i.e. the
- second-to-last specified.</para>
-
- <para>If only two paths are specified, then the second
- specified path is used both as the top-level directory tree in
- the stacking order as seen from the host, as well as the mount
- point for the overlay file system in the container. At least
- two paths have to be specified.</para>
+ <para>If only two paths are specified, then the second specified path is used both as the top-level
+ directory tree in the stacking order as seen from the host, as well as the mount point for the
+ overlay file system in the container. At least two paths have to be specified.</para>
<para>The source paths may optionally be prefixed with <literal>+</literal> character. If so they are
taken relative to the image's root directory. The uppermost source path may also be specified as an
used. The directory is removed automatically when the container is shut down. This behaviour is
useful in order to make read-only container directories writable while the container is running. For
example, use <literal>--overlay=+/var::/var</literal> in order to automatically overlay a writable
- temporary directory on a read-only <filename>/var/</filename> directory.</para>
+ temporary directory on a read-only <filename>/var/</filename> directory. If a source path is not
+ absolute, it is resolved relative to the current working directory.</para>
<para>For details about overlay file systems, see <ulink
- url="https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt">overlayfs.txt</ulink>. Note
- that the semantics of overlay file systems are substantially
- different from normal file systems, in particular regarding
- reported device and inode information. Device and inode
- information may change for a file while it is being written
- to, and processes might see out-of-date versions of files at
- times. Note that this switch automatically derives the
- <literal>workdir=</literal> mount option for the overlay file
- system from the top-level directory tree, making it a sibling
- of it. It is hence essential that the top-level directory tree
- is not a mount point itself (since the working directory must
- be on the same file system as the top-most directory
- tree). Also note that the <literal>lowerdir=</literal> mount
- option receives the paths to stack in the opposite order of
- this switch.</para>
+ url="https://docs.kernel.org/filesystems/overlayfs.html">Overlay Filesystem</ulink>.
+ Note that the semantics of overlay file systems are substantially different from normal file systems,
+ in particular regarding reported device and inode information. Device and inode information may
+ change for a file while it is being written to, and processes might see out-of-date versions of files
+ at times. Note that this switch automatically derives the <literal>workdir=</literal> mount option
+ for the overlay file system from the top-level directory tree, making it a sibling of it. It is hence
+ essential that the top-level directory tree is not a mount point itself (since the working directory
+ must be on the same file system as the top-most directory tree). Also note that the
+ <literal>lowerdir=</literal> mount option receives the paths to stack in the opposite order of this
+ switch.</para>
<para>Note that this option cannot be used to replace the root file system of the container with an overlay
file system. However, the <option>--volatile=</option> option described above provides similar functionality,
projects / thirdparty / systemd.git / blobdiff