system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-21 10:17:21 +00:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

Merge pull request #12868 from poettering/doc-243-fixes

Browse source 
various man page fixes
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2019-06-24 16:07:16 +02:00 committed by GitHub
parent 0d92a3088a e5134f00f8
commit c455677449
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 82 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
man/sd_bus_creds_get_pid.xml
View file

@ -325,12 +325,14 @@
<filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
</para>
<para><function>sd_bus_creds_get_exe()</function> will retrieve
the path to the program executable (as stored in the
<filename>/proc/<replaceable>pid</replaceable>/exe</filename>
link, but with the <literal> (deleted)</literal> suffix removed). Note
that kernel threads do not have an executable path, in which case
-ENXIO is returned.</para>
<para><function>sd_bus_creds_get_exe()</function> will retrieve the path to the program executable (as
stored in the <filename>/proc/<replaceable>pid</replaceable>/exe</filename> link, but with the <literal>
(deleted)</literal> suffix removed). Note that kernel threads do not have an executable path, in which
case -ENXIO is returned. Note that this property should not be used for more than explanatory
information, in particular it should not be used for security-relevant decisions. That's because the
executable might have been replaced or removed by the time the value can be processed. Moreover, the
kernel exports this information in an ambiguous way (i.e. a deleted executable cannot be safely
distinguished from one whose name suffix is <literal> (deleted)</literal>.</para>
<para><function>sd_bus_creds_get_cmdline()</function> will
retrieve an array of command line arguments (as stored in

103
man/systemd.exec.xml
View file

@ -254,14 +254,15 @@
part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by
these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus
gain access to these files or directories. If <varname>DynamicUser=</varname> is enabled,
<varname>RemoveIPC=</varname>, <varname>PrivateTmp=</varname> are implied. This ensures that the
lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime
of the service, and hence the lifetime of the dynamic user/group. Since <filename>/tmp</filename> and
<filename>/var/tmp</filename> are usually the only world-writable directories on a system this
ensures that a unit making use of dynamic user/group allocation cannot leave files around after unit
termination. Furthermore <varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname>
are implicitly enabled to ensure that processes invoked cannot take benefit or create SUID/SGID files
or directories. Moreover <varname>ProtectSystem=strict</varname> and
<varname>RemoveIPC=</varname> and <varname>PrivateTmp=</varname> are implied (and cannot be turned
off). This ensures that the lifetime of IPC objects and temporary files created by the executed
processes is bound to the runtime of the service, and hence the lifetime of the dynamic
user/group. Since <filename>/tmp/</filename> and <filename>/var/tmp/</filename> are usually the only
world-writable directories on a system this ensures that a unit making use of dynamic user/group
allocation cannot leave files around after unit termination. Furthermore
<varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname> are implicitly enabled
(and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID
files or directories. Moreover <varname>ProtectSystem=strict</varname> and
<varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to
arbitrary file system locations. In order to allow the service to write to certain directories, they
have to be whitelisted using <varname>ReadWritePaths=</varname>, but care must be taken so that
@ -1935,12 +1936,12 @@ SystemCallErrorNumber=EPERM</programlisting>
<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>file:<replaceable>path</replaceable></option>, <option>append:<replaceable>path</replaceable></option>,
<option>socket</option> or <option>fd:<replaceable>name</replaceable></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>kmsg</option>, <option>journal+console</option>,
<option>kmsg+console</option>, <option>file:<replaceable>path</replaceable></option>,
<option>append:<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>
@ -1951,23 +1952,20 @@ SystemCallErrorNumber=EPERM</programlisting>
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>
<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 kmsg (see below) is implicitly stored in the journal as well, the
specific option listed below is hence a superset of this one. (Also note that any external,
additional syslog daemons receive their log data from the journal, too, hence this is the option to
use when logging shall be processed with such a daemon.)</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>journal+console</option> and <option>kmsg+console</option> work in a similar way as the
two 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
@ -1996,13 +1994,14 @@ SystemCallErrorNumber=EPERM</programlisting>
<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
<filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section above). Also note
that in this case stdout (or stderr, see below) will be an <constant>AF_UNIX</constant> stream socket, and not
a pipe or FIFO that can be re-opened. This means when executing shell scripts the construct <command>echo
"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>If the standard output (or error output, see below) of a unit is connected to the journal or
the kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname>
on <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section
above). Also note that in this case stdout (or stderr, see below) will be an
<constant>AF_UNIX</constant> stream socket, and not a pipe or FIFO that can be re-opened. This means
when executing shell scripts the construct <command>echo "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
@ -2120,12 +2119,12 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
<varlistentry>
<term><varname>SyslogIdentifier=</varname></term>
<listitem><para>Sets the process name ("<command>syslog</command> tag") to prefix log lines sent to the logging
system or the kernel log buffer with. If not set, defaults to the process name of the executed process. This
option is only useful when <varname>StandardOutput=</varname> or <varname>StandardError=</varname> are set to
<option>journal</option>, <option>syslog</option> or <option>kmsg</option> (or to the same settings in
combination with <option>+console</option>) and only applies to log messages written to stdout or
stderr.</para></listitem>
<listitem><para>Sets the process name ("<command>syslog</command> tag") to prefix log lines sent to
the logging system or the kernel log buffer with. If not set, defaults to the process name of the
executed process. This option is only useful when <varname>StandardOutput=</varname> or
<varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to
the same settings in combination with <option>+console</option>) and only applies to log messages
written to stdout or stderr.</para></listitem>
</varlistentry>
<varlistentry>
@ -2136,12 +2135,13 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
<option>auth</option>, <option>syslog</option>, <option>lpr</option>, <option>news</option>,
<option>uucp</option>, <option>cron</option>, <option>authpriv</option>, <option>ftp</option>,
<option>local0</option>, <option>local1</option>, <option>local2</option>, <option>local3</option>,
<option>local4</option>, <option>local5</option>, <option>local6</option> or <option>local7</option>. See
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for details. This option is only useful when <varname>StandardOutput=</varname> or
<varname>StandardError=</varname> are set to <option>journal</option>, <option>syslog</option> or
<option>kmsg</option> (or to the same settings in combination with <option>+console</option>), and only applies
to log messages written to stdout or stderr. Defaults to <option>daemon</option>.</para></listitem>
<option>local4</option>, <option>local5</option>, <option>local6</option> or
<option>local7</option>. See <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
details. This option is only useful when <varname>StandardOutput=</varname> or
<varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to
the same settings in combination with <option>+console</option>), and only applies to log messages
written to stdout or stderr. Defaults to <option>daemon</option>.</para></listitem>
</varlistentry>
<varlistentry>
@ -2153,7 +2153,7 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
<option>debug</option>. See <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
details. This option is only useful when <varname>StandardOutput=</varname> or
<varname>StandardError=</varname> are set to <option>journal</option>, <option>syslog</option> or
<varname>StandardError=</varname> are set to <option>journal</option> or
<option>kmsg</option> (or to the same settings in combination with <option>+console</option>), and only applies
to log messages written to stdout or stderr. Note that individual lines output by executed processes may be
prefixed with a different log level which can be used to override the default log level specified here. The
@ -2166,12 +2166,13 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
<term><varname>SyslogLevelPrefix=</varname></term>
<listitem><para>Takes a boolean argument. If true and <varname>StandardOutput=</varname> or
<varname>StandardError=</varname> are set to <option>journal</option>, <option>syslog</option> or
<option>kmsg</option> (or to the same settings in combination with <option>+console</option>), log lines
written by the executed process that are prefixed with a log level will be processed with this log level set
but the prefix removed. If set to false, the interpretation of these prefixes is disabled and the logged lines
are passed on as-is. This only applies to log messages written to stdout or stderr. For details about this
prefixing see <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
<varname>StandardError=</varname> are set to <option>journal</option> or <option>kmsg</option> (or to
the same settings in combination with <option>+console</option>), log lines written by the executed
process that are prefixed with a log level will be processed with this log level set but the prefix
removed. If set to false, the interpretation of these prefixes is disabled and the logged lines are
passed on as-is. This only applies to log messages written to stdout or stderr. For details about
this prefixing see
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
Defaults to true.</para></listitem>
</varlistentry>

8
man/systemd.service.xml
View file

@ -945,11 +945,9 @@
inverse of the <varname>Sockets=</varname> setting of the
<filename>.service</filename> it refers to.</para>
<para>This option may appear more than once, in which case the
list of socket units is merged. If the empty string is
assigned to this option, the list of sockets is reset, and all
prior uses of this setting will have no
effect.</para></listitem>
<para>This option may appear more than once, in which case the list of socket units is merged. Note
that once set, clearing the list of sockets again (for example, by assigning the empty string to this
option) is not supported.</para></listitem>
</varlistentry>
<varlistentry>

32
man/systemd.xml
View file

@ -70,8 +70,13 @@
<varlistentry>
<term><option>--test</option></term>
<listitem><para>Determine startup sequence, dump it and exit.
This is an option useful for debugging only.</para></listitem>
<listitem><para>Determine the initial start-up transaction (i.e. the list of jobs enqueued at
start-up), dump it and exit. This option is useful for debugging only. Note that during regular
service manager start-up further units might be started than this operation shows, because hardware,
socket, bus or other kinds of activation might add additional jobs. Use <option>--system</option> to
request the initial transaction of the system service manager (this is also the implied default),
combine with <option>--user</option> to request the initial transaction of the per-user service
manager instead.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dump-configuration-items</option></term>
@ -94,23 +99,20 @@
not specified, defaults to
<filename>default.target</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--system</option></term>
<term><option>--user</option></term>
<listitem><para>For <option>--system</option>, tell systemd to
run a system instance, even if the process ID is not 1, i.e.
systemd is not run as init process. <option>--user</option>
does the opposite, running a user instance even if the process
ID is 1. Normally, it should not be necessary to pass these
options, as systemd automatically detects the mode it is
started in. These options are hence of little use except for
debugging. Note that it is not supported booting and
maintaining a full system with systemd running in
<option>--system</option> mode, but PID not 1. In practice,
passing <option>--system</option> explicitly is only useful in
conjunction with <option>--test</option>.</para></listitem>
<listitem><para>When used in conjunction with <option>--test</option>, selects whether to calculate
the initial transaction for the system instance or for a per-user instance. These options have no
effect when invoked without <option>--test</option>, as during regular
(i.e. non-<option>--test</option>) invocations the service manager will automatically detect whether
it shall operate in system or per-user mode, by checking whether the PID it is run as is 1 or
not. Note that it is not supported booting and maintaining a system with the service manager running
in <option>--system</option> mode but with a PID other than 1.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dump-core</option></term>
@ -232,8 +234,6 @@
<option>tty</option>,
<option>journal</option>,
<option>journal+console</option>,
<option>syslog</option>,
<option>syslog+console</option>,
<option>kmsg</option>,
<option>kmsg+console</option>. If the
argument is omitted

6
src/core/main.c
View file

@ -1157,13 +1157,13 @@ static int help(void) {
"Starts up and maintains the system or user services.\n\n"
" -h --help Show this help\n"
" --version Show version\n"
" --test Determine startup sequence, dump it and exit\n"
" --test Determine initial transaction, dump it and exit\n"
" --system In combination with --test: operate as system service manager\n"
" --user In combination with --test: operate as per-user service manager\n"
" --no-pager Do not pipe output into a pager\n"
" --dump-configuration-items Dump understood unit configuration items\n"
" --dump-bus-properties Dump exposed bus properties\n"
" --unit=UNIT Set default unit\n"
" --system Run a system instance, even if PID != 1\n"
" --user Run a user instance\n"
" --dump-core[=BOOL] Dump core on crash\n"
" --crash-vt=NR Change to specified VT on crash\n"
" --crash-reboot[=BOOL] Reboot on crash\n"