summaryrefslogtreecommitdiff
path: root/man/systemd.nspawn.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/systemd.nspawn.xml')
-rw-r--r--man/systemd.nspawn.xml454
1 files changed, 0 insertions, 454 deletions
diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml
deleted file mode 100644
index 3683412c14..0000000000
--- a/man/systemd.nspawn.xml
+++ /dev/null
@@ -1,454 +0,0 @@
-<?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 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>
-
- </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>Persistent settings files 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 for 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, which 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. This option may not be combined with
- <varname>ProcessTwo=yes</varname>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>ProcessTwo=</varname></term>
-
- <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
- PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch
- on the <command>systemd-nspawn</command> command line. This option may not be combined with
- <varname>Boot=yes</varname>.</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>WorkingDirectory=</varname></term>
-
- <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
- path in the container's file system namespace. This corresponds to the <option>--chdir=</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 project='man-pages'><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 capabilities. 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>KillSignal=</varname></term>
-
- <listitem><para>Specify the process signal to send to the
- container's PID 1 when nspawn itself receives SIGTERM, in
- order to trigger an orderly shutdown of the container.
- Defaults to SIGRTMIN+3 if <option>Boot=</option> is used
- (on systemd-compatible init systems SIGRTMIN+3 triggers an
- orderly shutdown). For a list of valid signals, see
- <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</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 128-bit 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>
-
- <varlistentry>
- <term><varname>PrivateUsers=</varname></term>
-
- <listitem><para>Configures support for usernamespacing. This is equivalent to the
- <option>--private-users=</option> command line switch, and takes the same options. 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, which 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 multiple 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>
-
- <varlistentry>
- <term><varname>PrivateUsersChown=</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>
- </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, which 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>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>
- </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>Zone=</varname></term>
-
- <listitem><para>Takes a network zone 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 an automatically managed bridge interface named after the passed argument, prefixed with
- <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</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>