man/systemd-analyze.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-analyze"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-analyze</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-analyze</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-analyze</refname>
  24     <refpurpose>Analyze and debug system manager</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-analyze</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg>time</arg>
  32     </cmdsynopsis>
  33     <cmdsynopsis>
  34       <command>systemd-analyze</command>
  35       <arg choice="opt" rep="repeat">OPTIONS</arg>
  36       <arg choice="plain">blame</arg>
  37     </cmdsynopsis>
  38     <cmdsynopsis>
  39       <command>systemd-analyze</command>
  40       <arg choice="opt" rep="repeat">OPTIONS</arg>
  41       <arg choice="plain">critical-chain</arg>
  42       <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
  43     </cmdsynopsis>
  44     <cmdsynopsis>
  45       <command>systemd-analyze</command>
  46       <arg choice="opt" rep="repeat">OPTIONS</arg>
  47       <arg choice="plain">plot</arg>
  48       <arg choice="opt">&gt; file.svg</arg>
  49     </cmdsynopsis>
  50     <cmdsynopsis>
  51       <command>systemd-analyze</command>
  52       <arg choice="opt" rep="repeat">OPTIONS</arg>
  53       <arg choice="plain">dot</arg>
  54       <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
  55       <arg choice="opt">&gt; file.dot</arg>
  56     </cmdsynopsis>
  57     <cmdsynopsis>
  58       <command>systemd-analyze</command>
  59       <arg choice="opt" rep="repeat">OPTIONS</arg>
  60       <arg choice="plain">dump</arg>
  61     </cmdsynopsis>
  62     <cmdsynopsis>
  63       <command>systemd-analyze</command>
  64       <arg choice="opt" rep="repeat">OPTIONS</arg>
  65       <arg choice="plain">cat-config</arg>
  66       <arg choice="plain" rep="repeat"><replaceable>NAME</replaceable>|<replaceable>PATH</replaceable></arg>
  67     </cmdsynopsis>
  68     <cmdsynopsis>
  69       <command>systemd-analyze</command>
  70       <arg choice="opt" rep="repeat">OPTIONS</arg>
  71       <arg choice="plain">unit-paths</arg>
  72     </cmdsynopsis>
  73     <cmdsynopsis>
  74       <command>systemd-analyze</command>
  75       <arg choice="opt" rep="repeat">OPTIONS</arg>
  76       <arg choice="plain">log-level</arg>
  77       <arg choice="opt"><replaceable>LEVEL</replaceable></arg>
  78     </cmdsynopsis>
  79     <cmdsynopsis>
  80       <command>systemd-analyze</command>
  81       <arg choice="opt" rep="repeat">OPTIONS</arg>
  82       <arg choice="plain">log-target</arg>
  83       <arg choice="opt"><replaceable>TARGET</replaceable></arg>
  84     </cmdsynopsis>
  85     <cmdsynopsis>
  86       <command>systemd-analyze</command>
  87       <arg choice="opt" rep="repeat">OPTIONS</arg>
  88       <arg choice="plain">syscall-filter</arg>
  89       <arg choice="opt"><replaceable>SET</replaceable>…</arg>
  90     </cmdsynopsis>
  91     <cmdsynopsis>
  92       <command>systemd-analyze</command>
  93       <arg choice="opt" rep="repeat">OPTIONS</arg>
  94       <arg choice="plain">verify</arg>
  95       <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg>
  96     </cmdsynopsis>
  97     <cmdsynopsis>
  98       <command>systemd-analyze</command>
  99       <arg choice="opt" rep="repeat">OPTIONS</arg>
 100       <arg choice="plain">calendar</arg>
 101       <arg choice="plain" rep="repeat"><replaceable>SPECS</replaceable></arg>
 102     </cmdsynopsis>
 103     <cmdsynopsis>
 104       <command>systemd-analyze</command>
 105       <arg choice="opt" rep="repeat">OPTIONS</arg>
 106       <arg choice="plain">service-watchdogs</arg>
 107       <arg choice="opt"><replaceable>BOOL</replaceable></arg>
 108     </cmdsynopsis>
 109     <cmdsynopsis>
 110       <command>systemd-analyze</command>
 111       <arg choice="opt" rep="repeat">OPTIONS</arg>
 112       <arg choice="plain">timespan</arg>
 113       <arg choice="plain" rep="repeat"><replaceable>SPAN</replaceable></arg>
 114     </cmdsynopsis>
 115   </refsynopsisdiv>
 116
 117   <refsect1>
 118     <title>Description</title>
 119
 120     <para><command>systemd-analyze</command> may be used to determine
 121     system boot-up performance statistics and retrieve other state and
 122     tracing information from the system and service manager, and to
 123     verify the correctness of unit files. It is also used to access
 124     special functions useful for advanced system manager debugging.</para>
 125
 126     <para><command>systemd-analyze time</command> prints the time
 127     spent in the kernel before userspace has been reached, the time
 128     spent in the initial RAM disk (initrd) before normal system
 129     userspace has been reached, and the time normal system userspace
 130     took to initialize. Note that these measurements simply measure
 131     the time passed up to the point where all system services have
 132     been spawned, but not necessarily until they fully finished
 133     initialization or the disk is idle.</para>
 134
 135     <para><command>systemd-analyze blame</command> prints a list of
 136     all running units, ordered by the time they took to initialize.
 137     This information may be used to optimize boot-up times. Note that
 138     the output might be misleading as the initialization of one
 139     service might be slow simply because it waits for the
 140     initialization of another service to complete.
 141     Also note: <command>systemd-analyze blame</command> doesn't display
 142     results for services with <varname>Type=simple</varname>,
 143     because systemd considers such services to be started immediately,
 144     hence no measurement of the initialization delays can be done.</para>
 145
 146     <para><command>systemd-analyze critical-chain
 147     [<replaceable>UNIT…</replaceable>]</command> prints a tree of
 148     the time-critical chain of units (for each of the specified
 149     <replaceable>UNIT</replaceable>s or for the default target
 150     otherwise). The time after the unit is active or started is
 151     printed after the "@" character. The time the unit takes to start
 152     is printed after the "+" character. Note that the output might be
 153     misleading as the initialization of one service might depend on
 154     socket activation and because of the parallel execution of
 155     units.</para>
 156
 157     <para><command>systemd-analyze plot</command> prints an SVG
 158     graphic detailing which system services have been started at what
 159     time, highlighting the time they spent on initialization.</para>
 160
 161     <para><command>systemd-analyze dot</command> generates textual
 162     dependency graph description in dot format for further processing
 163     with the GraphViz
 164     <citerefentry project='die-net'><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 165     tool. Use a command line like <command>systemd-analyze dot | dot
 166     -Tsvg > systemd.svg</command> to generate a graphical dependency
 167     tree. Unless <option>--order</option> or
 168     <option>--require</option> is passed, the generated graph will
 169     show both ordering and requirement dependencies. Optional pattern
 170     globbing style specifications (e.g. <filename>*.target</filename>)
 171     may be given at the end. A unit dependency is included in the
 172     graph if any of these patterns match either the origin or
 173     destination node.</para>
 174
 175     <para><command>systemd-analyze dump</command> outputs a (usually
 176     very long) human-readable serialization of the complete server
 177     state. Its format is subject to change without notice and should
 178     not be parsed by applications.</para>
 179
 180     <para><command>systemd-analyze cat-config</command> is similar
 181     to <command>systemctl cat</command>, but operates on config files.
 182     It will copy the contents of a config file and any drop-ins to standard
 183     output, using the usual systemd set of directories and rules for
 184     precedence. Each argument must be either an absolute path including
 185     the prefix (such as <filename>/etc/systemd/logind.conf</filename> or
 186     <filename>/usr/lib/systemd/logind.conf</filename>), or a name
 187     relative to the prefix (such as <filename>systemd/logind.conf</filename>).
 188     </para>
 189
 190     <example>
 191       <title>Showing logind configuration</title>
 192       <programlisting>$ systemd-analyze cat-config systemd/logind.conf
 193 # /etc/systemd/logind.conf
 194 ...
 195 [Login]
 196 NAutoVTs=8
 197 ...
 198
 199 # /usr/lib/systemd/logind.conf.d/20-test.conf
 200 ... some override from another package
 201
 202 # /etc/systemd/logind.conf.d/50-override.conf
 203 ... some administrator override
 204       </programlisting>
 205     </example>
 206
 207     <para><command>systemd-analyze unit-paths</command> outputs a list of all
 208     directories from which unit files, <filename>.d</filename> overrides, and
 209     <filename>.wants</filename>, <filename>.requires</filename> symlinks may be
 210     loaded. Combine with <option>--user</option> to retrieve the list for the user
 211     manager instance, and <option>--global</option> for the global configuration of
 212     user manager instances. Note that this verb prints the list that is compiled into
 213     <command>systemd-analyze</command> itself, and does not comunicate with the
 214     running manager. Use
 215     <programlisting>systemctl [--user] [--global] show -p UnitPath --value</programlisting>
 216     to retrieve the actual list that the manager uses, with any empty directories
 217     omitted.</para>
 218
 219     <para><command>systemd-analyze log-level</command>
 220     prints the current log level of the <command>systemd</command> daemon.
 221     If an optional argument <replaceable>LEVEL</replaceable> is provided, then the command changes the current log
 222     level of the <command>systemd</command> daemon to <replaceable>LEVEL</replaceable> (accepts the same values as
 223     <option>--log-level=</option> described in
 224     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 225
 226     <para><command>systemd-analyze log-target</command>
 227     prints the current log target of the <command>systemd</command> daemon.
 228     If an optional argument <replaceable>TARGET</replaceable> is provided, then the command changes the current log
 229     target of the <command>systemd</command> daemon to <replaceable>TARGET</replaceable> (accepts the same values as
 230     <option>--log-target=</option>, described in
 231     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 232
 233     <para><command>systemd-analyze syscall-filter <optional><replaceable>SET</replaceable>…</optional></command>
 234     will list system calls contained in the specified system call set <replaceable>SET</replaceable>,
 235     or all known sets if no sets are specified. Argument <replaceable>SET</replaceable> must include
 236     the <literal>@</literal> prefix.</para>
 237
 238     <para><command>systemd-analyze verify</command> will load unit files and print
 239     warnings if any errors are detected. Files specified on the command line will be
 240     loaded, but also any other units referenced by them. The full unit search path is
 241     formed by combining the directories for all command line arguments, and the usual unit
 242     load paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be
 243     used to replace or augment the compiled in set of unit load paths; see
 244     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 245     All units files present in the directories containing the command line arguments will
 246     be used in preference to the other paths.</para>
 247
 248     <para><command>systemd-analyze calendar</command> will parse and normalize repetitive calendar time events, and
 249     will calculate when they will elapse next. This takes the same input as the <varname>OnCalendar=</varname> setting
 250     in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, following the
 251     syntax described in
 252     <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 253
 254     <para><command>systemd-analyze service-watchdogs</command>
 255     prints the current state of service runtime watchdogs of the <command>systemd</command> daemon.
 256     If an optional boolean argument is provided, then globally enables or disables the service
 257     runtime watchdogs (<option>WatchdogSec=</option>) and emergency actions (e.g.
 258     <option>OnFailure=</option> or <option>StartLimitAction=</option>); see
 259     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 260     The hardware watchdog is not affected by this setting.</para>
 261
 262     <para><command>systemd-analyze timespan</command> parses a time span and outputs the equivalent value in microseconds, and as a reformatted timespan.
 263     The time span should adhere to the same syntax documented in <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 264     Values without associated magnitudes are parsed as seconds.</para>
 265
 266     <para>If no command is passed, <command>systemd-analyze
 267     time</command> is implied.</para>
 268
 269   </refsect1>
 270
 271   <refsect1>
 272     <title>Options</title>
 273
 274     <para>The following options are understood:</para>
 275
 276     <variablelist>
 277       <varlistentry>
 278         <term><option>--system</option></term>
 279
 280         <listitem><para>Operates on the system systemd instance. This
 281         is the implied default.</para></listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><option>--user</option></term>
 286
 287         <listitem><para>Operates on the user systemd
 288         instance.</para></listitem>
 289       </varlistentry>
 290
 291       <varlistentry>
 292         <term><option>--global</option></term>
 293
 294         <listitem><para>Operates on the system-wide configuration for
 295         user systemd instance.</para></listitem>
 296       </varlistentry>
 297
 298       <varlistentry>
 299         <term><option>--order</option></term>
 300         <term><option>--require</option></term>
 301
 302         <listitem><para>When used in conjunction with the
 303         <command>dot</command> command (see above), selects which
 304         dependencies are shown in the dependency graph. If
 305         <option>--order</option> is passed, only dependencies of type
 306         <varname>After=</varname> or <varname>Before=</varname> are
 307         shown. If <option>--require</option> is passed, only
 308         dependencies of type <varname>Requires=</varname>,
 309         <varname>Requisite=</varname>,
 310         <varname>Wants=</varname> and <varname>Conflicts=</varname>
 311         are shown. If neither is passed, this shows dependencies of
 312         all these types.</para></listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term><option>--from-pattern=</option></term>
 317         <term><option>--to-pattern=</option></term>
 318
 319         <listitem><para>When used in conjunction with the
 320         <command>dot</command> command (see above), this selects which
 321         relationships are shown in the dependency graph. Both options
 322         require a
 323         <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 324         pattern as an argument, which will be matched against the
 325         left-hand and the right-hand, respectively, nodes of a
 326         relationship.</para>
 327
 328         <para>Each of these can be used more than once, in which case
 329         the unit name must match one of the values. When tests for
 330         both sides of the relation are present, a relation must pass
 331         both tests to be shown. When patterns are also specified as
 332         positional arguments, they must match at least one side of the
 333         relation. In other words, patterns specified with those two
 334         options will trim the list of edges matched by the positional
 335         arguments, if any are given, and fully determine the list of
 336         edges shown otherwise.</para></listitem>
 337       </varlistentry>
 338
 339       <varlistentry>
 340         <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
 341
 342         <listitem><para>When used in conjunction with the
 343         <command>critical-chain</command> command (see above), also
 344         show units, which finished <replaceable>timespan</replaceable>
 345         earlier, than the latest unit in the same level. The unit of
 346         <replaceable>timespan</replaceable> is seconds unless
 347         specified with a different unit, e.g.
 348         "50ms".</para></listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><option>--man=no</option></term>
 353
 354         <listitem><para>Do not invoke man to verify the existence of
 355         man pages listed in <varname>Documentation=</varname>.
 356         </para></listitem>
 357       </varlistentry>
 358
 359       <varlistentry>
 360         <term><option>--generators</option></term>
 361
 362         <listitem><para>Invoke unit generators, see
 363         <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 364         Some generators require root privileges. Under a normal user, running with
 365         generators enabled will generally result in some warnings.</para></listitem>
 366       </varlistentry>
 367
 368       <varlistentry>
 369         <term><option>--root=<replaceable>PATH</replaceable></option></term>
 370
 371         <listitem><para>With <command>cat-files</command>, show config files underneath
 372         the specified root path <replaceable>PATH</replaceable>.</para></listitem>
 373       </varlistentry>
 374
 375       <xi:include href="user-system-options.xml" xpointer="host" />
 376       <xi:include href="user-system-options.xml" xpointer="machine" />
 377
 378       <xi:include href="standard-options.xml" xpointer="help" />
 379       <xi:include href="standard-options.xml" xpointer="version" />
 380       <xi:include href="standard-options.xml" xpointer="no-pager" />
 381     </variablelist>
 382
 383   </refsect1>
 384
 385   <refsect1>
 386     <title>Exit status</title>
 387
 388     <para>On success, 0 is returned, a non-zero failure code
 389     otherwise.</para>
 390   </refsect1>
 391
 392   <refsect1>
 393     <title>Examples for <command>dot</command></title>
 394
 395     <example>
 396       <title>Plots all dependencies of any unit whose name starts with
 397       <literal>avahi-daemon</literal></title>
 398
 399       <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
 400 $ eog avahi.svg</programlisting>
 401     </example>
 402
 403     <example>
 404       <title>Plots the dependencies between all known target units</title>
 405
 406       <programlisting>$ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
 407 $ eog targets.svg</programlisting>
 408     </example>
 409   </refsect1>
 410
 411   <refsect1>
 412     <title>Examples for <command>verify</command></title>
 413
 414     <para>The following errors are currently detected:</para>
 415     <itemizedlist>
 416       <listitem><para>unknown sections and directives,
 417       </para></listitem>
 418
 419       <listitem><para>missing dependencies which are required to start
 420       the given unit,</para></listitem>
 421
 422       <listitem><para>man pages listed in
 423       <varname>Documentation=</varname> which are not found in the
 424       system,</para></listitem>
 425
 426       <listitem><para>commands listed in <varname>ExecStart=</varname>
 427       and similar which are not found in the system or not
 428       executable.</para></listitem>
 429     </itemizedlist>
 430
 431     <example>
 432       <title>Misspelt directives</title>
 433
 434       <programlisting>$ cat ./user.slice
 435 [Unit]
 436 WhatIsThis=11
 437 Documentation=man:nosuchfile(1)
 438 Requires=different.service
 439
 440 [Service]
 441 Description=x
 442
 443 $ systemd-analyze verify ./user.slice
 444 [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit'
 445 [./user.slice:13] Unknown section 'Service'. Ignoring.
 446 Error: org.freedesktop.systemd1.LoadFailed:
 447    Unit different.service failed to load:
 448    No such file or directory.
 449 Failed to create user.slice/start: Invalid argument
 450 user.slice: man nosuchfile(1) command failed with code 16
 451       </programlisting>
 452     </example>
 453
 454     <example>
 455       <title>Missing service units</title>
 456
 457       <programlisting>$ tail ./a.socket ./b.socket
 458 ==> ./a.socket &lt;==
 459 [Socket]
 460 ListenStream=100
 461
 462 ==> ./b.socket &lt;==
 463 [Socket]
 464 ListenStream=100
 465 Accept=yes
 466
 467 $ systemd-analyze verify ./a.socket ./b.socket
 468 Service a.service not loaded, a.socket cannot be started.
 469 Service b@0.service not loaded, b.socket cannot be started.
 470       </programlisting>
 471     </example>
 472   </refsect1>
 473
 474   <xi:include href="less-variables.xml" />
 475
 476   <refsect1>
 477     <title>See Also</title>
 478     <para>
 479       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 480       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 481     </para>
 482   </refsect1>
 483
 484 </refentry>