1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-24 21:34:08 +03:00

man: document all the new options we acquired

This commit is contained in:
Lennart Poettering 2017-10-27 18:10:34 +02:00
parent 99be45a46f
commit fc8d038130

View File

@ -482,145 +482,116 @@
<varlistentry> <varlistentry>
<term><varname>StandardInput=</varname></term> <term><varname>StandardInput=</varname></term>
<listitem><para>Controls where file descriptor 0 (STDIN) of <listitem><para>Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one
the executed processes is connected to. Takes one of of <option>null</option>, <option>tty</option>, <option>tty-force</option>, <option>tty-fail</option>,
<option>null</option>, <option>data</option>, <option>file:<replaceable>path</replaceable></option>, <option>socket</option> or
<option>tty</option>, <option>fd:<replaceable>name</replaceable></option>.</para>
<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 <para>If <option>null</option> is selected, standard input will be connected to <filename>/dev/null</filename>,
will be connected to <filename>/dev/null</filename>, i.e. all i.e. all read attempts by the process will result in immediate EOF.</para>
read attempts by the process will result in immediate
EOF.</para>
<para>If <option>tty</option> is selected, standard input is <para>If <option>tty</option> is selected, standard input is connected to a TTY (as configured by
connected to a TTY (as configured by <varname>TTYPath=</varname>, see below) and the executed process becomes the controlling process of the
<varname>TTYPath=</varname>, see below) and the executed terminal. If the terminal is already being controlled by another process, the executed process waits until the
process becomes the controlling process of the terminal. If current controlling process releases the terminal.</para>
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 <para><option>tty-force</option> is similar to <option>tty</option>, but the executed process is forcefully and
<option>tty</option>, but the executed process is forcefully immediately made the controlling process of the terminal, potentially removing previous controlling processes
and immediately made the controlling process of the terminal, from the terminal.</para>
potentially removing previous controlling processes from the
terminal.</para>
<para><option>tty-fail</option> is similar to <para><option>tty-fail</option> is similar to <option>tty</option>, but if the terminal already has a
<option>tty</option> but if the terminal already has a controlling process start-up of the executed process fails.</para>
controlling process start-up of the executed process
fails.</para>
<para>The <option>socket</option> option is only valid in <para>The <option>data</option> option may be used to configure arbitrary textual or binary data to pass via
socket-activated services, and only when the socket standard input to the executed process. The data to pass is configured via
configuration file (see <varname>StandardInputText=</varname>/<varname>StandardInputData=</varname> (see below). Note that the actual
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> file descriptor type passed (memory file, regular file, UNIX pipe, …) might depend on the kernel and available
for details) specifies a single socket only. If this option is privileges. In any case, the file descriptor is read-only, and when read returns the specified data
set, standard input will be connected to the socket the followed by EOF.</para>
service was activated from, which is primarily useful for
compatibility with daemons designed for use with the <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file
traditional system object to standard input. An absolute path following the <literal>:</literal> character is expected,
<citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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> daemon.</para>
<para>The <option>fd</option> option connects <para>The <option>fd:<replaceable>name</replaceable></option> option connects standard input to a specific,
the input stream to a single file descriptor provided by a socket unit. named file descriptor provided by a socket unit. The name may be specified as part of this option, following a
A custom named file descriptor can be specified as part of this option, <literal>:</literal> character (e.g. <literal>fd:foobar</literal>). If no name is specified, the name
after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>). <literal>stdin</literal> is implied (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>).
If no name is specified, <literal>stdin</literal> is assumed At least one socket unit defining the specified name must be provided via the <varname>Sockets=</varname>
(i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>). option, and the file descriptor name may differ from the name of its containing socket unit. If multiple
At least one socket unit defining such name must be explicitly provided via the matches are found, the first one will be used. See <varname>FileDescriptorName=</varname> in
<varname>Sockets=</varname> option, and file descriptor name may differ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
from the name of its containing socket unit. details about named file descriptors and their ordering.</para>
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>This setting defaults to <para>This setting defaults to <option>null</option>.</para></listitem>
<option>null</option>.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>StandardOutput=</varname></term> <term><varname>StandardOutput=</varname></term>
<listitem><para>Controls where file descriptor 1 (STDOUT) of <listitem><para>Controls where file descriptor 1 (STDOUT) of the executed processes is connected to. Takes one
the executed processes is connected to. Takes one of of <option>inherit</option>, <option>null</option>, <option>tty</option>, <option>journal</option>,
<option>inherit</option>, <option>syslog</option>, <option>kmsg</option>, <option>journal+console</option>,
<option>null</option>, <option>syslog+console</option>, <option>kmsg+console</option>,
<option>tty</option>, <option>file:<replaceable>path</replaceable></option>, <option>socket</option> or
<option>journal</option>, <option>fd:<replaceable>name</replaceable></option>.</para>
<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 <para><option>inherit</option> duplicates the file descriptor of standard input for standard output.</para>
of standard input for standard output.</para>
<para><option>null</option> connects standard output to <para><option>null</option> connects standard output to <filename>/dev/null</filename>, i.e. everything written
<filename>/dev/null</filename>, i.e. everything written to it to it will be lost.</para>
will be lost.</para>
<para><option>tty</option> connects standard output to a tty <para><option>tty</option> connects standard output to a tty (as configured via <varname>TTYPath=</varname>,
(as configured via <varname>TTYPath=</varname>, see below). If see below). If the TTY is used for output only, the executed process will not become the controlling process of
the TTY is used for output only, the executed process will not the terminal, and will not fail or wait for other processes to release the terminal.</para>
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 <para><option>journal</option> connects standard output with the journal which is accessible via
the journal which is accessible via <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note that
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. everything that is written to syslog or kmsg (see below) is implicitly stored in the journal as well, the
Note that everything that is written to syslog or kmsg (see specific two options listed below are hence supersets of this one.</para>
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 <para><option>syslog</option> connects standard output to the <citerefentry
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> system syslog
system syslog service, in addition to the journal. Note that service, in addition to the journal. Note that the journal daemon is usually configured to forward everything
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>
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 <para><option>kmsg</option> connects standard output with the kernel log buffer which is accessible via
kernel log buffer which is accessible via
<citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
in addition to the journal. The journal daemon might be in addition to the journal. The journal daemon might be configured to send all logs to kmsg anyway, in which
configured to send all logs to kmsg anyway, in which case this case this option is no different from <option>journal</option>.</para>
option is no different from <option>journal</option>.</para>
<para><option>journal+console</option>, <para><option>journal+console</option>, <option>syslog+console</option> and <option>kmsg+console</option> work
<option>syslog+console</option> and in a similar way as the three options above but copy the output to the system console as well.</para>
<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 <para>The <option>file:<replaceable>path</replaceable></option> option may be used to connect a specific file
socket acquired via socket activation. The semantics are system object to standard output. The semantics are similar to the same option of
similar to the same option of <varname>StandardInputText=</varname>, see above. If standard input and output are directed to the same file
<varname>StandardInput=</varname>.</para> 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>The <option>fd</option> option connects <para><option>socket</option> connects standard output to a socket acquired via socket activation. The
the output stream to a single file descriptor provided by a socket unit. semantics are similar to the same option of <varname>StandardInput=</varname>, see above.</para>
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>). <para>The <option>fd:<replaceable>name</replaceable></option> option connects standard output to a specific,
If no name is specified, <literal>stdout</literal> is assumed named file descriptor provided by a socket unit. A name may be specified as part of this option, following a
(i.e. <literal>fd</literal> is equivalent to <literal>fd:stdout</literal>). <literal>:</literal> character (e.g. <literal>fd:foobar</literal>). If no name is
At least one socket unit defining such name must be explicitly provided via the specified, the name <literal>stdout</literal> is implied (i.e. <literal>fd</literal> is equivalent to
<varname>Sockets=</varname> option, and file descriptor name may differ <literal>fd:stdout</literal>). At least one socket unit defining the specified name must be provided via the
from the name of its containing socket unit. <varname>Sockets=</varname> option, and the file descriptor name may differ from the name of its containing socket
If multiple matches are found, the first one will be used. unit. If multiple matches are found, the first one will be used. See <varname>FileDescriptorName=</varname>
See <varname>FileDescriptorName=</varname> in in <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> details about named descriptors and their ordering.</para>
for more details about named descriptors and ordering.</para>
<para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the <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 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 "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> <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 <para>This setting defaults to the value set with <varname>DefaultStandardOutput=</varname> in
<varname>DefaultStandardOutput=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, defaults to <option>journal</option>. Note that setting this parameter might result in additional dependencies
which defaults to <option>journal</option>. Note that setting to be added to the unit (see above).</para>
this parameter might result in additional dependencies to be
added to the unit (see above).</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><varname>StandardError=</varname></term> <term><varname>StandardError=</varname></term>
<listitem><para>Controls where file descriptor 2 (STDERR) of <listitem><para>Controls where file descriptor 2 (STDERR) of the executed processes is connected to. The
the executed processes is connected to. The available options available options are identical to those of <varname>StandardOutput=</varname>, with some exceptions: if set to
are identical to those of <varname>StandardOutput=</varname>, <option>inherit</option> the file descriptor used for standard output is duplicated for standard error, while
with some exceptions: if set to <option>inherit</option> the <option>fd:<replaceable>name</replaceable></option> will use a default file descriptor name of
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
<literal>stderr</literal>.</para> <literal>stderr</literal>.</para>
<para>This setting defaults to the value set with <para>This setting defaults to the value set with <varname>DefaultStandardError=</varname> in
<varname>DefaultStandardError=</varname> in <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, which
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, defaults to <option>inherit</option>. Note that setting this parameter might result in additional dependencies
which defaults to <option>inherit</option>. Note that setting to be added to the unit (see above).</para></listitem>
this parameter might result in additional dependencies to be </varlistentry>
added to the unit (see above).</para></listitem>
<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>
<varlistentry> <varlistentry>