From fc8d038130cedf0f1488f906a3a82930b9673a4d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 27 Oct 2017 18:10:34 +0200 Subject: [PATCH] man: document all the new options we acquired --- man/systemd.exec.xml | 277 ++++++++++++++++++++++--------------------- 1 file changed, 141 insertions(+), 136 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 @@ StandardInput= - Controls where file descriptor 0 (STDIN) of - the executed processes is connected to. Takes one of - , - , - , - , - or - . + Controls where file descriptor 0 (STDIN) of the executed processes is connected to. Takes one + of , , , , + , , or + . - If is selected, standard input - will be connected to /dev/null, i.e. all - read attempts by the process will result in immediate - EOF. + If is selected, standard input will be connected to /dev/null, + i.e. all read attempts by the process will result in immediate EOF. - If is selected, standard input is - connected to a TTY (as configured by - TTYPath=, 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. + If is selected, standard input is connected to a TTY (as configured by + TTYPath=, 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. - is similar to - , but the executed process is forcefully - and immediately made the controlling process of the terminal, - potentially removing previous controlling processes from the - terminal. + is similar to , but the executed process is forcefully and + immediately made the controlling process of the terminal, potentially removing previous controlling processes + from the terminal. - is similar to - but if the terminal already has a - controlling process start-up of the executed process - fails. + is similar to , but if the terminal already has a + controlling process start-up of the executed process fails. - The option is only valid in - socket-activated services, and only when the socket - configuration file (see - systemd.socket5 - 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 - inetd8 + The 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 + StandardInputText=/StandardInputData= (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. + + The option may be used to connect a specific file + system object to standard input. An absolute path following the : character is expected, + which may refer to a regular file, a FIFO or special file. If an AF_UNIX 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. + + The option is valid in socket-activated services only, and requires the relevant + socket unit file (see + systemd.socket5 for details) + to have Accept=yes 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 inetd8 socket activation daemon. - The 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 : (e.g. fd:foobar). - If no name is specified, stdin is assumed - (i.e. fd is equivalent to fd:stdin). - At least one socket unit defining such name must be explicitly provided via the - Sockets= 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 FileDescriptorName= in - systemd.socket5 - for more details about named descriptors and ordering. + The 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 + : character (e.g. fd:foobar). If no name is specified, the name + stdin is implied (i.e. fd is equivalent to fd:stdin). + At least one socket unit defining the specified name must be provided via the Sockets= + 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 FileDescriptorName= in + systemd.socket5 for more + details about named file descriptors and their ordering. - This setting defaults to - . + This setting defaults to . StandardOutput= - Controls where file descriptor 1 (STDOUT) of - the executed processes is connected to. Takes one of - , - , - , - , - , - , - , - , - , - or - . + Controls where file descriptor 1 (STDOUT) of the executed processes is connected to. Takes one + of , , , , + , , , + , , + , or + . - duplicates the file descriptor - of standard input for standard output. + duplicates the file descriptor of standard input for standard output. - connects standard output to - /dev/null, i.e. everything written to it - will be lost. + connects standard output to /dev/null, i.e. everything written + to it will be lost. - connects standard output to a tty - (as configured via TTYPath=, 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. + connects standard output to a tty (as configured via TTYPath=, + 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. - connects standard output with - the journal which is accessible via - journalctl1. - 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. + connects standard output with the journal which is accessible via + journalctl1. 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. - connects standard output to the - syslog3 - 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 . + connects standard output to the syslog3 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 . - connects standard output with the - kernel log buffer which is accessible via + connects standard output with the kernel log buffer which is accessible via dmesg1, - 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 . + 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 . - , - and - work in a similar way as the - three options above but copy the output to the system console - as well. + , and work + in a similar way as the three options above but copy the output to the system console as well. - connects standard output to a - socket acquired via socket activation. The semantics are - similar to the same option of - StandardInput=. + The option may be used to connect a specific file + system object to standard output. The semantics are similar to the same option of + StandardInputText=, 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 AF_UNIX socket in the file system, as in that case only a + single stream connection is created for both input and output. - The 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 : (e.g. fd:foobar). - If no name is specified, stdout is assumed - (i.e. fd is equivalent to fd:stdout). - At least one socket unit defining such name must be explicitly provided via the - Sockets= 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 FileDescriptorName= in - systemd.socket5 - for more details about named descriptors and ordering. + connects standard output to a socket acquired via socket activation. The + semantics are similar to the same option of StandardInput=, see above. + + The 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 + : character (e.g. fd:foobar). If no name is + specified, the name stdout is implied (i.e. fd is equivalent to + fd:stdout). At least one socket unit defining the specified name must be provided via the + Sockets= 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 FileDescriptorName= + in systemd.socket5 for more + details about named descriptors and their ordering. 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 After= on @@ -630,32 +601,66 @@ "hello" > /dev/stderr for writing text to stderr will not work. To mitigate this use the construct echo "hello" >&2 instead, which is mostly equivalent and avoids this pitfall. - This setting defaults to the value set with - DefaultStandardOutput= in - systemd-system.conf5, - which defaults to . Note that setting - this parameter might result in additional dependencies to be - added to the unit (see above). + This setting defaults to the value set with DefaultStandardOutput= in + systemd-system.conf5, which + defaults to . Note that setting this parameter might result in additional dependencies + to be added to the unit (see above). StandardError= - Controls where file descriptor 2 (STDERR) of - the executed processes is connected to. The available options - are identical to those of StandardOutput=, - with some exceptions: if set to the - file descriptor used for standard output is duplicated for - standard error, while operates on the error - stream and will look by default for a descriptor named + Controls where file descriptor 2 (STDERR) of the executed processes is connected to. The + available options are identical to those of StandardOutput=, with some exceptions: if set to + the file descriptor used for standard output is duplicated for standard error, while + will use a default file descriptor name of stderr. - This setting defaults to the value set with - DefaultStandardError= in - systemd-system.conf5, - which defaults to . Note that setting - this parameter might result in additional dependencies to be - added to the unit (see above). + This setting defaults to the value set with DefaultStandardError= in + systemd-system.conf5, which + defaults to . Note that setting this parameter might result in additional dependencies + to be added to the unit (see above). + + + + StandardInputText= + StandardInputData= + + Configures arbitrary textual or binary data to pass via file descriptor 0 (STDIN) to the + executed processes. These settings have no effect unless StandardInput= is set to + . Use this option to embed process input data directly in the unit file. + + StandardInputText= accepts arbitrary textual data. C-style escapes for special + characters as well as the usual %-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 \n to the end or beginning of a line). + + StandardInputData= accepts arbitrary binary data, encoded in Base64. No escape sequences or specifiers are + resolved. Any whitespace in the encoded version is ignored during decoding. + + Note that StandardInputText= and StandardInputData= 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. + + 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 \ character (see + systemd.unit5 for + details). This is particularly useful for large data configured with these two options. Example: + + … +StandardInput=data +StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy4KSWNrIGtpZWtl \ + LCBzdGF1bmUsIHd1bmRyZSBtaXIsCnVmZiBlZW1hbCBqZWh0IHNlIHVmZiBkaWUgVMO8ci4KTmFu \ + dSwgZGVuayBpY2ssIGljayBkZW5rIG5hbnUhCkpldHogaXNzZSB1ZmYsIGVyc2NodCB3YXIgc2Ug \ + enUhCkljayBqZWhlIHJhdXMgdW5kIGJsaWNrZSDigJQKdW5kIHdlciBzdGVodCBkcmF1w59lbj8g \ + SWNrZSEK +… + +