<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
-<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="systemd.nspawn">
+<refentry id="systemd.nspawn" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd.nspawn</title>
<refsect1>
<title>Description</title>
- <para>An nspawn container settings file (suffix
- <filename>.nspawn</filename>) encodes additional runtime
- information about a local container, and is searched, read and
- used by
- <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- when starting a container. Files of this type are named after the
- containers they define settings for. They are optional, and only
- required for containers whose execution environment shall differ
- from the defaults. Files of this type mostly contain settings that
- may also be set on the <command>systemd-nspawn</command> command
- line, and make it easier to persistently attach specific settings
- to specific containers. The syntax of these files is inspired by
- <filename>.desktop</filename> files following the <ulink
- url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
- Desktop Entry Specification</ulink>, which in turn are inspired by
- Microsoft Windows <filename>.ini</filename> files.</para>
-
- <para>Boolean arguments used in these settings files can be
- written in various formats. For positive settings, the strings
- <option>1</option>, <option>yes</option>, <option>true</option>
- and <option>on</option> are equivalent. For negative settings, the
- strings <option>0</option>, <option>no</option>,
- <option>false</option> and <option>off</option> are
- equivalent.</para>
-
- <para>Empty lines and lines starting with # or ; are
- ignored. This may be used for commenting. Lines ending
- in a backslash are concatenated with the following
- line while reading and the backslash is replaced by a
- space character. This may be used to wrap long lines.</para>
-
+ <para>An nspawn container settings file (suffix <filename>.nspawn</filename>) contains runtime
+ configuration for a local container, and is used by
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ Files of this type are named after the containers they define settings for. They are optional, and only
+ required for containers whose execution environment shall differ from the defaults. Files of this type
+ mostly contain settings that may also be set on the <command>systemd-nspawn</command> command line, and
+ make it easier to persistently attach specific settings to specific containers. The syntax of these files
+ is inspired by <filename>.desktop</filename> files, similarly to other configuration files supported by
+ the systemd project. See
+ <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for an
+ overview.</para>
</refsect1>
<refsect1>
<title><filename>.nspawn</filename> File Discovery</title>
- <para>Files are searched by appending the
- <filename>.nspawn</filename> suffix to the machine name of the
- container, as specified with the <option>--machine=</option>
- switch of <command>systemd-nspawn</command>, or derived from the
- directory or image file name. This file is first searched in
- <filename>/etc/systemd/nspawn/</filename> and
- <filename>/run/systemd/nspawn/</filename>. If found in these
- directories, its settings are read and all of them take full effect
- (but are possibly overridden by corresponding command line
- arguments). If not found, the file will then be searched next to
- the image file or in the immediate parent of the root directory of
- the container. If the file is found there, only a subset of the
- settings will take effect however. All settings that possibly
- elevate privileges or grant additional access to resources of the
- host (such as files or directories) are ignored. To which options
- this applies is documented below.</para>
+ <para>Files are searched for by appending the <filename>.nspawn</filename> suffix to the machine name of
+ the container, as specified with the <option>--machine=</option> switch of
+ <command>systemd-nspawn</command>, or derived from the directory or image file name. This file is first
+ searched for in <filename>/etc/systemd/nspawn/</filename> and
+ <filename>/run/systemd/nspawn/</filename>. If found there, the settings are read and all of them take
+ full effect (but may still be overridden by corresponding command line arguments). Otherwise, the file
+ will then be searched for next to the image file or in the immediate parent of the root directory of the
+ container. If the file is found there, only a subset of the settings will take effect however. All
+ settings that possibly elevate privileges or grant additional access to resources of the host (such as
+ files or directories) are ignored. To which options this applies is documented below.</para>
<para>Persistent settings files created and maintained by the
administrator (and thus trusted) should be placed in
<refsect1>
<title>[Exec] Section Options</title>
- <para>Settings files may include an <literal>[Exec]</literal>
+ <para>Settings files may include an [Exec]
section, which carries various execution parameters:</para>
<variablelist class='nspawn-directives'>
<filename>/etc/systemd/nspawn/</filename> and
<filename>/run/system/nspawn/</filename> (see above). On the
other hand, <varname>DropCapability=</varname> takes effect in
- all cases.</para></listitem>
+ all cases. If the special value <literal>all</literal> is passed, all
+ capabilities are retained (or dropped).</para>
+ <para>These settings change the bounding set of capabilities which
+ also limits the ambient capabilities as given with the
+ <varname>AmbientCapability=</varname>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>AmbientCapability=</varname></term>
+ <listitem><para>Takes a space-separated list of Linux process
+ capabilities (see
+ <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details). The <varname>AmbientCapability=</varname> setting
+ specifies capabilities which will be passed to the started program
+ in the inheritable and ambient capability sets. This will grant
+ these capabilities to this process. This setting correspond to
+ the <option>--ambient-capability=</option> command line switch.
+ </para>
+
+ <para>The value <literal>all</literal> is not supported for this
+ setting.</para>
+
+ <para>The setting of <varname>AmbientCapability=</varname> must
+ be covered by the bounding set settings which were established by
+ <varname>Capability=</varname> and <varname>DropCapability=</varname>.
+ </para>
+
+ <para>Note that <varname>AmbientCapability=</varname> is a privileged
+ setting (see above).</para></listitem>
</varlistentry>
<varlistentry>
details.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>SuppressSync=</varname></term>
+
+ <listitem><para>Configures whether to suppress disk synchronization for the container payload. This
+ is equivalent to the <option>--suppress-sync=</option> command line switch, and takes the same
+ parameter. See
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for details.</para></listitem>
+ </varlistentry>
+
</variablelist>
</refsect1>
<refsect1>
<title>[Files] Section Options</title>
- <para>Settings files may include a <literal>[Files]</literal>
+ <para>Settings files may include a [Files]
section, which carries various parameters configuring the file
system of the container:</para>
is privileged (see above).</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>BindUser=</varname></term>
+
+ <listitem><para>Binds a user from the host into the container. This option is equivalent to the
+ command line switch <option>--bind-user=</option>, see
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for details about the specific options supported. This setting is privileged (see
+ above).</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>TemporaryFileSystem=</varname></term>
<varlistentry>
<term><varname>Inaccessible=</varname></term>
- <listitem><para>Masks the specified file or directly in the container, by over-mounting it with an empty file
+ <listitem><para>Masks the specified file or directory in the container, by over-mounting it with an empty file
node of the same type with the most restrictive access mode. Takes a file system path as argument. This option
may be used multiple times to mask multiple files or directories. This option is equivalent to the command line
switch <option>--inaccessible=</option>, see
</varlistentry>
<varlistentry>
- <term><varname>PrivateUsersChown=</varname></term>
+ <term><varname>PrivateUsersOwnership=</varname></term>
- <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be
- adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the
- <option>--private-users-chown</option> command line switch. This option is privileged (see
- above). </para></listitem>
+ <listitem><para>Configures whether the ownership of the files and directories in the container tree
+ shall be adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is
+ equivalent to the <option>--private-users-ownership=</option> command line switch. This option is
+ privileged (see above).</para></listitem>
</varlistentry>
</variablelist>
<refsect1>
<title>[Network] Section Options</title>
- <para>Settings files may include a <literal>[Network]</literal>
+ <para>Settings files may include a [Network]
section, which carries various parameters configuring the network
connectivity of the container:</para>
<varlistentry>
<term><varname>VirtualEthernetExtra=</varname></term>
- <listitem><para>Takes a colon-separated pair of interface
- names. Configures an additional virtual Ethernet connection
- (<literal>veth</literal>) between host and the container. The
- first specified name is the interface name on the host, the
- second the interface name in the container. The latter may be
- omitted in which case it is set to the same name as the host
- side interface. This setting implies
- <varname>Private=yes</varname>. This setting corresponds to
- the <option>--network-veth-extra=</option> command line
- switch, and maybe be used multiple times. It is independent of
- <varname>VirtualEthernet=</varname>. This option is privileged
- (see above).</para></listitem>
+ <listitem><para>Takes a colon-separated pair of interface names. Configures an additional virtual
+ Ethernet connection (<literal>veth</literal>) between host and the container. The first specified
+ name is the interface name on the host, the second the interface name in the container. The latter
+ may be omitted in which case it is set to the same name as the host side interface. This setting
+ implies <varname>Private=yes</varname>. This setting corresponds to the
+ <option>--network-veth-extra=</option> command line switch, and may be used multiple times. It is
+ independent of <varname>VirtualEthernet=</varname>. Note that this option is unrelated to the
+ <varname>Bridge=</varname> setting below, and thus any connections created this way are not
+ automatically added to any bridge device on the host side. This option is privileged (see
+ above).</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Interface=</varname></term>
- <listitem><para>Takes a space-separated list of interfaces to
- add to the container. This option corresponds to the
+ <listitem><para>Takes a space-separated list of interfaces to add to the container.
+ The interface object is defined either by a single interface name, referencing the name on the host,
+ or a colon-separated pair of interfaces, in which case the first one references the name on the host,
+ and the second one the name in the container.
+ This option corresponds to the
<option>--network-interface=</option> command line switch and
implies <varname>Private=yes</varname>. This option is
privileged (see above).</para></listitem>
<listitem><para>Takes a space-separated list of interfaces to
add MACLVAN or IPVLAN interfaces to, which are then added to
- the container. These options correspond to the
+ the container. The interface object is defined either by a single interface name, referencing the name
+ on the host, or a colon-separated pair of interfaces, in which case the first one references the name
+ on the host, and the second one the name in the container. These options correspond to the
<option>--network-macvlan=</option> and
<option>--network-ipvlan=</option> command line switches and
imply <varname>Private=yes</varname>. These options are
projects / thirdparty / systemd.git / blobdiff