<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.nspawn">
<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 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'>
specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the
<filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the
<command>systemd-nspawn</command> command line. This option may not be combined with
- <varname>ProcessTwo=yes</varname>. This option is the default if the
- <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem>
+ <varname>ProcessTwo=yes</varname>. This option is specified by default in the
+ <filename>systemd-nspawn@.service</filename> template unit.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>Parameters=</varname></term>
- <listitem><para>Takes a space-separated list of
- arguments. This is either a command line, beginning with the
- binary name to execute, or – if <varname>Boot=</varname> is
- enabled – the list of arguments to pass to the init
- process. This setting corresponds to the command line
- parameters passed on the <command>systemd-nspawn</command>
- command line.</para></listitem>
+ <listitem><para>Takes a whitespace-separated list of arguments. Single (<literal>'</literal>) and
+ double (<literal>"</literal>) quotes may be used around arguments with whitespace. This is either a
+ command line, beginning with the binary name to execute, or – if <varname>Boot=</varname> is enabled
+ – the list of arguments to pass to the init process. This setting corresponds to the command line
+ parameters passed on the <command>systemd-nspawn</command> command line.</para>
+
+ <para>Note: <option>Boot=no</option>, <option>Parameters=a b "c c"</option> is the same as
+ <command>systemd-nspawn a b "c c"</command>, and <option>Boot=yes</option>, <option>Parameters=b 'c c'</option>
+ is the same as <command>systemd-nspawn --boot b 'c c'</command>.</para></listitem>
</varlistentry>
<varlistentry>
<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></listitem>
</varlistentry>
<varlistentry>
<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>Inaccessible=</varname></term>
+
+ <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
+ <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>Overlay=</varname></term>
<term><varname>OverlayReadOnly=</varname></term>
<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 maybe 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>
projects / thirdparty / systemd.git / blobdiff