man: document all the new options we acquired
This commit is contained in:
Lennart Poettering
parent
99be45a46f
commit
fc8d038130
|
|
@ -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" > /dev/stderr</command> for writing text to stderr will not work. To mitigate this use the construct
|
"hello" > /dev/stderr</command> for writing text to stderr will not work. To mitigate this use the construct
|
||||||
<command>echo "hello" >&2</command> instead, which is mostly equivalent and avoids this pitfall.</para>
|
<command>echo "hello" >&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>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue