man: document all the new options we acquired

1 files changed, 154 insertions, 149 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index d043555860..190d3af317 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -482,145 +482,116 @@
 
       <varlistentry>
         <term><varname>StandardInput=</varname></term>
-        <listitem><para>Controls where file descriptor 0 (STDIN) of
-        the executed processes is connected to. Takes one of
-        <option>null</option>,
-        <option>tty</option>,
-        <option>tty-force</option>,
-        <option>tty-fail</option>,
-        <option>socket</option> or
-        <option>fd</option>.</para>
-
-        <para>If <option>null</option> is selected, standard input
-        will be connected to <filename>/dev/null</filename>, i.e. all
-        read attempts by the process will result in immediate
-        EOF.</para>
-
-        <para>If <option>tty</option> is selected, standard input is
-        connected to a TTY (as configured by
-        <varname>TTYPath=</varname>, see below) and the executed
-        process becomes the controlling process of the terminal. If
-        the terminal is already being controlled by another process,
-        the executed process waits until the current controlling
-        process releases the terminal.</para>
-
-        <para><option>tty-force</option> is similar to
-        <option>tty</option>, but the executed process is forcefully
-        and immediately made the controlling process of the terminal,
-        potentially removing previous controlling processes from the
-        terminal.</para>
-
-        <para><option>tty-fail</option> is similar to
-        <option>tty</option> but if the terminal already has a
-        controlling process start-up of the executed process
-        fails.</para>
-
-        <para>The <option>socket</option> option is only valid in
-        socket-activated services, and only when the socket
-        configuration file (see
-        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-        for details) specifies a single socket only. If this option is
-        set, standard input will be connected to the socket the
-        service was activated from, which is primarily useful for
-        compatibility with daemons designed for use with the
-        traditional
-        <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        <listitem><para>Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one
+        of <option>null</option>, <option>tty</option>, <option>tty-force</option>, <option>tty-fail</option>,
+        <option>data</option>, <option>file:<replaceable>path</replaceable></option>, <option>socket</option> or
+        <option>fd:<replaceable>name</replaceable></option>.</para>
+
+        <para>If <option>null</option> is selected, standard input will be connected to <filename>/dev/null</filename>,
+        i.e. all read attempts by the process will result in immediate EOF.</para>
+
+        <para>If <option>tty</option> is selected, standard input is connected to a TTY (as configured by
+        <varname>TTYPath=</varname>, see below) and the executed process becomes the controlling process of the
+        terminal. If the terminal is already being controlled by another process, the executed process waits until the
+        current controlling process releases the terminal.</para>
+
+        <para><option>tty-force</option> is similar to <option>tty</option>, but the executed process is forcefully and
+        immediately made the controlling process of the terminal, potentially removing previous controlling processes
+        from the terminal.</para>
+
+        <para><option>tty-fail</option> is similar to <option>tty</option>, but if the terminal already has a
+        controlling process start-up of the executed process fails.</para>
+
+        <para>The <option>data</option> option may be used to configure arbitrary textual or binary data to pass via
+        standard input to the executed process. The data to pass is configured via
+        <varname>StandardInputText=</varname>/<varname>StandardInputData=</varname> (see below). Note that the actual
+        file descriptor type passed (memory file, regular file, UNIX pipe, …) might depend on the kernel and available
+        privileges. In any case, the file descriptor is read-only, and when read returns the specified data
+        followed by EOF.</para>
+
+        <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file
+        system object to standard input. An absolute path following the <literal>:</literal> character is expected,
+        which may refer to a regular file, a FIFO or special file. If an <constant>AF_UNIX</constant> socket in the
+        file system is specified, a stream socket is connected to it. The latter is useful for connecting standard
+        input of processes to arbitrary system services.</para>
+
+        <para>The <option>socket</option> option is valid in socket-activated services only, and requires the relevant
+        socket unit file (see
+        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details)
+        to have <varname>Accept=yes</varname> set, or to specify a single socket only. If this option is set, standard
+        input will be connected to the socket the service was activated from, which is primarily useful for
+        compatibility with daemons designed for use with the traditional <citerefentry
+        project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> socket activation
         daemon.</para>
 
-        <para>The <option>fd</option> option connects
-        the input stream to a single file descriptor provided by a socket unit.
-        A custom named file descriptor can be specified as part of this option,
-        after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>).
-        If no name is specified, <literal>stdin</literal> is assumed
-        (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>).
-        At least one socket unit defining such name must be explicitly provided via the
-        <varname>Sockets=</varname> option, and file descriptor name may differ
-        from the name of its containing socket unit.
-        If multiple matches are found, the first one will be used.
-        See <varname>FileDescriptorName=</varname> in
-        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-        for more details about named descriptors and ordering.</para>
+        <para>The <option>fd:<replaceable>name</replaceable></option> option connects standard input to a specific,
+        named file descriptor provided by a socket unit.  The name may be specified as part of this option, following a
+        <literal>:</literal> character (e.g. <literal>fd:foobar</literal>).  If no name is specified, the name
+        <literal>stdin</literal> is implied (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>).
+        At least one socket unit defining the specified name must be provided via the <varname>Sockets=</varname>
+        option, and the file descriptor name may differ from the name of its containing socket unit.  If multiple
+        matches are found, the first one will be used.  See <varname>FileDescriptorName=</varname> in
+        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
+        details about named file descriptors and their ordering.</para>
 
-        <para>This setting defaults to
-        <option>null</option>.</para></listitem>
+        <para>This setting defaults to <option>null</option>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><varname>StandardOutput=</varname></term>
-        <listitem><para>Controls where file descriptor 1 (STDOUT) of
-        the executed processes is connected to. Takes one of
-        <option>inherit</option>,
-        <option>null</option>,
-        <option>tty</option>,
-        <option>journal</option>,
-        <option>syslog</option>,
-        <option>kmsg</option>,
-        <option>journal+console</option>,
-        <option>syslog+console</option>,
-        <option>kmsg+console</option>,
-        <option>socket</option> or
-        <option>fd</option>.</para>
-
-        <para><option>inherit</option> duplicates the file descriptor
-        of standard input for standard output.</para>
-
-        <para><option>null</option> connects standard output to
-        <filename>/dev/null</filename>, i.e. everything written to it
-        will be lost.</para>
-
-        <para><option>tty</option> connects standard output to a tty
-        (as configured via <varname>TTYPath=</varname>, see below). If
-        the TTY is used for output only, the executed process will not
-        become the controlling process of the terminal, and will not
-        fail or wait for other processes to release the
-        terminal.</para>
-
-        <para><option>journal</option> connects standard output with
-        the journal which is accessible via
-        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
-        Note that everything that is written to syslog or kmsg (see
-        below) is implicitly stored in the journal as well, the
-        specific two options listed below are hence supersets of this
-        one.</para>
-
-        <para><option>syslog</option> connects standard output to the
-        <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-        system syslog service, in addition to the journal. Note that
-        the journal daemon is usually configured to forward everything
-        it receives to syslog anyway, in which case this option is no
-        different from <option>journal</option>.</para>
+        <listitem><para>Controls where file descriptor 1 (STDOUT) of the executed processes is connected to. Takes one
+        of <option>inherit</option>, <option>null</option>, <option>tty</option>, <option>journal</option>,
+        <option>syslog</option>, <option>kmsg</option>, <option>journal+console</option>,
+        <option>syslog+console</option>, <option>kmsg+console</option>,
+        <option>file:<replaceable>path</replaceable></option>, <option>socket</option> or
+        <option>fd:<replaceable>name</replaceable></option>.</para>
+
+        <para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para>
+
+        <para><option>null</option> connects standard output to <filename>/dev/null</filename>, i.e. everything written
+        to it will be lost.</para>
+
+        <para><option>tty</option> connects standard output to a tty (as configured via <varname>TTYPath=</varname>,
+        see below). If the TTY is used for output only, the executed process will not become the controlling process of
+        the terminal, and will not fail or wait for other processes to release the terminal.</para>
 
-        <para><option>kmsg</option> connects standard output with the
-        kernel log buffer which is accessible via
+        <para><option>journal</option> connects standard output with the journal which is accessible via
+        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.  Note that
+        everything that is written to syslog or kmsg (see below) is implicitly stored in the journal as well, the
+        specific two options listed below are hence supersets of this one.</para>
+
+        <para><option>syslog</option> connects standard output to the <citerefentry
+        project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> system syslog
+        service, in addition to the journal. Note that the journal daemon is usually configured to forward everything
+        it receives to syslog anyway, in which case this option is no different from <option>journal</option>.</para>
+
+        <para><option>kmsg</option> connects standard output with the kernel log buffer which is accessible via
         <citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-        in addition to the journal. The journal daemon might be
-        configured to send all logs to kmsg anyway, in which case this
-        option is no different from <option>journal</option>.</para>
-
-        <para><option>journal+console</option>,
-        <option>syslog+console</option> and
-        <option>kmsg+console</option> work in a similar way as the
-        three options above but copy the output to the system console
-        as well.</para>
-
-        <para><option>socket</option> connects standard output to a
-        socket acquired via socket activation. The semantics are
-        similar to the same option of
-        <varname>StandardInput=</varname>.</para>
-
-        <para>The <option>fd</option> option connects
-        the output stream to a single file descriptor provided by a socket unit.
-        A custom named file descriptor can be specified as part of this option,
-        after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>).
-        If no name is specified, <literal>stdout</literal> is assumed
-        (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdout</literal>).
-        At least one socket unit defining such name must be explicitly provided via the
-        <varname>Sockets=</varname> option, and file descriptor name may differ
-        from the name of its containing socket unit.
-        If multiple matches are found, the first one will be used.
-        See <varname>FileDescriptorName=</varname> in
-        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-        for more details about named descriptors and ordering.</para>
+        in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which
+        case this option is no different from <option>journal</option>.</para>
+
+        <para><option>journal+console</option>, <option>syslog+console</option> and <option>kmsg+console</option> work
+        in a similar way as the three options above but copy the output to the system console as well.</para>
+
+        <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file
+        system object to standard output. The semantics are similar to the same option of
+        <varname>StandardInputText=</varname>, see above. If standard input and output are directed to the same file
+        path, it is opened only once, for reading as well as writing and duplicated. This is particular useful when the
+        specified path refers to an <constant>AF_UNIX</constant> socket in the file system, as in that case only a
+        single stream connection is created for both input and output.</para>
+
+        <para><option>socket</option> connects standard output to a socket acquired via socket activation. The
+        semantics are similar to the same option of <varname>StandardInput=</varname>, see above.</para>
+
+        <para>The <option>fd:<replaceable>name</replaceable></option> option connects standard output to a specific,
+        named file descriptor provided by a socket unit.  A name may be specified as part of this option, following a
+        <literal>:</literal> character (e.g. <literal>fd:foobar</literal>).  If no name is
+        specified, the name <literal>stdout</literal> is implied (i.e. <literal>fd</literal> is equivalent to
+        <literal>fd:stdout</literal>).  At least one socket unit defining the specified name must be provided via the
+        <varname>Sockets=</varname> option, and the file descriptor name may differ from the name of its containing socket
+        unit.  If multiple matches are found, the first one will be used.  See <varname>FileDescriptorName=</varname>
+        in <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
+        details about named descriptors and their ordering.</para>
 
         <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the
         kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on
@@ -630,32 +601,66 @@
         "hello" &gt; /dev/stderr</command> for writing text to stderr will not work. To mitigate this use the construct
         <command>echo "hello" >&amp;2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
 
-        <para>This setting defaults to the value set with
-        <varname>DefaultStandardOutput=</varname> in
-        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-        which defaults to <option>journal</option>. Note that setting
-        this parameter might result in additional dependencies to be
-        added to the unit (see above).</para>
+        <para>This setting defaults to the value set with <varname>DefaultStandardOutput=</varname> in
+        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which
+        defaults to <option>journal</option>. Note that setting this parameter might result in additional dependencies
+        to be added to the unit (see above).</para>
       </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><varname>StandardError=</varname></term>
-        <listitem><para>Controls where file descriptor 2 (STDERR) of
-        the executed processes is connected to. The available options
-        are identical to those of <varname>StandardOutput=</varname>,
-        with some exceptions: if set to <option>inherit</option> the
-        file descriptor used for standard output is duplicated for
-        standard error, while <option>fd</option> operates on the error
-        stream and will look by default for a descriptor named
+        <listitem><para>Controls where file descriptor 2 (STDERR) of the executed processes is connected to. The
+        available options are identical to those of <varname>StandardOutput=</varname>, with some exceptions: if set to
+        <option>inherit</option> the file descriptor used for standard output is duplicated for standard error, while
+        <option>fd:<replaceable>name</replaceable></option> will use a default file descriptor name of
         <literal>stderr</literal>.</para>
 
-        <para>This setting defaults to the value set with
-        <varname>DefaultStandardError=</varname> in
-        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-        which defaults to <option>inherit</option>. Note that setting
-        this parameter might result in additional dependencies to be
-        added to the unit (see above).</para></listitem>
+        <para>This setting defaults to the value set with <varname>DefaultStandardError=</varname> in
+        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which
+        defaults to <option>inherit</option>. Note that setting this parameter might result in additional dependencies
+        to be added to the unit (see above).</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>StandardInputText=</varname></term>
+        <term><varname>StandardInputData=</varname></term>
+
+        <listitem><para>Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to the
+        executed processes. These settings have no effect unless <varname>StandardInput=</varname> is set to
+        <option>data</option>. Use this option to embed process input data directly in the unit file.</para>
+
+        <para><varname>StandardInputText=</varname> accepts arbitrary textual data. C-style escapes for special
+        characters as well as the usual <literal>%</literal>-specifiers are resolved. Each time this setting is used
+        the the specified text is appended to the per-unit data buffer, followed by a newline character (thus every use
+        appends a new line to the end of the buffer). Note that leading and trailing whitespace of lines configured
+        with this option is removed. If an empty line is specified the buffer is cleared (hence, in order to insert an
+        empty line, add an additional <literal>\n</literal> to the end or beginning of a line).</para>
+
+        <para><varname>StandardInputData=</varname> accepts arbitrary binary data, encoded in <ulink
+        url="https://tools.ietf.org/html/rfc2045#section-6.8">Base64</ulink>. No escape sequences or specifiers are
+        resolved. Any whitespace in the encoded version is ignored during decoding.</para>
+
+        <para>Note that <varname>StandardInputText=</varname> and <varname>StandardInputData=</varname> operate on the
+        same data buffer, and may be mixed in order to configure both binary and textual data for the same input
+        stream. The textual or binary data is joined strictly in the order the settings appear in the unit
+        file. Assigning an empty string to either will reset the data buffer.</para>
+
+        <para>Please keep in mind that in order to maintain readability long unit file settings may be split into
+        multiple lines, by suffixing each line (except for the last) with a <literal>\</literal> character (see
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+        details). This is particularly useful for large data configured with these two options. Example:</para>
+
+        <programlisting>…
+StandardInput=data
+StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy4KSWNrIGtpZWtl \
+                  LCBzdGF1bmUsIHd1bmRyZSBtaXIsCnVmZiBlZW1hbCBqZWh0IHNlIHVmZiBkaWUgVMO8ci4KTmFu \
+                  dSwgZGVuayBpY2ssIGljayBkZW5rIG5hbnUhCkpldHogaXNzZSB1ZmYsIGVyc2NodCB3YXIgc2Ug \
+                  enUhCkljayBqZWhlIHJhdXMgdW5kIGJsaWNrZSDigJQKdW5kIHdlciBzdGVodCBkcmF1w59lbj8g \
+                  SWNrZSEK
+…
+        </programlisting>
+        </listitem>
       </varlistentry>
 
       <varlistentry>