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