Merge pull request #1165 from poettering/nspawn-files

various fixes to the core, logind, machined, nspawn

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