keeps track of running containers, and provides programming interfaces to interact with them.</para>
</refsect1>
+ <refsect1>
+ <title>Unprivileged Operation</title>
+
+ <para><command>systemd-nspawn</command> may be invoked with or without privileges. The full functionality
+ is currently only available when invoked with privileges. When invoked without privileges, various
+ limitations apply, including, but not limited to:</para>
+
+ <itemizedlist>
+ <listitem><para>Only disk image based containers are supported (i.e. <option>--image=</option>).
+ Directory based ones (i.e. <option>--directory=</option>) are not supported.</para></listitem>
+
+ <listitem><para>Machine registration via <option>--machine=</option> is not supported.</para></listitem>
+
+ <listitem><para>Only <option>--private-network</option> and <option>--network-veth</option> networking modes are supported.</para></listitem>
+ </itemizedlist>
+
+ <para>When running in unprivileged mode, some needed functionality is provided via
+ <citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd-nsresourced.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
+ </refsect1>
+
<refsect1>
<title>Options</title>
</varlistentry>
<varlistentry>
- <term><option>--settings=</option><replaceable>MODE</replaceable></term>
+ <term><option>--settings=<replaceable>MODE</replaceable></option></term>
<listitem><para>Controls whether
<command>systemd-nspawn</command> shall search for and use
<term><option>-D</option></term>
<term><option>--directory=</option></term>
- <listitem><para>Directory to use as file system root for the
- container.</para>
+ <listitem><para>Directory to use as file system root for the container.</para>
- <para>If neither <option>--directory=</option>, nor
- <option>--image=</option> is specified the directory is
- determined by searching for a directory named the same as the
- machine name specified with <option>--machine=</option>. See
+ <para>If neither <option>--directory=</option>, nor <option>--image=</option> is specified the
+ directory is determined by searching for a directory named the same as the machine name specified
+ with <option>--machine=</option>. See
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
section "Files and Directories" for the precise search path.</para>
- <para>If neither <option>--directory=</option>,
- <option>--image=</option>, nor <option>--machine=</option>
- are specified, the current directory will
- be used. May not be specified together with
- <option>--image=</option>.</para></listitem>
+ <xi:include href="vpick.xml" xpointer="directory"/>
+
+ <para>If neither <option>--directory=</option>, <option>--image=</option>, nor
+ <option>--machine=</option> are specified, the current directory will be used. May not be specified
+ together with <option>--image=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<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>
+ <xi:include href="vpick.xml" xpointer="image"/>
+
<xi:include href="version-info.xml" xpointer="v211"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--volatile</option></term>
- <term><option>--volatile=</option><replaceable>MODE</replaceable></term>
+ <term><option>--volatile=<replaceable>MODE</replaceable></option></term>
<listitem><para>Boots the container in volatile mode. When no mode parameter is passed or when mode is
specified as <option>yes</option>, full volatile mode is enabled. This means the root directory is mounted as a
<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>
+ provides protection against accidental destructive operations only.</para>
+
+ <para>Note that if credentials are used in combination with a non-root <option>--user=</option>
+ (e.g.: <option>--set-credential=</option>, <option>--load-credential=</option> or
+ <option>--import-credential=</option>), then <option>--no-new-privileges=yes</option> must be used, and
+ <option>--boot</option> or <option>--as-pid2</option> must not be used, as the credentials would
+ otherwise be unreadable by the container due to missing privileges after switching to the specified
+ user.</para></listitem>
</varlistentry>
<varlistentry>
and the subdirectory is symlinked into the host at the same
location. <literal>try-host</literal> and
<literal>try-guest</literal> do the same but do not fail if
- the host does not have persistent journaling enabled. If
+ the host does not have persistent journaling enabled, or if
+ the container is in the <option>--ephemeral</option> mode. If
<literal>auto</literal> (the default), and the right
subdirectory of <filename>/var/log/journal</filename> exists,
it will be bind mounted into the container. If the
<para>Mount options are comma-separated. <option>rbind</option> and <option>norbind</option> control whether
to create a recursive or a regular bind mount. Defaults to <option>rbind</option>. <option>noidmap</option>,
- <option>idmap</option>, and <option>rootidmap</option> control ID mapping.</para>
+ <option>idmap</option>, <option>rootidmap</option> and <option>owneridmap</option> control ID mapping.</para>
- <para>Using <option>idmap</option> or <option>rootidmap</option> requires support by the source filesystem
- for user/group ID mapped mounts. Defaults to <option>noidmap</option>. With <option>x</option> being the container's UID range
- offset, <option>y</option> being the length of the container's UID range, and <option>p</option> being the
- owner UID of the bind mount source inode on the host:
+ <para>Using <option>idmap</option>, <option>rootidmap</option> or <option>owneridmap</option> requires support
+ by the source filesystem for user/group ID mapped mounts. Defaults to <option>noidmap</option>. With
+ <option>x</option> being the container's UID range offset, <option>y</option> being the length of the
+ container's UID range, and <option>p</option> being the owner UID of the bind mount source inode on the host:
<itemizedlist>
<listitem><para>If <option>noidmap</option> is used, any user <option>z</option> in the range
<listitem><para>If <option>rootidmap</option> is used, the user <option>0</option> seen from inside
of the container is mapped to <option>p</option> on the host. Other host users are mapped to
<option>nobody</option> inside the container.</para></listitem>
+
+ <listitem><para>If <option>owneridmap</option> is used, the owner of the target directory inside of the
+ container is mapped to <option>p</option> on the host. Other host users are mapped to
+ <option>nobody</option> inside the container.</para></listitem>
</itemizedlist></para>
<para>Whichever ID mapping option is used, the same mapping will be used for users and groups IDs. If
- <option>rootidmap</option> is used, the group owning the bind mounted directory will have no effect.</para>
+ <option>rootidmap</option> or <option>owneridmap</option> are used, the group owning the bind mounted directory
+ will have no effect.</para>
<para>Note that when this option is used in combination with <option>--private-users</option>, the resulting
mount points will be owned by the <constant>nobody</constant> user. That's because the mount and its files and
<variablelist>
<varlistentry>
- <term><option>--console=</option><replaceable>MODE</replaceable></term>
+ <term><option>--console=<replaceable>MODE</replaceable></option></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
<xi:include href="version-info.xml" xpointer="v242"/></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--background=<replaceable>COLOR</replaceable></option></term>
+
+ <listitem><para>Change the terminal background color to the specified ANSI color as long as the
+ container runs. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such
+ as <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
+ <literal>48;5;…</literal>. See <ulink
+ url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
+ Escape Code (Wikipedia)</ulink> for details. Assign an empty string to disable any coloring.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</refsect2>
<variablelist>
<varlistentry>
- <term><option>--load-credential=</option><replaceable>ID</replaceable>:<replaceable>PATH</replaceable></term>
- <term><option>--set-credential=</option><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term>
+ <term><option>--load-credential=<replaceable>ID</replaceable>:<replaceable>PATH</replaceable></option></term>
+ <term><option>--set-credential=<replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></option></term>
<listitem><para>Pass a credential to the container. These two options correspond to the
<varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See
<para>In order to embed binary data into the credential data for <option>--set-credential=</option>,
use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to
embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping
- once, hence this might require double escaping!.</para>
+ once, hence this might require double escaping!</para>
<para>The
<citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<refsect1>
<title>Examples</title>
- <example>
- <title>Download a
- <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 \
- 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>
- and opens a shell in it.</para>
- </example>
+ <xi:include href="importctl.xml" xpointer="example-import-tar" />
<example>
<title>Build and boot a minimal Fedora distribution in a container</title>
<member><citerefentry project='mankier'><refentrytitle>zypper</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-nsresourced.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs.html'>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff