diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/systemd-nspawn.xml | 67 | ||||
| -rw-r--r-- | man/systemd.nspawn.xml | 383 | ||||
| -rw-r--r-- | man/systemd.unit.xml | 2 |
3 files changed, 444 insertions, 8 deletions
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 6165fe1357..b1d68b9ecd 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?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"> @@ -748,34 +748,86 @@ </varlistentry> <varlistentry> - <term><option>--volatile</option><replaceable>=MODE</replaceable></term> + <term><option>--volatile</option></term> + <term><option>--volatile=</option><replaceable>MODE</replaceable></term> <listitem><para>Boots the container in volatile mode. When no mode parameter is passed or when mode is specified as - <literal>yes</literal> full volatile mode is enabled. This + <option>yes</option> full volatile mode is enabled. This means the root directory is mounted as mostly unpopulated <literal>tmpfs</literal> instance, and <filename>/usr</filename> from the OS tree is mounted into it, read-only (the system thus starts up with read-only OS resources, but pristine state and configuration, any changes to the either are lost on shutdown). When the mode parameter - is specified as <literal>state</literal> the OS tree is + is specified as <option>state</option> the OS tree is mounted read-only, but <filename>/var</filename> is mounted as <literal>tmpfs</literal> instance into it (the system thus starts up with read-only OS resources and configuration, but pristine state, any changes to the latter are lost on shutdown). When the mode parameter is specified as - <literal>no</literal> (the default) the whole OS tree is made + <option>no</option> (the default) the whole OS tree is made available writable.</para> - <para>Note that setting this to <literal>yes</literal> or - <literal>state</literal> will only work correctly with + <para>Note that setting this to <option>yes</option> or + <option>state</option> will only work correctly with operating systems in the container that can boot up with only <filename>/usr</filename> mounted, and are able to populate <filename>/var</filename> automatically, as needed.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--settings=</option><replaceable>MODE</replaceable></term> + + <listitem><para>Controls whether + <command>systemd-nspawn</command> shall search for and use + additional per-container settings from + <filename>.nspawn</filename> files. Takes a boolean or the + special values <option>override</option> or + <option>trusted</option>.</para> + + <para>If enabled (the default) a settings file named after the + machine (as specified with the <option>--machine=</option> + setting, or derived from the directory or image file name) + with the suffix <filename>.nspawn</filename> is searched in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/systemd/nspawn/</filename>. If it is found + there, its settings are read and used. If it is not found + there it is subequently searched in the same directory as the + image file or in the immediate parent of the root directory of + the container. In this case, if the file is found its settings + will be also read and used, but potentially unsafe settings + are ignored. Note that in both these cases settings on the + command line take precendence over the corresponding settings + from loaded <filename>.nspawn</filename> files, if both are + specified. Unsafe settings are considered all settings that + elevate the container's privileges or grant access to + additional resources such as files or directories of the + host. For details about the format and contents of + <filename>.nspawn</filename> files consult + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If this option is set to <option>override</option> the + file is searched, read and used the same way, however the order of + precedence is reversed: settings read from the + <filename>.nspawn</filename> file will take precedence over + the corresponding command line options, if both are + specified.</para> + + <para>If this option is set to <option>trusted</option> the + file is searched, read and used the same way, but regardless + if found in <filename>/etc/systemd/nspawn/</filename>, + <filename>/run/systemd/nspawn/</filename> or next to the image + file or container root directory, all settings will take + effect, however command line arguments still take precedence + over corresponding settings.</para> + + <para>If disabled no <filename>.nspawn</filename> file is read + and no settings except the ones on the command line are in + effect.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -859,6 +911,7 @@ <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 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> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 407f6d32eb..ea58580bba 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -256,7 +256,7 @@ </refsect1> <refsect1> - <title>Unit Load Path</title> + <title>Unit File Load Path</title> <para>Unit files are loaded from a set of paths determined during compilation, described in the two tables below. Unit files found |