diff options
Diffstat (limited to 'man/systemd.nspawn.xml')
| -rw-r--r-- | man/systemd.nspawn.xml | 463 |
1 files changed, 0 insertions, 463 deletions
diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml deleted file mode 100644 index b1344d6c10..0000000000 --- a/man/systemd.nspawn.xml +++ /dev/null @@ -1,463 +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>. This option is the default if the - <filename>systemd-nspawn@.service</filename> template unit file is used.</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). This option is the default if the <filename>systemd-nspawn@.service</filename> template unit file - is used.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>NotifyReady=</varname></term> - - <listitem><para>Configures support for notifications from the container's init process. - This is equivalent to use <option>--notify-ready=</option> command line switch, - and takes the same options. See <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details about the specific options supported.</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). This option is the default if the - <filename>systemd-nspawn@.service</filename> template unit file is used.</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> |