summaryrefslogtreecommitdiff
path: root/man/systemd.nspawn.xml
diff options
context:
space:
mode:
authorTom Gundersen <teg@jklm.no>2015-09-07 02:59:08 +0200
committerTom Gundersen <teg@jklm.no>2015-09-07 02:59:08 +0200
commit6167a91c745e5406164ef57e27212ba572d9a0dc (patch)
tree35af349cc76d850d1593163d8dabfd4c59dfe267 /man/systemd.nspawn.xml
parent2009bcfd23400bacd50848ac3e72cd5f6fbe53db (diff)
parent08acb521f30d692f13056daa23fb1323528249ff (diff)
Merge pull request #1165 from poettering/nspawn-files
various fixes to the core, logind, machined, nspawn
Diffstat (limited to 'man/systemd.nspawn.xml')
-rw-r--r--man/systemd.nspawn.xml383
1 files changed, 383 insertions, 0 deletions
diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml
new file mode 100644
index 0000000000..ac0b911373
--- /dev/null
+++ b/man/systemd.nspawn.xml
@@ -0,0 +1,383 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "custom-entities.ent" >
+%entities;
+]>
+
+<!--
+ This file is part of systemd.
+
+ Copyright 2015 Lennart Poettering
+
+ systemd is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
+ (at your option) any later version.
+
+ systemd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License
+ along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="systemd.nspawn">
+
+ <refentryinfo>
+ <title>systemd.nspawn</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd.nspawn</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd.nspawn</refname>
+ <refpurpose>Container settings</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para>
+ <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para>
+ <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para>
+ </refsynopsisdiv>
+
+ <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 are in turn 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>
+
+ </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 overriden 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>Persistent settings file created and maintained by the
+ administrator (and thus trusted) should be placed in
+ <filename>/etc/systemd/nspawn/</filename>, while automatically
+ downloaded (and thus potentially untrusted) settings files are
+ placed in <filename>/var/lib/machines/</filename> instead (next to
+ the container images), where their security impact is limited. In
+ order to add privileged settings to <filename>.nspawn</filename>
+ files acquired from the image vendor it is recommended to copy the
+ settings files into <filename>/etc/systemd/nspawn/</filename> and
+ edit them there, so that the privileged options become
+ available. The precise algorithm how the files are searched and
+ interpreted may be configured with
+ <command>systemd-nspawn</command>'s <option>--settings=</option>
+ switch, see
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for details.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>[Exec] Section Options</title>
+
+ <para>Settings files may include an <literal>[Exec]</literal>
+ section, which carries various execution parameters:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>Boot=</varname></term>
+
+ <listitem><para>Takes a boolean argument, defaults to off. If
+ enabled <command>systemd-nspawn</command> will automatically
+ search for an <filename>init</filename> executable and invoke
+ it. In this case the 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. </para></listitem>
+ </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>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Environment=</varname></term>
+
+ <listitem><para>Takes an environment variable assignment
+ consisting of key and value, separated by
+ <literal>=</literal>. Sets an environment variable for the
+ main process invoked in the container. This setting may be
+ used multiple times to set multiple environment variables. It
+ corresponds to the <option>--setenv=</option> command line
+ switch.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>User=</varname></term>
+
+ <listitem><para>Takes a UNIX user name. Specifies the user
+ name to invoke the main process of the container as. This user
+ must be known in the container's user database. This
+ corresponds to the <option>--user=</option> command line
+ switch.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Capability=</varname></term>
+ <term><varname>DropCapability=</varname></term>
+
+ <listitem><para>Takes a space separated list of Linux process
+ capabilities (see
+ <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details). The <varname>Capability=</varname> setting
+ specifies additional capabilities to pass on top of the
+ default set of capabilites. The
+ <varname>DropCapability=</varname> setting specifies
+ capabilities to drop from the default set. These settings
+ correspond to the <option>--capability=</option> and
+ <option>--drop-capability=</option> command line
+ switches. Note that <varname>Capability=</varname> is a
+ privileged setting, and only takes effect in
+ <filename>.nspawn</filename> files in
+ <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>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Personality=</varname></term>
+
+ <listitem><para>Configures the kernel personality for the
+ container. This is equivalent to the
+ <option>--personality=</option> switch.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>MachineID=</varname></term>
+
+ <listitem><para>Configures the 128bit machine ID (UUID) to pass to
+ the container. This is equivalent to the
+ <option>--uuid=</option> command line switch. This option is
+ privileged (see above). </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>[Files] Section Options</title>
+
+ <para>Settings files may include a <literal>[Files]</literal>
+ section, which carries various parameters configuring the file
+ system of the container:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>ReadOnly=</varname></term>
+
+ <listitem><para>Takes a boolean argument, defaults to off. If
+ specified the container will be run with a read-only file
+ system. This setting corresponds to the
+ <option>--read-only</option> command line
+ switch.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Volatile=</varname></term>
+
+ <listitem><para>Takes a boolean argument, or the special value
+ <literal>state</literal>. This configures whether to run the
+ container with volatile state and/or configuration. This
+ option is equivalent to <option>--volatile=</option>, see
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for details about the specific options
+ supported.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Bind=</varname></term>
+ <term><varname>BindReadOnly=</varname></term>
+
+ <listitem><para>Adds a bind mount from the host into the
+ container. Takes a single path, a pair of two paths separated
+ by a colon, or a triplet of two paths plus an option string
+ separated by colons. This option may be used multiple times to
+ configure multiple bind mounts. This option is equivalent to
+ the command line switches <option>--bind=</option> and
+ <option>--bind-ro=</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>
+
+ <listitem><para>Adds a <literal>tmpfs</literal> mount to the
+ container. Takes a path or a pair of path and option string,
+ separated by a colon. This option may be used mutiple times to
+ configure multiple <literal>tmpfs</literal> mounts. This
+ option is equivalent to the command line switch
+ <option>--tmpfs=</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>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>[Network] Section Options</title>
+
+ <para>Settings files may include a <literal>[Network]</literal>
+ section, which carries various parameters configuring the network
+ connectivity of the container:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>Private=</varname></term>
+
+ <listitem><para>Takes a boolean argument, defaults to off. If
+ enabled the container will run in its own network namespace
+ and not share network interfaces and configuration with the
+ host. This setting corresponds to the
+ <option>--private-network</option> command line
+ switch.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>VirtualEthernet=</varname></term>
+
+ <listitem><para>Takes a boolean argument. Configures whether
+ to create a virtual ethernet connection
+ (<literal>veth</literal>) between host and the container. This
+ setting implies <varname>Private=yes</varname>. This setting
+ corresponds to the <option>--network-veth</option> command
+ line switch. 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
+ <option>--network-interface=</option> command line switch and
+ implies <varname>Private=yes</varname>. This option is
+ privileged (see above).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>MACVLAN=</varname></term>
+ <term><varname>IPVLAN=</varname></term>
+
+ <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
+ <option>--network-macvlan=</option> and
+ <option>--network-ipvlan=</option> command line switches and
+ imply <varname>Private=yes</varname>. These options are
+ privileged (see above).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Bridge=</varname></term>
+
+ <listitem><para>Takes an interface name. This setting implies
+ <varname>VirtualEthernet=yes</varname> and
+ <varname>Private=yes</varname> and has the effect that the
+ host side of the created virtual Ethernet link is connected to
+ the specified bridge interface. This option corresponds to the
+ <option>--network-bridge=</option> command line switch. This
+ option is privileged (see above).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Port=</varname></term>
+
+ <listitem><para>Exposes a TCP or UDP port of the container on
+ the host. This option corresponds to the
+ <option>--port=</option> command line switch, see
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for the precise syntax of the argument this option takes. This
+ option is privileged (see above).</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>