<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="systemd-analyze"
+<refentry id="systemd-analyze" conditional='ENABLE_ANALYZE'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">log-level</arg>
- <arg choice="opt"><replaceable>LEVEL</replaceable></arg>
+ <arg choice="plain">dump</arg>
</cmdsynopsis>
+
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">log-target</arg>
- <arg choice="opt"><replaceable>TARGET</replaceable></arg>
+ <arg choice="plain">plot</arg>
+ <arg choice="opt">>file.svg</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">service-watchdogs</arg>
- <arg choice="opt"><replaceable>BOOL</replaceable></arg>
+ <arg choice="plain">dot</arg>
+ <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
+ <arg choice="opt">>file.dot</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">dump</arg>
+ <arg choice="plain">unit-paths</arg>
</cmdsynopsis>
-
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">plot</arg>
- <arg choice="opt">>file.svg</arg>
+ <arg choice="plain">exit-status</arg>
+ <arg choice="opt" rep="repeat"><replaceable>STATUS</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">dot</arg>
- <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
- <arg choice="opt">>file.dot</arg>
+ <arg choice="plain">capability</arg>
+ <arg choice="opt" rep="repeat"><replaceable>CAPABILITY</replaceable></arg>
</cmdsynopsis>
-
<cmdsynopsis>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
- <arg choice="plain">unit-paths</arg>
+ <arg choice="plain">condition</arg>
+ <arg choice="plain"><replaceable>CONDITION</replaceable>…</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>systemd-analyze</command>
<command>systemd-analyze</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">calendar</arg>
- <arg choice="plain" rep="repeat"><replaceable>SPECS</replaceable></arg>
+ <arg choice="plain" rep="repeat"><replaceable>SPEC</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>systemd-analyze</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="plain">timestamp</arg>
+ <arg choice="plain" rep="repeat"><replaceable>TIMESTAMP</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>systemd-analyze</command>
initialization of one service might be slow simply because it waits for the initialization of another
service to complete. Also note: <command>systemd-analyze blame</command> doesn't display results for
services with <varname>Type=simple</varname>, because systemd considers such services to be started
- immediately, hence no measurement of the initialization delays can be done.</para>
+ immediately, hence no measurement of the initialization delays can be done. Also note that this command
+ only shows the time units took for starting up, it does not show how long unit jobs spent in the
+ execution queue. In particular it shows the time units spent in <literal>activating</literal> state,
+ which is not defined for units such as device units that transition directly from
+ <literal>inactive</literal> to <literal>active</literal>. This command hence gives an impression of the
+ performance of program code, but cannot accurately reflect latency introduced by waiting for
+ hardware and similar events.</para>
<example>
<title><command>Show which units took the most time during boot</command></title>
<replaceable>UNIT</replaceable>s or for the default target otherwise). The time after the unit is
active or started is printed after the "@" character. The time the unit takes to start is printed after
the "+" character. Note that the output might be misleading as the initialization of services might
- depend on socket activation and because of the parallel execution of units.</para>
+ depend on socket activation and because of the parallel execution of units. Also, similar to the
+ <command>blame</command> command, this only takes into account the time units spent in
+ <literal>activating</literal> state, and hence does not cover units that never went through an
+ <literal>activating</literal> state (such as device units that transition directly from
+ <literal>inactive</literal> to <literal>active</literal>). Moreover it does not show information on
+ jobs (and in particular not jobs that timed out).</para>
<example>
- <title><command>systemd-analyze time</command></title>
+ <title><command>systemd-analyze critical-chain</command></title>
<programlisting>$ systemd-analyze critical-chain
multi-user.target @47.820s
</example>
</refsect2>
- <refsect2>
- <title><command>systemd-analyze log-level [<replaceable>LEVEL</replaceable>]</command></title>
-
- <para><command>systemd-analyze log-level</command> prints the current log level of the
- <command>systemd</command> daemon. If an optional argument <replaceable>LEVEL</replaceable> is
- provided, then the command changes the current log level of the <command>systemd</command> daemon to
- <replaceable>LEVEL</replaceable> (accepts the same values as <option>--log-level=</option> described in
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
- </refsect2>
-
- <refsect2>
- <title><command>systemd-analyze log-target [<replaceable>TARGET</replaceable>]</command></title>
-
- <para><command>systemd-analyze log-target</command> prints the current log target of the
- <command>systemd</command> daemon. If an optional argument <replaceable>TARGET</replaceable> is
- provided, then the command changes the current log target of the <command>systemd</command> daemon to
- <replaceable>TARGET</replaceable> (accepts the same values as <option>--log-target=</option>, described
- in <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
- </refsect2>
-
- <refsect2>
- <title><command>systemd-analyze service-watchdogs [yes|no]</command></title>
-
- <para><command>systemd-analyze service-watchdogs</command> prints the current state of service runtime
- watchdogs of the <command>systemd</command> daemon. If an optional boolean argument is provided, then
- globally enables or disables the service runtime watchdogs (<option>WatchdogSec=</option>) and
- emergency actions (e.g. <option>OnFailure=</option> or <option>StartLimitAction=</option>); see
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
- The hardware watchdog is not affected by this setting.</para>
- </refsect2>
-
<refsect2>
<title><command>systemd-analyze dump</command></title>
</example>
<para>Note that this verb prints the list that is compiled into <command>systemd-analyze</command>
- itself, and does not comunicate with the running manager. Use
+ itself, and does not communicate with the running manager. Use
<programlisting>systemctl [--user] [--global] show -p UnitPath --value</programlisting>
to retrieve the actual list that the manager uses, with any empty directories omitted.</para>
</refsect2>
+ <refsect2>
+ <title><command>systemd-analyze exit-status <optional><replaceable>STATUS</replaceable>...</optional></command></title>
+
+ <para>This command prints a list of exit statuses along with their "class", i.e. the source of the
+ definition (one of <literal>glibc</literal>, <literal>systemd</literal>, <literal>LSB</literal>, or
+ <literal>BSD</literal>), see the Process Exit Codes section in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ If no additional arguments are specified, all known statuses are are shown. Otherwise, only the
+ definitions for the specified codes are shown.</para>
+
+ <example>
+ <title><command>Show some example exit status names</command></title>
+
+ <programlisting>$ systemd-analyze exit-status 0 1 {63..65}
+NAME STATUS CLASS
+SUCCESS 0 glibc
+FAILURE 1 glibc
+- 63 -
+USAGE 64 BSD
+DATAERR 65 BSD
+</programlisting>
+ </example>
+ </refsect2>
+
+ <refsect2>
+ <title><command>systemd-analyze capability <optional><replaceable>CAPABILITY</replaceable>...</optional></command></title>
+
+ <para>This command prints a list of Linux capabilities along with their numeric IDs. See <citerefentry
+ project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details. If no argument is specified the full list of capabilities known to the service manager and
+ the kernel is shown. Capabilities defined by the kernel but not known to the service manager are shown
+ as <literal>cap_???</literal>. Optionally, if arguments are specified they may refer to specific
+ cabilities by name or numeric ID, in which case only the indicated capabilities are shown in the
+ table.</para>
+
+ <example>
+ <title><command>Show some example capability names</command></title>
+
+ <programlisting>$ systemd-analyze capability 0 1 {30..32}
+NAME NUMBER
+cap_chown 0
+cap_dac_override 1
+cap_audit_control 30
+cap_setfcap 31
+cap_mac_override 32</programlisting>
+ </example>
+ </refsect2>
+
+ <refsect2>
+ <title><command>systemd-analyze condition <replaceable>CONDITION</replaceable>...</command></title>
+
+ <para>This command will evaluate <varname index="false">Condition*=...</varname> and
+ <varname index="false">Assert*=...</varname> assignments, and print their values, and
+ the resulting value of the combined condition set. See
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for a list of available conditions and asserts.</para>
+
+ <example>
+ <title>Evaluate conditions that check kernel versions</title>
+
+ <programlisting>$ systemd-analyze condition 'ConditionKernelVersion = ! <4.0' \
+ 'ConditionKernelVersion = >=5.1' \
+ 'ConditionACPower=|false' \
+ 'ConditionArchitecture=|!arm' \
+ 'AssertPathExists=/etc/os-release'
+test.service: AssertPathExists=/etc/os-release succeeded.
+Asserts succeeded.
+test.service: ConditionArchitecture=|!arm succeeded.
+test.service: ConditionACPower=|false failed.
+test.service: ConditionKernelVersion=>=5.1 succeeded.
+test.service: ConditionKernelVersion=!<4.0 succeeded.
+Conditions succeeded.</programlisting>
+ </example>
+ </refsect2>
+
<refsect2>
<title><command>systemd-analyze syscall-filter <optional><replaceable>SET</replaceable>...</optional></command></title>
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. By
default, only the next time the calendar expression will elapse is shown; use
<option>--iterations=</option> to show the specified number of next times the expression
- elapses.</para>
+ elapses. Each time the expression elapses forms a timestamp, see the <command>timestamp</command>
+ verb below.</para>
<example>
<title>Show leap days in the near future</title>
</example>
</refsect2>
+ <refsect2>
+ <title><command>systemd-analyze timestamp <replaceable>TIMESTAMP</replaceable>...</command></title>
+
+ <para>This command parses a timestamp (i.e. a single point in time) and outputs the normalized form and
+ the difference between this timestamp and now. The timestamp should adhere to the syntax documented in
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ section "PARSING TIMESTAMPS".</para>
+
+ <example>
+ <title>Show parsing of timestamps</title>
+
+ <programlisting>$ systemd-analyze timestamp yesterday now tomorrow
+ Original form: yesterday
+Normalized form: Mon 2019-05-20 00:00:00 CEST
+ (in UTC): Sun 2019-05-19 22:00:00 UTC
+ UNIX seconds: @15583032000
+ From now: 1 day 9h ago
+
+ Original form: now
+Normalized form: Tue 2019-05-21 09:48:39 CEST
+ (in UTC): Tue 2019-05-21 07:48:39 UTC
+ UNIX seconds: @1558424919.659757
+ From now: 43us ago
+
+ Original form: tomorrow
+Normalized form: Wed 2019-05-22 00:00:00 CEST
+ (in UTC): Tue 2019-05-21 22:00:00 UTC
+ UNIX seconds: @15584760000
+ From now: 14h left
+</programlisting>
+ </example>
+ </refsect2>
+
<refsect2>
<title><command>systemd-analyze timespan <replaceable>EXPRESSION</replaceable>...</command></title>
- <para>This command parses a time span and outputs the normalized form and the equivalent value in
- microseconds. The time span should adhere to the same syntax documented in
- <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
- Values without associated magnitudes are parsed as seconds.</para>
+ <para>This command parses a time span (i.e. a difference between two timestamps) and outputs the
+ normalized form and the equivalent value in microseconds. The time span should adhere to the syntax
+ documented in
+ <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ section "PARSING TIME SPANS". Values without units are parsed as seconds.</para>
<example>
<title>Show parsing of timespans</title>
<para>This command will load unit files and print warnings if any errors are detected. Files specified
on the command line will be loaded, but also any other units referenced by them. The full unit search
path is formed by combining the directories for all command line arguments, and the usual unit load
- paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be used to replace or
+ paths. The variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be used to replace or
augment the compiled in set of unit load paths; see
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). All
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. All
units files present in the directories containing the command line arguments will be used in preference
to the other paths.</para>
policy is not validated too.</para>
<example>
- <title>Analyze <filename noindex="true">systemd-logind.service</filename></title>
+ <title>Analyze <filename index="false">systemd-logind.service</filename></title>
<programlisting>$ systemd-analyze security --no-pager systemd-logind.service
NAME DESCRIPTION EXPOSURE
<command>dot</command> command (see above), this selects which
relationships are shown in the dependency graph. Both options
require a
- <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
pattern as an argument, which will be matched against the
left-hand and the right-hand, respectively, nodes of a
relationship.</para>
<varlistentry>
<term><option>--man=no</option></term>
- <listitem><para>Do not invoke man to verify the existence of
- man pages listed in <varname>Documentation=</varname>.
- </para></listitem>
+ <listitem><para>Do not invoke
+ <citerefentry project='man-pages'><refentrytitle>man</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ to verify the existence of man pages listed in <varname>Documentation=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
iterations the specified calendar expression will elapse next. Defaults to 1.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--base-time=<replaceable>TIMESTAMP</replaceable></option></term>
+
+ <listitem><para>When used with the <command>calendar</command> command, show next iterations relative
+ to the specified point in time. If not specified defaults to the current time.</para></listitem>
+ </varlistentry>
+
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />
projects / thirdparty / systemd.git / blobdiff