shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-03-19 22:50:17 +03:00
Code

Merge pull request #18827 from keszybz/a-bunch-of-man-page-updates

Browse Source 
A bunch of man page updates
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2021-03-01 15:14:40 +01:00 committed by GitHub
commit cd18afec16
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 771 additions and 365 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
TODO
View File

@ -1272,6 +1272,7 @@ Features:
- creating new directories/subvolumes/fifos/device nodes
should not follow symlinks. None of the other adjustment or creation
calls follow symlinks.
- add --test mode
* make sure systemd-ask-password-wall does not shutdown systemd-ask-password-console too early

74
man/less-variables.xml → man/common-variables.xml
View File

@ -7,6 +7,80 @@
<title>Environment</title>
<variablelist class='environment-variables'>
<varlistentry id='log-level'>
<term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
<listitem><para id='log-level-body'>The maximum log level of emitted messages (messages with a higher
log level, i.e. less important ones, will be suppressed). Either one of (in order of decreasing
importance) <constant>emerg</constant>, <constant>alert</constant>, <constant>crit</constant>,
<constant>err</constant>, <constant>warning</constant>, <constant>notice</constant>,
<constant>info</constant>, <constant>debug</constant>, or an integer in the range 0…7. See
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for more information.</para>
</listitem>
</varlistentry>
<varlistentry id='log-color'>
<term><varname>$SYSTEMD_LOG_COLOR</varname></term>
<listitem><para id='log-color-body'>A boolean. If true, messages written to the tty will be colored
according to priority.</para>
<para>This setting is only useful when messages are written directly to the terminal, because
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
other tools that display logs will color messages based on the log level on their own.</para>
</listitem>
</varlistentry>
<varlistentry id='log-time'>
<term><varname>$SYSTEMD_LOG_TIME</varname></term>
<listitem><para id='log-time-body'>A boolean. If true, log messages will be prefixed with a
timestamp.</para>
<para>This setting is only useful when messages are written directly to the terminal or a file, because
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
other tools that display logs will attach timestamps based on the entry metadata on their own.</para>
</listitem>
</varlistentry>
<varlistentry id='log-location'>
<term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
<listitem><para id='log-location-body'>A boolean. If true, messages will be prefixed with a filename
and line number in the source code where the message originates.</para>
<para>Note that the log location is often attached as metadata to journal entries anyway. Including it
directly in the message text can nevertheless be convenient when debugging programs.</para>
</listitem>
</varlistentry>
<varlistentry id='log-tid'>
<term><varname>$SYSTEMD_LOG_TID</varname></term>
<listitem><para id='log-tid-body'>A boolean. If true, messages will be prefixed with the current
numerical thread ID (TID).</para>
<para>Note that the this information is attached as metadata to journal entries anyway. Including it
directly in the message text can nevertheless be convenient when debugging programs.</para>
</listitem>
</varlistentry>
<varlistentry id='log-target'>
<term><varname>$SYSTEMD_LOG_TARGET</varname></term>
<listitem><para id='log-target-body'>The destination for log messages. One of
<constant>console</constant> (log to the attached tty), <constant>console-prefixed</constant> (log to
the attached tty but with prefixes encoding the log level and "facility", see <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<constant>kmsg</constant> (log to the kernel circular log buffer), <constant>journal</constant> (log to
the journal), <constant>journal-or-kmsg</constant> (log to the journal if available, and to kmsg
otherwise), <constant>auto</constant> (dermine the appropriate log target automatically, the default),
<constant>null</constant> (disable log output).</para>
<!-- <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated -->
</listitem>
</varlistentry>
<varlistentry id='pager'>
<term><varname>$SYSTEMD_PAGER</varname></term>

28
man/coredumpctl.xml
View File

@ -324,35 +324,47 @@
<title>Examples</title>
<example>
<title>List all the core dumps of a program named foo</title>
<title>List all the core dumps of a program</title>
<programlisting># coredumpctl list foo</programlisting>
<programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
TIME PID UID GID SIG COREFILE EXE SIZE
Tue … 8018 1000 1000 SIGSEGV missing /usr/lib64/firefox/firefox n/a
Wed … 251609 1000 1000 SIGTRAP missing /usr/lib64/firefox/firefox n/a
Fri … 552351 1000 1000 SIGSEGV present /usr/lib64/firefox/firefox 28.7M
</programlisting>
<para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
only the last entry still has an available core file (in external storage on disk).</para>
<para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
relevant entries from the journal. Thus, an unprivileged user will normally only see information about
crashing programs of this user.</para>
</example>
<example>
<title>Invoke gdb on the last core dump</title>
<title>Invoke <command>gdb</command> on the last core dump</title>
<programlisting># coredumpctl debug</programlisting>
<programlisting>$ coredumpctl debug</programlisting>
</example>
<example>
<title>Use gdb to display full register info from the last core dump</title>
<title>Use <command>gdb</command> to display full register info from the last core dump</title>
<programlisting># coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
<programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
</example>
<example>
<title>Show information about a process that dumped core,
matching by its PID 6654</title>
<programlisting># coredumpctl info 6654</programlisting>
<programlisting>$ coredumpctl info 6654</programlisting>
</example>
<example>
<title>Extract the last core dump of /usr/bin/bar to a file named
<filename index="false">bar.coredump</filename></title>
<programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
<programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
</example>
</refsect1>

2
man/homectl.xml
View File

@ -848,7 +848,7 @@
<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>

2
man/journalctl.xml
View File

@ -992,7 +992,7 @@
code is returned.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>

2
man/localectl.xml
View File

@ -185,7 +185,7 @@
otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

2
man/loginctl.xml
View File

@ -415,7 +415,7 @@ Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
</example>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

22
man/machine-info.xml
View File

@ -37,12 +37,10 @@
file without implementing a shell compatible execution
engine.</para>
<para><filename>/etc/machine-info</filename> contains metadata
about the machine that is set by the user or administrator.</para>
<para>Depending on the operating system other configuration files
might be checked for machine information as well, however only as
fallback.</para>
<para><filename>/etc/machine-info</filename> contains metadata about the machine that is set by the user
or administrator. The settings configured here have the highest precedence. When not set, appropriate
values may be determined automatically, based on the information about the hardware or other
configuration files. It is thus completely fine for this file to not be present.</para>
<para>You may use
<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
@ -102,13 +100,11 @@
as well as the special chassis types
<literal>vm</literal> and
<literal>container</literal> for
virtualized systems that lack an immediate physical chassis.
Note that many systems allow detection of the chassis type
automatically (based on firmware information or suchlike).
This setting (if set) shall take precedence over automatically
detected information and is useful to override misdetected
configuration or to manually configure the chassis type where
automatic detection is not available.</para></listitem>
virtualized systems that lack an immediate physical chassis.</para>
<para>Note that most systems allow detection of the chassis type automatically (based on firmware
information or suchlike). This setting should only be used to override a misdetection or to manually
configure the chassis type where automatic detection is not available.</para></listitem>
</varlistentry>
<varlistentry>

2
man/machinectl.xml
View File

@ -980,7 +980,7 @@
otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

2
man/portablectl.xml
View File

@ -428,7 +428,7 @@
<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

17
man/systemctl.xml
View File

@ -2407,12 +2407,17 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
</para></listitem>
</varlistentry>
</variablelist>
<xi:include href="less-variables.xml" xpointer="pager"/>
<xi:include href="less-variables.xml" xpointer="less"/>
<xi:include href="less-variables.xml" xpointer="lesscharset"/>
<xi:include href="less-variables.xml" xpointer="lesssecure"/>
<xi:include href="less-variables.xml" xpointer="colors"/>
<xi:include href="less-variables.xml" xpointer="urlify"/>
<xi:include href="common-variables.xml" xpointer="log-level"/>
<xi:include href="common-variables.xml" xpointer="log-color"/>
<xi:include href="common-variables.xml" xpointer="log-time"/>
<xi:include href="common-variables.xml" xpointer="log-location"/>
<xi:include href="common-variables.xml" xpointer="log-target"/>
<xi:include href="common-variables.xml" xpointer="pager"/>
<xi:include href="common-variables.xml" xpointer="less"/>
<xi:include href="common-variables.xml" xpointer="lesscharset"/>
<xi:include href="common-variables.xml" xpointer="lesssecure"/>
<xi:include href="common-variables.xml" xpointer="colors"/>
<xi:include href="common-variables.xml" xpointer="urlify"/>
</refsect1>
<refsect1>

2
man/systemd-analyze.xml
View File

@ -782,7 +782,7 @@ Service b@0.service not loaded, b.socket cannot be started.
otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

317
man/systemd-coredump.xml
View File

@ -32,29 +32,12 @@
<refsect1>
<title>Description</title>
<para><filename>systemd-coredump@.service</filename> is a system service that can acquire core
dumps from the kernel and handle them in various ways. The <command>systemd-coredump</command>
executable does the actual work. It is invoked twice: once as the handler by the kernel, and the
second time in the <filename>systemd-coredump@.service</filename> to actually write the data to
the journal.</para>
<para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, it runs
in privileged mode, and will connect to the socket created by the
<filename>systemd-coredump.socket</filename> unit, which in turn will spawn an unprivileged
<filename>systemd-coredump@.service</filename> instance to process the core dump. Hence
<filename>systemd-coredump.socket</filename> and <filename>systemd-coredump@.service</filename>
are helper units which do the actual processing of core dumps and are subject to normal service
management.</para>
<para>Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved
for further processing, for example in
<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
<para>By default, <command>systemd-coredump</command> will log the core dump including a backtrace
if possible to the journal and store the core dump itself in an external file in
<filename>/var/lib/systemd/coredump</filename>. These core dumps are deleted after a few days by
default; see <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> for details.</para>
<para><filename>systemd-coredump@.service</filename> is a system service to process core dumps. It will
log a summary of the event to
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
including information about the process identifier, owner, the signal that killed the process, and the
stack trace if possible. It may also save the core dump for later processing. See the "Information about
the crashed process" section below.</para>
<para>The behavior of a specific program upon reception of a signal is governed by a few
factors which are described in detail in
@ -62,14 +45,47 @@
In particular, the core dump will only be processed when the related resource limits are sufficient.
</para>
<para>It is also possible to invoke <command>systemd-coredump</command> with
<option>--backtrace</option> option. In this case, <command>systemd-coredump</command> expects
a journal entry in the journal
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format</ulink>
on standard input. The entry should contain a <varname>MESSAGE=</varname> field and any additional
metadata fields the caller deems reasonable. <command>systemd-coredump</command> will append
additional metadata fields in the same way it does for core dumps received from the kernel. In
this mode, no core dump is stored in the journal.</para>
<para>Core dumps can be written to the journal or saved as a file. In both cases, they can be retrieved
for further processing, for example in
<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
See <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
in particular the <command>list</command> and <command>debug</command> verbs.</para>
<para>By default, <command>systemd-coredump</command> will log the core dump to the journal, including a
backtrace if possible, and store the core dump (an image of the memory contents of the process) itself in
an external file in <filename>/var/lib/systemd/coredump</filename>. These core dumps are deleted after a
few days by default; see <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> for details. Note that the
removal of core files from the file system and the purging of journal entries are independent, and the
core file may be present without the journal entry, and journal entries may point to since-removed core
files. Metadata is attached to core files in the form of extended attributes, so the core files may be
useful even without the full metadata available in the journal entry.
</para>
<refsect2>
<title>Invocation of <command>systemd-coredump</command></title>
<para>The <command>systemd-coredump</command> executable does the actual work. It is invoked twice:
once as the handler by the kernel, and the second time in the
<filename>systemd-coredump@.service</filename> to actually write the data to the journal and process
and save the core file.</para>
<para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, it runs in
privileged mode, and will connect to the socket created by the
<filename>systemd-coredump.socket</filename> unit, which in turn will spawn an unprivileged
<filename>systemd-coredump@.service</filename> instance to process the core dump. Hence
<filename>systemd-coredump.socket</filename> and <filename>systemd-coredump@.service</filename> are
helper units which do the actual processing of core dumps and are subject to normal service
management.</para>
<para>It is also possible to invoke <command>systemd-coredump</command> with
<option>--backtrace</option> option. In this case, <command>systemd-coredump</command> expects a
journal entry in the journal
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format</ulink>
on standard input. The entry should contain a <varname>MESSAGE=</varname> field and any additional
metadata fields the caller deems reasonable. <command>systemd-coredump</command> will append additional
metadata fields in the same way it does for core dumps received from the kernel. In this mode, no core
dump is stored in the journal.</para>
</refsect2>
</refsect1>
<refsect1>
@ -118,22 +134,241 @@
<refsect2>
<title>Disabling coredump processing</title>
<para>To disable potentially resource-intensive processing by <command>systemd-coredump</command>,
set <programlisting>Storage=none
ProcessSizeMax=0</programlisting> in
<para>To disable potentially resource-intensive processing by <command>systemd-coredump</command>, set
<programlisting>Storage=none ProcessSizeMax=0</programlisting> in
<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Usage</title>
<para>Data stored in the journal can be viewed with
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
as usual.
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
can be used to retrieve saved core dumps independent of their location, to display information and to process
them e.g. by passing to the GNU debugger (gdb).</para>
<title>Information about the crashed process</title>
<para><citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> can
be used to retrieve saved core dumps independently of their location, to display information, and to
process them e.g. by passing to the GNU debugger (gdb).</para>
<para>Data stored in the journal can be also viewed with
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> as usual
(or from any other process, using the
<citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> API).
The relevant messages have <constant>MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1</constant>:</para>
<programlisting>$ journalctl MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 -o verbose
…
MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
COREDUMP_PID=552351
COREDUMP_UID=1000
COREDUMP_GID=1000
COREDUMP_SIGNAL_NAME=SIGSEGV
COREDUMP_SIGNAL=11
COREDUMP_TIMESTAMP=1614342930000000
COREDUMP_COMM=Web Content
COREDUMP_EXE=/usr/lib64/firefox/firefox
COREDUMP_USER_UNIT=app-gnome-firefox-552136.scope
COREDUMP_CMDLINE=/usr/lib64/firefox/firefox -contentproc -childID 5 -isForBrowser …
COREDUMP_CGROUP=/user.slice/user-1000.slice/user@1000.service/app.slice/app-….scope
COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst
…
</programlisting>
<para>The following fields are saved (if known) with the journal entry</para>
<variablelist class='journal-directives'>
<varlistentry>
<term><varname>COREDUMP_UID=</varname></term>
<term><varname>COREDUMP_PID=</varname></term>
<term><varname>COREDUMP_GID=</varname></term>
<listitem><para>The process number (PID) and owner (UID and GID) of the crashed process.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_TIMESTAMP=</varname></term>
<listitem><para>The time of the crash as reported by the kernel (in µs since the epoch).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_RLIMIT=</varname></term>
<listitem><para>The core file size soft resource limit, see
<citerefentry project='man-pages'><refentrytitle>getrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_UNIT=</varname></term>
<term><varname>COREDUMP_SLICE=</varname></term>
<listitem><para>The system unit and slice names.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_CGROUP=</varname></term>
<listitem><para>Control group information in the format used in
<filename>/proc/self/cgroup</filename>. On systems with the unified cgroup hierarchy, this is a
single path prefixed with <literal>0::</literal>, and multiple paths prefixed with controller numbers
on legacy systems.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_OWNER_UID=</varname></term>
<term><varname>COREDUMP_USER_UNIT=</varname></term>
<listitem><para>The numerical UID of the user owning the login session or systemd user unit of the
crashed process, and the user manager unit. Both fields are only present for user processes.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_SIGNAL_NAME=</varname></term>
<term><varname>COREDUMP_SIGNAL=</varname></term>
<listitem><para>The terminating signal name and numerical value. (Both are included because signal
numbers vary by architecture.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_CWD=</varname></term>
<term><varname>COREDUMP_ROOT=</varname></term>
<listitem><para>The current working directory and root directory of the crashed process.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_OPEN_FDS=</varname></term>
<listitem><para>Information about open file descriptors, in the following format:</para>
<programlisting><replaceable>fd</replaceable>:<replaceable>/path/to/file</replaceable>
pos: ...
flags: ...
...
<replaceable>fd</replaceable>:<replaceable>/path/to/file</replaceable>
pos: ...
flags: ...
...
</programlisting>
<para>The first line contains the file descriptor number <replaceable>fd</replaceable> and the path,
while subsequent lines show the contents of
<filename>/proc/<replaceable>pid</replaceable>/fdinfo/<replaceable>fd</replaceable></filename>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_COMM=</varname></term>
<term><varname>COREDUMP_EXE=</varname></term>
<term><varname>COREDUMP_PROC_STATUS=</varname></term>
<term><varname>COREDUMP_PROC_MAPS=</varname></term>
<term><varname>COREDUMP_PROC_LIMITS=</varname></term>
<term><varname>COREDUMP_PROC_MOUNTINFO=</varname></term>
<term><varname>COREDUMP_ENVIRON=</varname></term>
<listitem><para>Fields that map the per-process entries in the <filename>/proc/</filename>
filesystem: <filename>/proc/<replaceable>pid</replaceable>/comm</filename> (the command name
associated with the process), <filename>/proc/<replaceable>pid</replaceable>/exe</filename> (the
filename of the executed command), <filename>/proc/<replaceable>pid</replaceable>/status</filename>
(various metadata about the process), <filename>/proc/<replaceable>pid</replaceable>/maps</filename>
(memory regions visible to the process and their access permissions),
<filename>/proc/<replaceable>pid</replaceable>/limits</filename> (the soft and hard resource limits),
<filename>/proc/<replaceable>pid</replaceable>/mountinfo</filename> (mount points in the process's
mount namespace), <filename>/proc/<replaceable>pid</replaceable>/environ</filename>
(the environemnt block of the crashed process).</para>
<para>See
<citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more information.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_HOSTNAME=</varname></term>
<listitem><para>The system hostname.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_CONTAINER_CMDLINE=</varname></term>
<listitem><para>For processes running in a container, the commandline of the process spawning the
container (the first parent process with a different mount namespace).</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP=</varname></term>
<listitem><para>When the core is stored in the journal, the core image itself.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_FILENAME=</varname></term>
<listitem><para>When the core is stored externally, the path the the core file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>COREDUMP_TRUNCATED=</varname></term>
<listitem><para>Set to <literal>1</literal> when the saved coredump was truncated. (A partial core
image may still be processed by some tools, though obviously not all information is available.)
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>MESSAGE=</varname></term>
<listitem><para>The message generated by <command>systemd-coredump</command> that includes the
backtrace if it was successfully generated. When <command>systemd-coredump</command> is invoked with
<option>--backtrace</option>, this field is provided by the caller.</para></listitem>
</varlistentry>
</variablelist>
<para>Various other fields exist in the journal entry, but pertain to the logging process,
i.e. <command>systemd-coredump</command>, not the crashed process. See
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
<para>The following fields are saved (if known) with the external file listed in
<varname>COREDUMP_FILENAME=</varname> as extended attributes:</para>
<variablelist>
<varlistentry>
<term><varname>user.coredump.pid</varname></term>
<term><varname>user.coredump.uid</varname></term>
<term><varname>user.coredump.gid</varname></term>
<term><varname>user.coredump.signal</varname></term>
<term><varname>user.coredump.timestamp</varname></term>
<term><varname>user.coredump.rlimit</varname></term>
<term><varname>user.coredump.hostname</varname></term>
<term><varname>user.coredump.comm</varname></term>
<term><varname>user.coredump.exe</varname></term>
<listitem><para>Those are the same as <varname>COREDUMP_PID=</varname>,
<varname>COREDUMP_UID=</varname>, <varname>COREDUMP_GID=</varname>,
<varname>COREDUMP_SIGNAL=</varname>, <varname>COREDUMP_TIMESTAMP=</varname>,
<varname>COREDUMP_RLIMIT=</varname>, <varname>COREDUMP_HOSTNAME=</varname>,
<varname>COREDUMP_COMM=</varname>, and <varname>COREDUMP_EXE=</varname>, described above.
</para></listitem>
</varlistentry>
</variablelist>
<para>Those can be viewed using
<citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
For the core file described in the journal entry shown above:
<programlisting>$ getfattr --absolute-names -d /var/lib/systemd/coredump/core.Web….552351.….zst
# file: /var/lib/systemd/coredump/core.Web….552351.….zst
user.coredump.pid="552351"
user.coredump.uid="1000"
user.coredump.gid="1000"
user.coredump.signal="11"
user.coredump.timestamp="1614342930000000"
user.coredump.comm="Web Content"
user.coredump.exe="/usr/lib64/firefox/firefox"
…
</programlisting>
</para>
</refsect1>
<refsect1>

2
man/systemd-inhibit.xml
View File

@ -141,7 +141,7 @@
doing so.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

2
man/systemd-nspawn.xml
View File

@ -1486,7 +1486,7 @@
</refsect2>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>

39
man/systemd-resolved.service.xml
View File

@ -115,8 +115,8 @@
<refsect1>
<title>Protocols and Routing</title>
<para>Lookup requests are routed to the available DNS servers, LLMNR, and MulticastDNS interfaces
according to the following rules:</para>
<para>The lookup requests that <filename>systemd-resolved.service</filename> receives are routed to the
available DNS servers, LLMNR, and MulticastDNS interfaces according to the following rules:</para>
<itemizedlist>
<listitem><para>Names for which synthetic records are generated (the local hostname,
@ -172,7 +172,8 @@
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
description of globally configured DNS settings.</para>
<para>The following query routing logic applies for unicast DNS traffic:</para>
<para>The following query routing logic applies for unicast DNS lookups initiated by
<filename>systemd-resolved.service</filename>:</para>
<itemizedlist>
<listitem><para>If a name to look up matches (that is: is equal to or has as suffix) any of the
@ -228,8 +229,22 @@
<itemizedlist>
<listitem><para>Some names are always resolved internally (see Synthetic Records above). Traditionally
they would be resolved by <filename>nss-files</filename>, and only if provided in
<filename>/etc/hosts</filename>.</para></listitem>
they would be resolved by <filename>nss-files</filename> if provided in
<filename>/etc/hosts</filename>. But note that the details of how a query is constructed are under the
control of the client library. <filename>nss-dns</filename> will first try to resolve names using
search domains and even if those queries are routed to <filename>systemd-resolved</filename>, it will
send them out over the network using the usual rules for multi-label name routing <footnote><para>For
example, if <filename>/etc/nsswitch.conf</filename> has <programlisting>nameserver 127.0.0.53
search foobar.com barbar.com
</programlisting>and we look up <literal>localhost</literal>, <filename>nss-dns</filename> will send
the following queries to <filename>systemd-resolved</filename> listening on 127.0.0.53:53: first
<literal>localhost.foobar.com</literal>, then <literal>localhost.barbar.com</literal>, and finally
<literal>localhost</literal>. If (hopefully) the first two queries fail,
<filename>systemd-resolved</filename> will synthesize an answer for the third query.</para>
<para>When using <filename>nss-dns</filename> with any search domains, it is thus crucial to always
configure <filename>nss-files</filename> with higher priority and provide mappings for names that
should not be resolved using search domains.</para></footnote>.</para></listitem>
<listitem><para>Single-label names are not resolved for A and AAAA records using unicast DNS (unless
overridden with <varname>ResolveUnicastSingleLabel=</varname>, see
@ -246,13 +261,13 @@
has failed, as absolute, while other names would be resolved in opposite order. The
<varname>ndots</varname> option in <filename>/etc/resolv.conf</filename> was used to control how many
dots the name needs to have to be resolved as relative first. This stub resolver does not implement
this at all: multi-label names are only resolved as FQDNs. (There are currently more than 1500
top-level domain names defined, and new ones are added regularly, often using "attractive" names that
are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility
in both directions: a valid global name could be obscured by a local name, and resolution of a relative
local name could suddenly break when a new top-level domain is created, or when a new subdomain of a
top-level domain in registered. Resolving any given name as either relative or absolute avoids this
ambiguity.)</para></listitem>
this at all: multi-label names are only resolved as FQDNs.<footnote><para>There are currently more than
1500 top-level domain names defined, and new ones are added regularly, often using "attractive" names
that are also likely to be used locally. Not looking up multi-label names in this fashion avoids
fragility in both directions: a valid global name could be obscured by a local name, and resolution of
a relative local name could suddenly break when a new top-level domain is created, or when a new
subdomain of a top-level domain in registered. Resolving any given name as either relative or absolute
avoids this ambiguity.)</para></footnote></para></listitem>
<listitem><para>This resolver has a notion of the special <literal>.local</literal> domain used for
MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly

14
man/systemd-sysv-generator.xml
View File

@ -60,6 +60,20 @@
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Environment</title>
<para>Special variables understood by <command>systemd-sysv-generator</command>:</para>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term>
<listitem><para>Controls where systemd looks for SysV init scripts.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>

53
man/systemd-tmpfiles.xml
View File

@ -48,23 +48,20 @@
<refsect1>
<title>Description</title>
<para><command>systemd-tmpfiles</command> creates, deletes, and
cleans up volatile and temporary files and directories, based on
the configuration file format and location specified in
<citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para><command>systemd-tmpfiles</command> creates, deletes, and cleans up volatile and temporary files
and directories, using the configuration file format and location specified in
<citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It must
be invoked with one or more options <option>--create</option>, <option>--remove</option>, and
<option>--clean</option>, to select the respective subset of operations.</para>
<para>If invoked with no arguments, it applies all directives from all configuration
files. When invoked with <option>--replace=<replaceable>PATH</replaceable></option>,
arguments specified on the command line are used instead of the configuration file
<replaceable>PATH</replaceable>. Otherwise, if one or more absolute filenames are
passed on the command line, only the directives in these files are applied. If
<literal>-</literal> is specified instead of a filename, directives are read from
standard input. If only the basename of a configuration file is specified, all
configuration directories as specified in
<citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
are searched for a matching file and the file found that has the highest priority is
executed.</para>
<para>By default, directives from all configuration files are applied. When invoked with
<option>--replace=<replaceable>PATH</replaceable></option>, arguments specified on the command line are
used instead of the configuration file <replaceable>PATH</replaceable>. Otherwise, if one or more
absolute filenames are passed on the command line, only the directives in these files are applied. If
<literal>-</literal> is specified instead of a filename, directives are read from standard input. If only
the basename of a configuration file is specified, all configuration directories as specified in
<citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
searched for a matching file and the file found that has the highest priority is executed.</para>
<para>System services (<filename>systemd-tmpfiles-setup.service</filename>,
<filename>systemd-tmpfiles-setup-dev.service</filename>,
@ -81,6 +78,12 @@
system instance, such as the one typically configured for <filename>/tmp/</filename>, will thus also
affect files created by the user instance if they are placed in <filename>/tmp/</filename>, even if the
user instance's time-based cleanup is turned off.</para>
<para>To re-apply settings after configuration has been modified, simply restart
<filename>systemd-tmpfiles-clean.service</filename>, which will apply any settings which can be safely
executed at runtime. To debug <command>systemd-tmpfiles</command>, it may be useful to invoke it
directly from the command line with increased log level (see <varname>$SYSTEMD_LOG_LEVEL</varname>
below).</para>
</refsect1>
<refsect1>
@ -227,6 +230,24 @@
<programlisting>systemd-tmpfiles --remove --create</programlisting>
</refsect1>
<refsect1>
<title>Environment</title>
<variablelist class='environment-variables'>
<xi:include href="common-variables.xml" xpointer="log-level" />
<xi:include href="common-variables.xml" xpointer="log-color" />
<xi:include href="common-variables.xml" xpointer="log-time" />
<xi:include href="common-variables.xml" xpointer="log-location" />
<xi:include href="common-variables.xml" xpointer="log-target" />
<xi:include href="common-variables.xml" xpointer="pager" />
<xi:include href="common-variables.xml" xpointer="less" />
<xi:include href="common-variables.xml" xpointer="lesscharset" />
<xi:include href="common-variables.xml" xpointer="lesssecure" />
<xi:include href="common-variables.xml" xpointer="colors" />
<xi:include href="common-variables.xml" xpointer="urlify" />
</variablelist>
</refsect1>
<refsect1>
<title>Unprivileged --cleanup operation</title>

35
man/systemd.exec.xml
View File

@ -2263,18 +2263,24 @@ SystemCallErrorNumber=EPERM</programlisting>
<varlistentry>
<term><varname>Environment=</varname></term>
<listitem><para>Sets environment variables for executed processes. Takes a space-separated list of
variable assignments. This option may be specified more than once, in which case all listed variables
will be set. If the same variable is set twice, the later setting will override the earlier
setting. If the empty string is assigned to this option, the list of environment variables is reset,
all prior assignments have no effect. Variable expansion is not performed inside the strings,
however, specifier expansion is possible. The <literal>$</literal> character has no special
meaning. If you need to assign a value containing spaces or the equals sign to a variable, use double
quotes (") for the assignment.</para>
<listitem><para>Sets environment variables for executed processes. Each line is unquoted using the
rules described in "Quoting" section in
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and becomes a list of variable assignments. If you need to assign a value containing spaces or the
equals sign to a variable, put quotes around the whole assignment. Variable expansion is not
performed inside the strings and the <literal>$</literal> character has no special meaning. Specifier
expansion is performed, see the "Specifiers" section in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>The names of the variables can contain ASCII letters, digits, and the underscore
character. Variable names cannot be empty or start with a digit. In variable values, most characters
are allowed, but non-printable characters are currently rejected.</para>
<para>This option may be specified more than once, in which case all listed variables will be set. If
the same variable is listed twice, the later setting will override the earlier setting. If the empty
string is assigned to this option, the list of environment variables is reset, all prior assignments
have no effect.</para>
<para>The names of the variables can contain ASCII letters, digits, and the underscore character.
Variable names cannot be empty or start with a digit. In variable values, most characters are
allowed, but non-printable characters are currently rejected.</para>
<para>Example:
<programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting>
@ -2284,10 +2290,9 @@ SystemCallErrorNumber=EPERM</programlisting>
<literal>word3</literal>, <literal>$word 5 6</literal>.
</para>
<para>
See <citerefentry
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details
about environment variables.</para>
<para>See <citerefentry
project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details about environment variables.</para>
<para>Note that environment variables are not suitable for passing secrets (such as passwords, key
material, …) to service processes. Environment variables set for a unit are exposed to unprivileged

96
man/systemd.service.xml
View File

@ -1107,11 +1107,9 @@
</variablelist>
<para>Check
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more settings.</para>
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
settings.</para>
</refsect1>
<refsect1>
@ -1126,21 +1124,13 @@
<varname>ExecStop=</varname>, and
<varname>ExecStopPost=</varname> options.</para>
<para>Multiple command lines may be concatenated in a single
directive by separating them with semicolons (these semicolons
must be passed as separate words). Lone semicolons may be escaped
as <literal>\;</literal>.</para>
<para>Multiple command lines may be concatenated in a single directive by separating them with semicolons
(these semicolons must be passed as separate words). Lone semicolons may be escaped as
<literal>\;</literal>.</para>
<para>Each command line is split on whitespace, with the first item being the command to
execute, and the subsequent items being the arguments. Double quotes ("…") and single quotes
('…') may be used to wrap a whole item (the opening quote may appear only at the beginning or
after whitespace that is not quoted, and the closing quote must be followed by whitespace or the
end of line), in which case everything until the next matching quote becomes part of the same
argument. Quotes themselves are removed. C-style escapes are also supported. The table below
contains the list of known escape patterns. Only escape patterns which match the syntax in the
table are allowed; other patterns may be added in the future and unknown patterns will result in
a warning. In particular, any backslashes should be doubled. Finally, a trailing backslash
(<literal>\</literal>) may be used to merge lines.</para>
<para>Each command line is unquoted using the rules described in "Quoting" section in
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
first item becomes the command to execute, and the subsequent items the arguments.</para>
<para>This syntax is inspired by shell syntax, but only the meta-characters and expansions
described in the following paragraphs are understood, and the expansion of variables is
@ -1240,74 +1230,6 @@ ls</programlisting>
<literal>&gt;/dev/null</literal>,
<literal>&amp;</literal>, <literal>;</literal>, and
<literal>ls</literal>.</para>
<table>
<title>C escapes supported in command lines and environment variables</title>
<tgroup cols='2'>
<colspec colname='escape' />
<colspec colname='meaning' />
<thead>
<row>
<entry>Literal</entry>
<entry>Actual value</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>\a</literal></entry>
<entry>bell</entry>
</row>
<row>
<entry><literal>\b</literal></entry>
<entry>backspace</entry>
</row>
<row>
<entry><literal>\f</literal></entry>
<entry>form feed</entry>
</row>
<row>
<entry><literal>\n</literal></entry>
<entry>newline</entry>
</row>
<row>
<entry><literal>\r</literal></entry>
<entry>carriage return</entry>
</row>
<row>
<entry><literal>\t</literal></entry>
<entry>tab</entry>
</row>
<row>
<entry><literal>\v</literal></entry>
<entry>vertical tab</entry>
</row>
<row>
<entry><literal>\\</literal></entry>
<entry>backslash</entry>
</row>
<row>
<entry><literal>\"</literal></entry>
<entry>double quotation mark</entry>
</row>
<row>
<entry><literal>\'</literal></entry>
<entry>single quotation mark</entry>
</row>
<row>
<entry><literal>\s</literal></entry>
<entry>space</entry>
</row>
<row>
<entry><literal>\x<replaceable>xx</replaceable></literal></entry>
<entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
</row>
<row>
<entry><literal>\<replaceable>nnn</replaceable></literal></entry>
<entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>

90
man/systemd.syntax.xml
View File

@ -74,10 +74,10 @@
<filename>.ini</filename> files.
</para>
<para>Each file is a plain text file divided into sections, with configuration entries in the
style <replaceable>key</replaceable>=<replaceable>value</replaceable>.
Whitespace immediately before or after the <literal>=</literal> is ignored. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are
ignored, which may be used for commenting.</para>
<para>Each file is a plain text file divided into sections, with configuration entries in the style
<replaceable>key</replaceable>=<replaceable>value</replaceable>. Whitespace immediately before or after
the <literal>=</literal> is ignored. Empty lines and lines starting with <literal>#</literal> or
<literal>;</literal> are ignored, which may be used for commenting.</para>
<para>Lines ending in a backslash are concatenated with the following line while reading and the
backslash is replaced by a space character. This may be used to wrap long lines. The limit on
@ -129,6 +129,88 @@ KeyThree=value 3\
file format.</para>
</refsect1>
<refsect1>
<title>Quoting</title>
<para>For settings where quoting is allowed, the following general rules apply: double quotes ("…") and
single quotes ('…') may be used to wrap a whole item (the opening quote may appear only at the beginning
or after whitespace that is not quoted, and the closing quote must be followed by whitespace or the end
of line), in which case everything until the next matching quote becomes part of the same item. Quotes
themselves are removed. C-style escapes are also supported. The table below contains the list of known
escape patterns. Only escape patterns which match the syntax in the table are allowed; other patterns may
be added in the future and unknown patterns will result in a warning. In particular, any backslashes
should be doubled. Finally, a trailing backslash (<literal>\</literal>) may be used to merge lines, as
described above.</para>
<table>
<title>Supported C escapes</title>
<tgroup cols='2'>
<colspec colname='escape' />
<colspec colname='meaning' />
<thead>
<row>
<entry>Literal</entry>
<entry>Actual value</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>\a</literal></entry>
<entry>bell</entry>
</row>
<row>
<entry><literal>\b</literal></entry>
<entry>backspace</entry>
</row>
<row>
<entry><literal>\f</literal></entry>
<entry>form feed</entry>
</row>
<row>
<entry><literal>\n</literal></entry>
<entry>newline</entry>
</row>
<row>
<entry><literal>\r</literal></entry>
<entry>carriage return</entry>
</row>
<row>
<entry><literal>\t</literal></entry>
<entry>tab</entry>
</row>
<row>
<entry><literal>\v</literal></entry>
<entry>vertical tab</entry>
</row>
<row>
<entry><literal>\\</literal></entry>
<entry>backslash</entry>
</row>
<row>
<entry><literal>\"</literal></entry>
<entry>double quotation mark</entry>
</row>
<row>
<entry><literal>\'</literal></entry>
<entry>single quotation mark</entry>
</row>
<row>
<entry><literal>\s</literal></entry>
<entry>space</entry>
</row>
<row>
<entry><literal>\x<replaceable>xx</replaceable></literal></entry>
<entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
</row>
<row>
<entry><literal>\<replaceable>nnn</replaceable></literal></entry>
<entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
<title>See Also</title>
<para>

94
man/systemd.unit.xml
View File

@ -976,16 +976,24 @@
<term><varname>JobTimeoutSec=</varname></term>
<term><varname>JobRunningTimeoutSec=</varname></term>
<listitem><para>When a job for this unit is queued, a timeout <varname>JobTimeoutSec=</varname> may be
configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually
started. If either time limit is reached, the job will be cancelled, the unit however will not change state or
even enter the <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts
disabled), except for device units (<varname>JobRunningTimeoutSec=</varname> defaults to
<varname>DefaultTimeoutStartSec=</varname>). NB: this timeout is independent from any unit-specific timeout
(for example, the timeout set with <varname>TimeoutStartSec=</varname> in service units) as the job timeout has
no effect on the unit itself, only on the job that might be pending for it. Or in other words: unit-specific
timeouts are useful to abort unit state changes, and revert them. The job timeout set with this option however
is useful to abort only the job waiting for the unit state to change.</para>
<listitem><para><varname>JobTimeoutSec=</varname> specifies a timeout for the whole job that starts
running when the job is queued. <varname>JobRunningTimeoutSec=</varname> specifies a timeout that
starts running when the queued job is actually started. If either limit is reached, the job will be
cancelled, the unit however will not change state or even enter the <literal>failed</literal> mode.
</para>
<para>Both settings take a time span with the default unit of seconds, but other units may be
specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
The default is <literal>infinity</literal> (job timeouts disabled), except for device units where
<varname>JobRunningTimeoutSec=</varname> defaults to <varname>DefaultTimeoutStartSec=</varname>.
</para>
<para>Note: these timeouts are independent from any unit-specific timeouts (for example, the timeout
set with <varname>TimeoutStartSec=</varname> in service units). The job timeout has no effect on the
unit itself. Or in other words: unit-specific timeouts are useful to abort unit state changes, and
revert them. The job timeout set with this option however is useful to abort only the job waiting for
the unit state to change.</para>
</listitem>
</varlistentry>
@ -993,13 +1001,14 @@
<term><varname>JobTimeoutAction=</varname></term>
<term><varname>JobTimeoutRebootArgument=</varname></term>
<listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when
the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
<listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to
take when the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
<varname>JobRunningTimeoutSec=</varname> above. It takes the same values as
<varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
<varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the
<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call.
</para></listitem>
<varname>StartLimitAction=</varname>. Defaults to <option>none</option>.</para>
<para><varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to
the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
call.</para></listitem>
</varlistentry>
<varlistentry>
@ -1007,28 +1016,39 @@
<term><varname>StartLimitBurst=<replaceable>burst</replaceable></varname></term>
<listitem><para>Configure unit start rate limiting. Units which are started more than
<replaceable>burst</replaceable> times within an <replaceable>interval</replaceable> time interval are not
permitted to start any more. Use <varname>StartLimitIntervalSec=</varname> to configure the checking interval
(defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, set it to 0 to
disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many starts per
interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager configuration
file). These configuration options are particularly useful in conjunction with the service setting
<varname>Restart=</varname> (see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however,
they apply to all kinds of starts (including manual), not just those triggered by the
<varname>Restart=</varname> logic. Note that units which are configured for <varname>Restart=</varname> and
which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted
manually at a later point, after the <replaceable>interval</replaceable> has passed. From this point on, the
restart logic is activated again. Note that <command>systemctl reset-failed</command> will cause the restart
rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit
and the start limit interferes with that. Note that this rate-limiting is enforced after any unit condition
checks are executed, and hence unit activations with failing conditions do not count towards this rate
limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose
activation may either never fail, or may succeed only a single time.</para>
<replaceable>burst</replaceable> times within an <replaceable>interval</replaceable> time span are
not permitted to start any more. Use <varname>StartLimitIntervalSec=</varname> to configure the
checking interval and <varname>StartLimitBurst=</varname> to configure how many starts per interval
are allowed.</para>
<para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are
flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously
has no effect.</para></listitem>
<para><replaceable>interval</replaceable> is a time span with the default unit of seconds, but other
units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, and may
be set to 0 to disable any kind of rate limiting. <replaceable>burst</replaceable> is a number and
defaults to <varname>DefaultStartLimitBurst=</varname> in manager configuration file.</para>
<para>These configuration options are particularly useful in conjunction with the service setting
<varname>Restart=</varname> (see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>);
however, they apply to all kinds of starts (including manual), not just those triggered by the
<varname>Restart=</varname> logic.</para>
<para>Note that units which are configured for <varname>Restart=</varname>, and which reach the start
limit are not attempted to be restarted anymore; however, they may still be restarted manually at a
later point, after the <replaceable>interval</replaceable> has passed. From that point on, the
restart logic is activated again. <command>systemctl reset-failed</command> will cause the restart
rate counter for a service to be flushed, which is useful if the administrator wants to manually
start a unit and the start limit interferes with that. Rate-limiting is enforced after any unit
condition checks are executed, and hence unit activations with failing conditions do not count
towards the rate limit.</para>
<para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters
are flushed out too. This means that configuring start rate limiting for a unit that is not
referenced continuously has no effect.</para>
<para>This setting does not apply to slice, target, device, and scope units, since they are unit
types whose activation may either never fail, or may succeed only a single time.</para></listitem>
</varlistentry>
<varlistentry>

63
man/systemd.xml
View File

@ -628,40 +628,44 @@
<para>Some of the variables understood by <command>systemd</command>:</para>
<variablelist class='environment-variables'>
<varlistentry>
<term><varname>$SYSTEMD_LOG_COLOR</varname></term>
<listitem><para>Controls whether systemd highlights important log messages. This can be overridden
with <option>--log-color=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
<listitem><para>systemd reads the log level from this environment variable. This can be overridden
with <option>--log-level=</option>.</para></listitem>
<listitem><xi:include href="common-variables.xml" xpointer="log-level-body" />
<para>This can be overridden with <option>--log-level=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
<listitem><para>Controls whether systemd prints the code location along with log messages. This can
be overridden with <option>--log-location=</option>.</para></listitem>
</varlistentry>
<term><varname>$SYSTEMD_LOG_COLOR</varname></term>
<listitem><xi:include href="common-variables.xml" xpointer="log-color-body" />
<varlistentry>
<term><varname>$SYSTEMD_LOG_TARGET</varname></term>
<listitem><para>systemd reads the log target from this environment variable. This can be overridden
with <option>--log-target=</option>.</para></listitem>
<para>This can be overridden with <option>--log-color=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_LOG_TIME</varname></term>
<listitem><para>Controls whether systemd prefixes log messages with the current time. This can be
overridden with <option>--log-time=</option>.</para></listitem>
<listitem><xi:include href="common-variables.xml" xpointer="log-time-body" />
<para>This can be overridden with <option>--log-time=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
<listitem><xi:include href="common-variables.xml" xpointer="log-location-body" />
<para>This can be overridden with <option>--log-location=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_LOG_TID</varname></term>
<listitem><para>Controls whether systemd prefixes log messages with the current thread ID
(TID).</para></listitem>
<listitem><xi:include href="common-variables.xml" xpointer="log-tid-body" /></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_LOG_TARGET</varname></term>
<listitem><xi:include href="common-variables.xml" xpointer="log-target-body" />
<para>This can be overridden with <option>--log-target=</option>.</para></listitem>
</varlistentry>
<varlistentry>
@ -692,13 +696,6 @@
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term>
<listitem><para>Controls where systemd looks for SysV init
scripts.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term>
@ -706,12 +703,12 @@
script runlevel link farms.</para></listitem>
</varlistentry>
<xi:include href="less-variables.xml" xpointer="pager"/>
<xi:include href="less-variables.xml" xpointer="less"/>
<xi:include href="less-variables.xml" xpointer="lesscharset"/>
<xi:include href="less-variables.xml" xpointer="lesssecure"/>
<xi:include href="less-variables.xml" xpointer="colors"/>
<xi:include href="less-variables.xml" xpointer="urlify"/>
<xi:include href="common-variables.xml" xpointer="pager"/>
<xi:include href="common-variables.xml" xpointer="less"/>
<xi:include href="common-variables.xml" xpointer="lesscharset"/>
<xi:include href="common-variables.xml" xpointer="lesssecure"/>
<xi:include href="common-variables.xml" xpointer="colors"/>
<xi:include href="common-variables.xml" xpointer="urlify"/>
<varlistentry>
<term><varname>$LISTEN_PID</varname></term>

2
man/timedatectl.xml
View File

@ -253,7 +253,7 @@
<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>

9
man/timesyncd.conf.xml
View File

@ -73,7 +73,7 @@
the current server does not satisfy this limit, <command>systemd-timesyncd</command> will switch
to a different server.</para>
<para>Takes a time value. The default unit is seconds, but other units may be specified, see
<para>Takes a time span value. The default unit is seconds, but other units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to 5 seconds.</para></listitem>
</varlistentry>
@ -85,8 +85,9 @@
minimum poll interval, and is adjusted within the specified limits in response to received packets.
</para>
<para>Each setting takes a time value. The default unit is seconds, but other units may be specified,
see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
<para>Each setting takes a time span value. The default unit is seconds, but other units may be
specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
<varname>PollIntervalMinSec=</varname> defaults to 32 seconds and must not be smaller than
16 seconds. <varname>PollIntervalMaxSec=</varname> defaults to 34 min 8 s (2048 seconds) and must be
larger than <varname>PollIntervalMinSec=</varname>.</para></listitem>
@ -97,7 +98,7 @@
<listitem><para>Specifies the minimum delay before subsequent attempts to contact a new NTP server
are made.</para>
<para>Takes a time value. The default unit is seconds, but other units may be specified, see
<para>Takes a time span value. The default unit is seconds, but other units may be specified, see
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Defaults to 30 seconds and must not be smaller than 1 second.</para></listitem>
</varlistentry>

84
man/udev.xml
View File

@ -79,14 +79,16 @@
<varlistentry>
<term><literal>==</literal></term>
<listitem>
<para>Compare for equality.</para>
<para>Compare for equality. (The specified key has the specified value.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>!=</literal></term>
<listitem>
<para>Compare for inequality.</para>
<para>Compare for inequality. (The specified key doesn't have the specified value, or the
specified key is not present at all.)
</para>
</listitem>
</varlistentry>
@ -166,6 +168,13 @@
</listitem>
</varlistentry>
<varlistentry>
<term><varname>KERNELS</varname></term>
<listitem>
<para>Search the devpath upwards for a matching device name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NAME</varname></term>
<listitem>
@ -190,36 +199,6 @@
<para>Match the subsystem of the event device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DRIVER</varname></term>
<listitem>
<para>Match the driver name of the event device. Only set this key for devices
which are bound to a driver at the time the event is generated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ATTR{<replaceable>filename</replaceable>}</varname></term>
<listitem>
<para>Match sysfs attribute values of the event device. Trailing
whitespace in the attribute values is ignored unless the specified match
value itself contains trailing whitespace.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>SYSCTL{<replaceable>kernel parameter</replaceable>}</varname></term>
<listitem>
<para>Match a kernel parameter value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>KERNELS</varname></term>
<listitem>
<para>Search the devpath upwards for a matching device name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>SUBSYSTEMS</varname></term>
@ -228,6 +207,14 @@
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DRIVER</varname></term>
<listitem>
<para>Match the driver name of the event device. Only set this key for devices
which are bound to a driver at the time the event is generated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>DRIVERS</varname></term>
<listitem>
@ -236,19 +223,31 @@
</varlistentry>
<varlistentry>
<term><varname>ATTRS{<replaceable>filename</replaceable>}</varname></term>
<term><varname>ATTR{<replaceable>filename</replaceable>}</varname></term>
<listitem>
<para>Search the devpath upwards for a device with matching sysfs attribute values.
If multiple <varname>ATTRS</varname> matches are specified, all of them
must match on the same device. Trailing whitespace in the attribute values is ignored
unless the specified match value itself contains trailing whitespace.</para>
<para>Match sysfs attribute value of the event device.</para>
<para>Trailing whitespace in the attribute values is ignored unless the specified match value
itself contains trailing whitespace.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>TAGS</varname></term>
<term><varname>ATTRS{<replaceable>filename</replaceable>}</varname></term>
<listitem>
<para>Search the devpath upwards for a device with matching tag.</para>
<para>Search the devpath upwards for a device with matching sysfs attribute values. If
multiple <varname>ATTRS</varname> matches are specified, all of them must match on the same
device.</para>
<para>Trailing whitespace in the attribute values is ignored unless the specified match value
itself contains trailing whitespace.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>SYSCTL{<replaceable>kernel parameter</replaceable>}</varname></term>
<listitem>
<para>Match a kernel parameter value.</para>
</listitem>
</varlistentry>
@ -292,6 +291,13 @@
</listitem>
</varlistentry>
<varlistentry>
<term><varname>TAGS</varname></term>
<listitem>
<para>Search the devpath upwards for a device with matching tag.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>TEST{<replaceable>octal mode mask</replaceable>}</varname></term>
<listitem>

2
man/userdbctl.xml
View File

@ -256,7 +256,7 @@ AuthorizedKeysCommandUser root
<para>On success, 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<xi:include href="common-variables.xml" />
<refsect1>
<title>See Also</title>

16
src/basic/log.c
View File

@ -1310,15 +1310,15 @@ bool log_on_console(void) {
}
static const char *const log_target_table[_LOG_TARGET_MAX] = {
[LOG_TARGET_CONSOLE] = "console",
[LOG_TARGET_CONSOLE] = "console",
[LOG_TARGET_CONSOLE_PREFIXED] = "console-prefixed",
[LOG_TARGET_KMSG] = "kmsg",
[LOG_TARGET_JOURNAL] = "journal",
[LOG_TARGET_JOURNAL_OR_KMSG] = "journal-or-kmsg",
[LOG_TARGET_SYSLOG] = "syslog",
[LOG_TARGET_SYSLOG_OR_KMSG] = "syslog-or-kmsg",
[LOG_TARGET_AUTO] = "auto",
[LOG_TARGET_NULL] = "null",
[LOG_TARGET_KMSG] = "kmsg",
[LOG_TARGET_JOURNAL] = "journal",
[LOG_TARGET_JOURNAL_OR_KMSG] = "journal-or-kmsg",
[LOG_TARGET_SYSLOG] = "syslog",
[LOG_TARGET_SYSLOG_OR_KMSG] = "syslog-or-kmsg",
[LOG_TARGET_AUTO] = "auto",
[LOG_TARGET_NULL] = "null",
};
DEFINE_STRING_TABLE_LOOKUP(log_target, LogTarget);

52
src/basic/syslog-util.c
View File

@ -57,26 +57,26 @@ int syslog_parse_priority(const char **p, int *priority, bool with_facility) {
}
static const char *const log_facility_unshifted_table[LOG_NFACILITIES] = {
[LOG_FAC(LOG_KERN)] = "kern",
[LOG_FAC(LOG_USER)] = "user",
[LOG_FAC(LOG_MAIL)] = "mail",
[LOG_FAC(LOG_DAEMON)] = "daemon",
[LOG_FAC(LOG_AUTH)] = "auth",
[LOG_FAC(LOG_SYSLOG)] = "syslog",
[LOG_FAC(LOG_LPR)] = "lpr",
[LOG_FAC(LOG_NEWS)] = "news",
[LOG_FAC(LOG_UUCP)] = "uucp",
[LOG_FAC(LOG_CRON)] = "cron",
[LOG_FAC(LOG_KERN)] = "kern",
[LOG_FAC(LOG_USER)] = "user",
[LOG_FAC(LOG_MAIL)] = "mail",
[LOG_FAC(LOG_DAEMON)] = "daemon",
[LOG_FAC(LOG_AUTH)] = "auth",
[LOG_FAC(LOG_SYSLOG)] = "syslog",
[LOG_FAC(LOG_LPR)] = "lpr",
[LOG_FAC(LOG_NEWS)] = "news",
[LOG_FAC(LOG_UUCP)] = "uucp",
[LOG_FAC(LOG_CRON)] = "cron",
[LOG_FAC(LOG_AUTHPRIV)] = "authpriv",
[LOG_FAC(LOG_FTP)] = "ftp",
[LOG_FAC(LOG_LOCAL0)] = "local0",
[LOG_FAC(LOG_LOCAL1)] = "local1",
[LOG_FAC(LOG_LOCAL2)] = "local2",
[LOG_FAC(LOG_LOCAL3)] = "local3",
[LOG_FAC(LOG_LOCAL4)] = "local4",
[LOG_FAC(LOG_LOCAL5)] = "local5",
[LOG_FAC(LOG_LOCAL6)] = "local6",
[LOG_FAC(LOG_LOCAL7)] = "local7"
[LOG_FAC(LOG_FTP)] = "ftp",
[LOG_FAC(LOG_LOCAL0)] = "local0",
[LOG_FAC(LOG_LOCAL1)] = "local1",
[LOG_FAC(LOG_LOCAL2)] = "local2",
[LOG_FAC(LOG_LOCAL3)] = "local3",
[LOG_FAC(LOG_LOCAL4)] = "local4",
[LOG_FAC(LOG_LOCAL5)] = "local5",
[LOG_FAC(LOG_LOCAL6)] = "local6",
[LOG_FAC(LOG_LOCAL7)] = "local7",
};
DEFINE_STRING_TABLE_LOOKUP_WITH_FALLBACK(log_facility_unshifted, int, LOG_FAC(~0));
@ -86,14 +86,14 @@ bool log_facility_unshifted_is_valid(int facility) {
}
static const char *const log_level_table[] = {
[LOG_EMERG] = "emerg",
[LOG_ALERT] = "alert",
[LOG_CRIT] = "crit",
[LOG_ERR] = "err",
[LOG_EMERG] = "emerg",
[LOG_ALERT] = "alert",
[LOG_CRIT] = "crit",
[LOG_ERR] = "err",
[LOG_WARNING] = "warning",
[LOG_NOTICE] = "notice",
[LOG_INFO] = "info",
[LOG_DEBUG] = "debug"
[LOG_NOTICE] = "notice",
[LOG_INFO] = "info",
[LOG_DEBUG] = "debug",
};
DEFINE_STRING_TABLE_LOOKUP_WITH_FALLBACK(log_level, int, LOG_DEBUG);

10
src/coredump/coredump.c
View File

@ -354,7 +354,7 @@ static int save_external_coredump(
context->meta[META_ARGV_RLIMIT]);
if (rlimit < page_size())
/* Is coredumping disabled? Then don't bother saving/processing the
* coredump. Anything below PAGE_SIZE cannot give a readable coredump
* coredump. Anything below PAGE_SIZE cannot give a readable coredump
* (the kernel uses ELF_EXEC_PAGESIZE which is not easily accessible, but
* is usually the same as PAGE_SIZE. */
return log_info_errno(SYNTHETIC_ERRNO(EBADSLT),
@ -435,10 +435,10 @@ static int save_external_coredump(
if (tmp)
unlink_noerrno(tmp);
*ret_filename = TAKE_PTR(fn_compressed); /* compressed */
*ret_node_fd = TAKE_FD(fd_compressed); /* compressed */
*ret_data_fd = TAKE_FD(fd); /* uncompressed */
*ret_size = (uint64_t) st.st_size; /* uncompressed */
*ret_filename = TAKE_PTR(fn_compressed); /* compressed */
*ret_node_fd = TAKE_FD(fd_compressed); /* compressed */
*ret_data_fd = TAKE_FD(fd); /* uncompressed */
*ret_size = (uint64_t) st.st_size; /* uncompressed */
return 0;