man: document all the new options we acquired
This commit is contained in:
Lennart Poettering
parent
99be45a46f
commit
fc8d038130
|
|
@ -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>
|
||||
<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>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>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-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><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>
|
||||
<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>
|
||||
<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>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>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>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>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>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
|
||||
<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>
|
||||
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>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>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>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>
|
||||
<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" > /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>
|
||||
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue