man/systemd-analyze.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="systemd-analyze"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-analyze</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-analyze</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-analyze</refname>
  21     <refpurpose>Analyze and debug system manager</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>systemd-analyze</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg>time</arg>
  29     </cmdsynopsis>
  30     <cmdsynopsis>
  31       <command>systemd-analyze</command>
  32       <arg choice="opt" rep="repeat">OPTIONS</arg>
  33       <arg choice="plain">blame</arg>
  34     </cmdsynopsis>
  35     <cmdsynopsis>
  36       <command>systemd-analyze</command>
  37       <arg choice="opt" rep="repeat">OPTIONS</arg>
  38       <arg choice="plain">critical-chain</arg>
  39       <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
  40     </cmdsynopsis>
  41
  42     <cmdsynopsis>
  43       <command>systemd-analyze</command>
  44       <arg choice="opt" rep="repeat">OPTIONS</arg>
  45       <arg choice="plain">log-level</arg>
  46       <arg choice="opt"><replaceable>LEVEL</replaceable></arg>
  47     </cmdsynopsis>
  48     <cmdsynopsis>
  49       <command>systemd-analyze</command>
  50       <arg choice="opt" rep="repeat">OPTIONS</arg>
  51       <arg choice="plain">log-target</arg>
  52       <arg choice="opt"><replaceable>TARGET</replaceable></arg>
  53     </cmdsynopsis>
  54     <cmdsynopsis>
  55       <command>systemd-analyze</command>
  56       <arg choice="opt" rep="repeat">OPTIONS</arg>
  57       <arg choice="plain">service-watchdogs</arg>
  58       <arg choice="opt"><replaceable>BOOL</replaceable></arg>
  59     </cmdsynopsis>
  60
  61     <cmdsynopsis>
  62       <command>systemd-analyze</command>
  63       <arg choice="opt" rep="repeat">OPTIONS</arg>
  64       <arg choice="plain">dump</arg>
  65     </cmdsynopsis>
  66
  67     <cmdsynopsis>
  68       <command>systemd-analyze</command>
  69       <arg choice="opt" rep="repeat">OPTIONS</arg>
  70       <arg choice="plain">plot</arg>
  71       <arg choice="opt">>file.svg</arg>
  72     </cmdsynopsis>
  73     <cmdsynopsis>
  74       <command>systemd-analyze</command>
  75       <arg choice="opt" rep="repeat">OPTIONS</arg>
  76       <arg choice="plain">dot</arg>
  77       <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
  78       <arg choice="opt">>file.dot</arg>
  79     </cmdsynopsis>
  80
  81     <cmdsynopsis>
  82       <command>systemd-analyze</command>
  83       <arg choice="opt" rep="repeat">OPTIONS</arg>
  84       <arg choice="plain">unit-paths</arg>
  85     </cmdsynopsis>
  86     <cmdsynopsis>
  87       <command>systemd-analyze</command>
  88       <arg choice="opt" rep="repeat">OPTIONS</arg>
  89       <arg choice="plain">exit-status</arg>
  90       <arg choice="opt" rep="repeat"><replaceable>STATUS</replaceable></arg>
  91     </cmdsynopsis>
  92     <cmdsynopsis>
  93       <command>systemd-analyze</command>
  94       <arg choice="opt" rep="repeat">OPTIONS</arg>
  95       <arg choice="plain">condition</arg>
  96       <arg choice="plain"><replaceable>CONDITION</replaceable>…</arg>
  97     </cmdsynopsis>
  98     <cmdsynopsis>
  99       <command>systemd-analyze</command>
 100       <arg choice="opt" rep="repeat">OPTIONS</arg>
 101       <arg choice="plain">syscall-filter</arg>
 102       <arg choice="opt"><replaceable>SET</replaceable>…</arg>
 103     </cmdsynopsis>
 104     <cmdsynopsis>
 105       <command>systemd-analyze</command>
 106       <arg choice="opt" rep="repeat">OPTIONS</arg>
 107       <arg choice="plain">calendar</arg>
 108       <arg choice="plain" rep="repeat"><replaceable>SPEC</replaceable></arg>
 109     </cmdsynopsis>
 110     <cmdsynopsis>
 111       <command>systemd-analyze</command>
 112       <arg choice="opt" rep="repeat">OPTIONS</arg>
 113       <arg choice="plain">timestamp</arg>
 114       <arg choice="plain" rep="repeat"><replaceable>TIMESTAMP</replaceable></arg>
 115     </cmdsynopsis>
 116     <cmdsynopsis>
 117       <command>systemd-analyze</command>
 118       <arg choice="opt" rep="repeat">OPTIONS</arg>
 119       <arg choice="plain">timespan</arg>
 120       <arg choice="plain" rep="repeat"><replaceable>SPAN</replaceable></arg>
 121     </cmdsynopsis>
 122     <cmdsynopsis>
 123       <command>systemd-analyze</command>
 124       <arg choice="opt" rep="repeat">OPTIONS</arg>
 125       <arg choice="plain">cat-config</arg>
 126       <arg choice="plain" rep="repeat"><replaceable>NAME</replaceable>|<replaceable>PATH</replaceable></arg>
 127     </cmdsynopsis>
 128     <cmdsynopsis>
 129       <command>systemd-analyze</command>
 130       <arg choice="opt" rep="repeat">OPTIONS</arg>
 131       <arg choice="plain">verify</arg>
 132       <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
 133     </cmdsynopsis>
 134     <cmdsynopsis>
 135       <command>systemd-analyze</command>
 136       <arg choice="opt" rep="repeat">OPTIONS</arg>
 137       <arg choice="plain">security</arg>
 138       <arg choice="plain" rep="repeat"><replaceable>UNIT</replaceable></arg>
 139     </cmdsynopsis>
 140   </refsynopsisdiv>
 141
 142   <refsect1>
 143     <title>Description</title>
 144
 145     <para><command>systemd-analyze</command> may be used to determine
 146     system boot-up performance statistics and retrieve other state and
 147     tracing information from the system and service manager, and to
 148     verify the correctness of unit files. It is also used to access
 149     special functions useful for advanced system manager debugging.</para>
 150
 151     <para>If no command is passed, <command>systemd-analyze
 152     time</command> is implied.</para>
 153
 154     <refsect2>
 155       <title><command>systemd-analyze time</command></title>
 156
 157       <para>This command prints the time spent in the kernel before userspace has been reached, the time
 158       spent in the initial RAM disk (initrd) before normal system userspace has been reached, and the time
 159       normal system userspace took to initialize. Note that these measurements simply measure the time passed
 160       up to the point where all system services have been spawned, but not necessarily until they fully
 161       finished initialization or the disk is idle.</para>
 162
 163       <example>
 164         <title><command>Show how long the boot took</command></title>
 165
 166         <programlisting># in a container
 167 $ systemd-analyze time
 168 Startup finished in 296ms (userspace)
 169 multi-user.target reached after 275ms in userspace
 170
 171 # on a real machine
 172 $ systemd-analyze time
 173 Startup finished in 2.584s (kernel) + 19.176s (initrd) + 47.847s (userspace) = 1min 9.608s
 174 multi-user.target reached after 47.820s in userspace
 175 </programlisting>
 176       </example>
 177     </refsect2>
 178
 179     <refsect2>
 180       <title><command>systemd-analyze blame</command></title>
 181
 182       <para>This command prints a list of all running units, ordered by the time they took to initialize.
 183       This information may be used to optimize boot-up times. Note that the output might be misleading as the
 184       initialization of one service might be slow simply because it waits for the initialization of another
 185       service to complete.  Also note: <command>systemd-analyze blame</command> doesn't display results for
 186       services with <varname>Type=simple</varname>, because systemd considers such services to be started
 187       immediately, hence no measurement of the initialization delays can be done. Also note that this command
 188       only shows the time units took for starting up, it does not show how long unit jobs spent in the
 189       execution queue. In particular it shows the time units spent in <literal>activating</literal> state,
 190       which is not defined for units such as device units that transition directly from
 191       <literal>inactive</literal> to <literal>active</literal>. This command hence gives an impression of the
 192       performance of program code, but cannot accurately reflect latency introduced by waiting for
 193       hardware and similar events.</para>
 194
 195       <example>
 196         <title><command>Show which units took the most time during boot</command></title>
 197
 198         <programlisting>$ systemd-analyze blame
 199          32.875s pmlogger.service
 200          20.905s systemd-networkd-wait-online.service
 201          13.299s dev-vda1.device
 202          ...
 203             23ms sysroot.mount
 204             11ms initrd-udevadm-cleanup-db.service
 205              3ms sys-kernel-config.mount
 206         </programlisting>
 207       </example>
 208     </refsect2>
 209
 210     <refsect2>
 211       <title><command>systemd-analyze critical-chain <optional><replaceable>UNIT</replaceable>...</optional></command></title>
 212
 213       <para>This command prints a tree of the time-critical chain of units (for each of the specified
 214       <replaceable>UNIT</replaceable>s or for the default target otherwise). The time after the unit is
 215       active or started is printed after the "@" character. The time the unit takes to start is printed after
 216       the "+" character. Note that the output might be misleading as the initialization of services might
 217       depend on socket activation and because of the parallel execution of units. Also, similar to the
 218       <command>blame</command> command, this only takes into account the time units spent in
 219       <literal>activating</literal> state, and hence does not cover units that never went through an
 220       <literal>activating</literal> state (such as device units that transition directly from
 221       <literal>inactive</literal> to <literal>active</literal>). Moreover it does not show information on
 222       jobs (and in particular not jobs that timed out).</para>
 223
 224       <example>
 225         <title><command>systemd-analyze time</command></title>
 226
 227       <programlisting>$ systemd-analyze critical-chain
 228 multi-user.target @47.820s
 229 └─pmie.service @35.968s +548ms
 230   └─pmcd.service @33.715s +2.247s
 231     └─network-online.target @33.712s
 232       └─systemd-networkd-wait-online.service @12.804s +20.905s
 233         └─systemd-networkd.service @11.109s +1.690s
 234           └─systemd-udevd.service @9.201s +1.904s
 235             └─systemd-tmpfiles-setup-dev.service @7.306s +1.776s
 236               └─kmod-static-nodes.service @6.976s +177ms
 237                 └─systemd-journald.socket
 238                   └─system.slice
 239                     └─-.slice
 240 </programlisting>
 241       </example>
 242     </refsect2>
 243
 244     <refsect2>
 245       <title><command>systemd-analyze log-level [<replaceable>LEVEL</replaceable>]</command></title>
 246
 247       <para><command>systemd-analyze log-level</command> prints the current log level of the
 248       <command>systemd</command> daemon.  If an optional argument <replaceable>LEVEL</replaceable> is
 249       provided, then the command changes the current log level of the <command>systemd</command> daemon to
 250       <replaceable>LEVEL</replaceable> (accepts the same values as <option>--log-level=</option> described in
 251       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 252     </refsect2>
 253
 254     <refsect2>
 255       <title><command>systemd-analyze log-target [<replaceable>TARGET</replaceable>]</command></title>
 256
 257       <para><command>systemd-analyze log-target</command> prints the current log target of the
 258       <command>systemd</command> daemon.  If an optional argument <replaceable>TARGET</replaceable> is
 259       provided, then the command changes the current log target of the <command>systemd</command> daemon to
 260       <replaceable>TARGET</replaceable> (accepts the same values as <option>--log-target=</option>, described
 261       in <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 262     </refsect2>
 263
 264     <refsect2>
 265       <title><command>systemd-analyze service-watchdogs [yes|no]</command></title>
 266
 267       <para><command>systemd-analyze service-watchdogs</command> prints the current state of service runtime
 268       watchdogs of the <command>systemd</command> daemon. If an optional boolean argument is provided, then
 269       globally enables or disables the service runtime watchdogs (<option>WatchdogSec=</option>) and
 270       emergency actions (e.g.  <option>OnFailure=</option> or <option>StartLimitAction=</option>); see
 271       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 272       The hardware watchdog is not affected by this setting.</para>
 273     </refsect2>
 274
 275     <refsect2>
 276       <title><command>systemd-analyze dump</command></title>
 277
 278       <para>This command outputs a (usually very long) human-readable serialization of the complete server
 279       state. Its format is subject to change without notice and should not be parsed by applications.</para>
 280
 281       <example>
 282         <title>Show the internal state of user manager</title>
 283
 284         <programlisting>$ systemd-analyze --user dump
 285 Timestamp userspace: Thu 2019-03-14 23:28:07 CET
 286 Timestamp finish: Thu 2019-03-14 23:28:07 CET
 287 Timestamp generators-start: Thu 2019-03-14 23:28:07 CET
 288 Timestamp generators-finish: Thu 2019-03-14 23:28:07 CET
 289 Timestamp units-load-start: Thu 2019-03-14 23:28:07 CET
 290 Timestamp units-load-finish: Thu 2019-03-14 23:28:07 CET
 291 -> Unit proc-timer_list.mount:
 292         Description: /proc/timer_list
 293         ...
 294 -> Unit default.target:
 295         Description: Main user target
 296 ...
 297 </programlisting>
 298       </example>
 299     </refsect2>
 300
 301     <refsect2>
 302       <title><command>systemd-analyze plot</command></title>
 303
 304       <para>This command prints an SVG graphic detailing which system services have been started at what
 305       time, highlighting the time they spent on initialization.</para>
 306
 307       <example>
 308         <title><command>Plot a bootchart</command></title>
 309
 310         <programlisting>$ systemd-analyze plot >bootup.svg
 311 $ eog bootup.svg&amp;
 312 </programlisting>
 313       </example>
 314     </refsect2>
 315
 316     <refsect2>
 317       <title><command>systemd-analyze dot [<replaceable>pattern</replaceable>...]</command></title>
 318
 319       <para>This command generates textual dependency graph description in dot format for further processing
 320       with the GraphViz
 321       <citerefentry project='die-net'><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 322       tool. Use a command line like <command>systemd-analyze dot | dot -Tsvg >systemd.svg</command> to
 323       generate a graphical dependency tree. Unless <option>--order</option> or <option>--require</option> is
 324       passed, the generated graph will show both ordering and requirement dependencies. Optional pattern
 325       globbing style specifications (e.g. <filename>*.target</filename>) may be given at the end. A unit
 326       dependency is included in the graph if any of these patterns match either the origin or destination
 327       node.</para>
 328
 329       <example>
 330         <title>Plot all dependencies of any unit whose name starts with <literal>avahi-daemon</literal>
 331         </title>
 332
 333         <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg >avahi.svg
 334 $ eog avahi.svg</programlisting>
 335       </example>
 336
 337       <example>
 338         <title>Plot the dependencies between all known target units</title>
 339
 340         <programlisting>$ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' \
 341       | dot -Tsvg >targets.svg
 342 $ eog targets.svg</programlisting>
 343       </example>
 344     </refsect2>
 345
 346     <refsect2>
 347       <title><command>systemd-analyze unit-paths</command></title>
 348
 349       <para>This command outputs a list of all directories from which unit files, <filename>.d</filename>
 350       overrides, and <filename>.wants</filename>, <filename>.requires</filename> symlinks may be
 351       loaded. Combine with <option>--user</option> to retrieve the list for the user manager instance, and
 352       <option>--global</option> for the global configuration of user manager instances.</para>
 353
 354       <example>
 355         <title><command>Show all paths for generated units</command></title>
 356
 357         <programlisting>$ systemd-analyze unit-paths | grep '^/run'
 358 /run/systemd/system.control
 359 /run/systemd/transient
 360 /run/systemd/generator.early
 361 /run/systemd/system
 362 /run/systemd/system.attached
 363 /run/systemd/generator
 364 /run/systemd/generator.late
 365 </programlisting>
 366       </example>
 367
 368       <para>Note that this verb prints the list that is compiled into <command>systemd-analyze</command>
 369       itself, and does not communicate with the running manager. Use
 370       <programlisting>systemctl [--user] [--global] show -p UnitPath --value</programlisting>
 371       to retrieve the actual list that the manager uses, with any empty directories omitted.</para>
 372     </refsect2>
 373
 374     <refsect2>
 375       <title><command>systemd-analyze exit-status <optional><replaceable>STATUS</replaceable>...</optional></command></title>
 376
 377       <para>This command prints a list of exit statuses along with their "class", i.e. the source of the
 378       definition (one of <literal>glibc</literal>, <literal>systemd</literal>, <literal>LSB</literal>, or
 379       <literal>BSD</literal>), see the Process Exit Codes section in
 380       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 381       If no additional arguments are specified, all known statuses are are shown. Otherwise, only the
 382       definitions for the specified codes are shown.</para>
 383
 384       <example>
 385         <title><command>Show some example exit status names</command></title>
 386
 387         <programlisting>$ systemd-analyze exit-status 0 1 {63..65}
 388 NAME    STATUS CLASS
 389 SUCCESS 0      glibc
 390 FAILURE 1      glibc
 391 -       63     -
 392 USAGE   64     BSD
 393 DATAERR 65     BSD
 394 </programlisting>
 395       </example>
 396     </refsect2>
 397
 398     <refsect2>
 399       <title><command>systemd-analyze condition <replaceable>CONDITION</replaceable>...</command></title>
 400
 401       <para>This command will evaluate <varname noindex='true'>Condition*=...</varname> and
 402       <varname noindex='true'>Assert*=...</varname> assignments, and print their values, and
 403       the resulting value of the combined condition set. See
 404       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 405       for a list of available conditions and asserts.</para>
 406
 407       <example>
 408         <title>Evaluate conditions that check kernel versions</title>
 409
 410         <programlisting>$ systemd-analyze condition 'ConditionKernelVersion = ! &lt;4.0' \
 411         'ConditionKernelVersion = &gt;=5.1' \
 412         'ConditionACPower=|false' \
 413         'ConditionArchitecture=|!arm' \
 414         'AssertPathExists=/etc/os-release'
 415 test.service: AssertPathExists=/etc/os-release succeeded.
 416 Asserts succeeded.
 417 test.service: ConditionArchitecture=|!arm succeeded.
 418 test.service: ConditionACPower=|false failed.
 419 test.service: ConditionKernelVersion=&gt;=5.1 succeeded.
 420 test.service: ConditionKernelVersion=!&lt;4.0 succeeded.
 421 Conditions succeeded.</programlisting>
 422       </example>
 423     </refsect2>
 424
 425     <refsect2>
 426       <title><command>systemd-analyze syscall-filter <optional><replaceable>SET</replaceable>...</optional></command></title>
 427
 428       <para>This command will list system calls contained in the specified system call set
 429       <replaceable>SET</replaceable>, or all known sets if no sets are specified. Argument
 430       <replaceable>SET</replaceable> must include the <literal>@</literal> prefix.</para>
 431     </refsect2>
 432
 433     <refsect2>
 434       <title><command>systemd-analyze calendar <replaceable>EXPRESSION</replaceable>...</command></title>
 435
 436       <para>This command will parse and normalize repetitive calendar time events, and will calculate when
 437       they elapse next. This takes the same input as the <varname>OnCalendar=</varname> setting in
 438       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 439       following the syntax described in
 440       <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. By
 441       default, only the next time the calendar expression will elapse is shown; use
 442       <option>--iterations=</option> to show the specified number of next times the expression
 443       elapses. Each time the expression elapses forms a timestamp, see the <command>timestamp</command>
 444       verb below.</para>
 445
 446       <example>
 447         <title>Show leap days in the near future</title>
 448
 449         <programlisting>$ systemd-analyze calendar --iterations=5 '*-2-29 0:0:0'
 450   Original form: *-2-29 0:0:0
 451 Normalized form: *-02-29 00:00:00
 452     Next elapse: Sat 2020-02-29 00:00:00 UTC
 453        From now: 11 months 15 days left
 454        Iter. #2: Thu 2024-02-29 00:00:00 UTC
 455        From now: 4 years 11 months left
 456        Iter. #3: Tue 2028-02-29 00:00:00 UTC
 457        From now: 8 years 11 months left
 458        Iter. #4: Sun 2032-02-29 00:00:00 UTC
 459        From now: 12 years 11 months left
 460        Iter. #5: Fri 2036-02-29 00:00:00 UTC
 461        From now: 16 years 11 months left
 462 </programlisting>
 463       </example>
 464     </refsect2>
 465
 466     <refsect2>
 467       <title><command>systemd-analyze timestamp <replaceable>TIMESTAMP</replaceable>...</command></title>
 468
 469       <para>This command parses a timestamp (i.e. a single point in time) and outputs the normalized form and
 470       the difference between this timestamp and now. The timestamp should adhere to the syntax documented in
 471       <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 472       section "PARSING TIMESTAMPS".</para>
 473
 474       <example>
 475         <title>Show parsing of timestamps</title>
 476
 477         <programlisting>$ systemd-analyze timestamp yesterday now tomorrow
 478   Original form: yesterday
 479 Normalized form: Mon 2019-05-20 00:00:00 CEST
 480        (in UTC): Sun 2019-05-19 22:00:00 UTC
 481    UNIX seconds: @15583032000
 482        From now: 1 day 9h ago
 483
 484   Original form: now
 485 Normalized form: Tue 2019-05-21 09:48:39 CEST
 486        (in UTC): Tue 2019-05-21 07:48:39 UTC
 487    UNIX seconds: @1558424919.659757
 488        From now: 43us ago
 489
 490   Original form: tomorrow
 491 Normalized form: Wed 2019-05-22 00:00:00 CEST
 492        (in UTC): Tue 2019-05-21 22:00:00 UTC
 493    UNIX seconds: @15584760000
 494        From now: 14h left
 495 </programlisting>
 496       </example>
 497     </refsect2>
 498
 499     <refsect2>
 500       <title><command>systemd-analyze timespan <replaceable>EXPRESSION</replaceable>...</command></title>
 501
 502       <para>This command parses a time span (i.e. a difference between two timestamps) and outputs the
 503       normalized form and the equivalent value in microseconds. The time span should adhere to the syntax
 504       documented in
 505       <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 506       section "PARSING TIME SPANS". Values without units are parsed as seconds.</para>
 507
 508       <example>
 509         <title>Show parsing of timespans</title>
 510
 511         <programlisting>$ systemd-analyze timespan 1s 300s '1year 0.000001s'
 512 Original: 1s
 513       μs: 1000000
 514    Human: 1s
 515
 516 Original: 300s
 517       μs: 300000000
 518    Human: 5min
 519
 520 Original: 1year 0.000001s
 521       μs: 31557600000001
 522    Human: 1y 1us
 523 </programlisting>
 524       </example>
 525     </refsect2>
 526
 527     <refsect2>
 528       <title><command>systemd-analyze cat-config</command>
 529       <replaceable>NAME</replaceable>|<replaceable>PATH</replaceable>...</title>
 530
 531       <para>This command is similar to <command>systemctl cat</command>, but operates on config files. It
 532       will copy the contents of a config file and any drop-ins to standard output, using the usual systemd
 533       set of directories and rules for precedence. Each argument must be either an absolute path including
 534       the prefix (such as <filename>/etc/systemd/logind.conf</filename> or
 535       <filename>/usr/lib/systemd/logind.conf</filename>), or a name relative to the prefix (such as
 536       <filename>systemd/logind.conf</filename>).</para>
 537
 538       <example>
 539         <title>Showing logind configuration</title>
 540         <programlisting>$ systemd-analyze cat-config systemd/logind.conf
 541 # /etc/systemd/logind.conf
 542 ...
 543 [Login]
 544 NAutoVTs=8
 545 ...
 546
 547 # /usr/lib/systemd/logind.conf.d/20-test.conf
 548 ... some override from another package
 549
 550 # /etc/systemd/logind.conf.d/50-override.conf
 551 ... some administrator override
 552         </programlisting>
 553       </example>
 554     </refsect2>
 555
 556     <refsect2>
 557       <title><command>systemd-analyze verify <replaceable>FILE</replaceable>...</command></title>
 558
 559       <para>This command will load unit files and print warnings if any errors are detected. Files specified
 560       on the command line will be loaded, but also any other units referenced by them. The full unit search
 561       path is formed by combining the directories for all command line arguments, and the usual unit load
 562       paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be used to replace or
 563       augment the compiled in set of unit load paths; see
 564       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).  All
 565       units files present in the directories containing the command line arguments will be used in preference
 566       to the other paths.</para>
 567
 568       <para>The following errors are currently detected:</para>
 569       <itemizedlist>
 570         <listitem><para>unknown sections and directives,</para></listitem>
 571
 572         <listitem><para>missing dependencies which are required to start the given unit,</para></listitem>
 573
 574         <listitem><para>man pages listed in <varname>Documentation=</varname> which are not found in the
 575         system,</para></listitem>
 576
 577         <listitem><para>commands listed in <varname>ExecStart=</varname> and similar which are not found in
 578         the system or not executable.</para></listitem>
 579       </itemizedlist>
 580
 581       <example>
 582         <title>Misspelt directives</title>
 583
 584         <programlisting>$ cat ./user.slice
 585 [Unit]
 586 WhatIsThis=11
 587 Documentation=man:nosuchfile(1)
 588 Requires=different.service
 589
 590 [Service]
 591 Description=x
 592
 593 $ systemd-analyze verify ./user.slice
 594 [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit'
 595 [./user.slice:13] Unknown section 'Service'. Ignoring.
 596 Error: org.freedesktop.systemd1.LoadFailed:
 597    Unit different.service failed to load:
 598    No such file or directory.
 599 Failed to create user.slice/start: Invalid argument
 600 user.slice: man nosuchfile(1) command failed with code 16
 601         </programlisting>
 602       </example>
 603
 604       <example>
 605         <title>Missing service units</title>
 606
 607         <programlisting>$ tail ./a.socket ./b.socket
 608 ==> ./a.socket &lt;==
 609 [Socket]
 610 ListenStream=100
 611
 612 ==> ./b.socket &lt;==
 613 [Socket]
 614 ListenStream=100
 615 Accept=yes
 616
 617 $ systemd-analyze verify ./a.socket ./b.socket
 618 Service a.service not loaded, a.socket cannot be started.
 619 Service b@0.service not loaded, b.socket cannot be started.
 620         </programlisting>
 621       </example>
 622     </refsect2>
 623
 624     <refsect2>
 625       <title><command>systemd-analyze security <optional><replaceable>UNIT</replaceable>...</optional></command></title>
 626
 627       <para>This command analyzes the security and sandboxing settings of one or more specified service
 628       units. If at least one unit name is specified the security settings of the specified service units are
 629       inspected and a detailed analysis is shown. If no unit name is specified, all currently loaded,
 630       long-running service units are inspected and a terse table with results shown. The command checks for
 631       various security-related service settings, assigning each a numeric "exposure level" value, depending
 632       on how important a setting is. It then calculates an overall exposure level for the whole unit, which
 633       is an estimation in the range 0.0…10.0 indicating how exposed a service is security-wise. High exposure
 634       levels indicate very little applied sandboxing. Low exposure levels indicate tight sandboxing and
 635       strongest security restrictions. Note that this only analyzes the per-service security features systemd
 636       itself implements. This means that any additional security mechanisms applied by the service code
 637       itself are not accounted for. The exposure level determined this way should not be misunderstood: a
 638       high exposure level neither means that there is no effective sandboxing applied by the service code
 639       itself, nor that the service is actually vulnerable to remote or local attacks. High exposure levels do
 640       indicate however that most likely the service might benefit from additional settings applied to
 641       them.</para>
 642
 643       <para>Please note that many of the security and sandboxing settings individually can be circumvented —
 644       unless combined with others. For example, if a service retains the privilege to establish or undo mount
 645       points many of the sandboxing options can be undone by the service code itself. Due to that is
 646       essential that each service uses the most comprehensive and strict sandboxing and security settings
 647       possible. The tool will take into account some of these combinations and relationships between the
 648       settings, but not all. Also note that the security and sandboxing settings analyzed here only apply to
 649       the operations executed by the service code itself. If a service has access to an IPC system (such as
 650       D-Bus) it might request operations from other services that are not subject to the same
 651       restrictions. Any comprehensive security and sandboxing analysis is hence incomplete if the IPC access
 652       policy is not validated too.</para>
 653
 654       <example>
 655       <title>Analyze <filename noindex="true">systemd-logind.service</filename></title>
 656
 657       <programlisting>$ systemd-analyze security --no-pager systemd-logind.service
 658   NAME                DESCRIPTION                              EXPOSURE
 659 ✗ PrivateNetwork=     Service has access to the host's network      0.5
 660 ✗ User=/DynamicUser=  Service runs as root user                     0.4
 661 ✗ DeviceAllow=        Service has no device ACL                     0.2
 662 ✓ IPAddressDeny=      Service blocks all IP address ranges
 663 ...
 664 → Overall exposure level for systemd-logind.service: 4.1 OK 🙂
 665 </programlisting>
 666       </example>
 667     </refsect2>
 668   </refsect1>
 669
 670   <refsect1>
 671     <title>Options</title>
 672
 673     <para>The following options are understood:</para>
 674
 675     <variablelist>
 676       <varlistentry>
 677         <term><option>--system</option></term>
 678
 679         <listitem><para>Operates on the system systemd instance. This
 680         is the implied default.</para></listitem>
 681       </varlistentry>
 682
 683       <varlistentry>
 684         <term><option>--user</option></term>
 685
 686         <listitem><para>Operates on the user systemd
 687         instance.</para></listitem>
 688       </varlistentry>
 689
 690       <varlistentry>
 691         <term><option>--global</option></term>
 692
 693         <listitem><para>Operates on the system-wide configuration for
 694         user systemd instance.</para></listitem>
 695       </varlistentry>
 696
 697       <varlistentry>
 698         <term><option>--order</option></term>
 699         <term><option>--require</option></term>
 700
 701         <listitem><para>When used in conjunction with the
 702         <command>dot</command> command (see above), selects which
 703         dependencies are shown in the dependency graph. If
 704         <option>--order</option> is passed, only dependencies of type
 705         <varname>After=</varname> or <varname>Before=</varname> are
 706         shown. If <option>--require</option> is passed, only
 707         dependencies of type <varname>Requires=</varname>,
 708         <varname>Requisite=</varname>,
 709         <varname>Wants=</varname> and <varname>Conflicts=</varname>
 710         are shown. If neither is passed, this shows dependencies of
 711         all these types.</para></listitem>
 712       </varlistentry>
 713
 714       <varlistentry>
 715         <term><option>--from-pattern=</option></term>
 716         <term><option>--to-pattern=</option></term>
 717
 718         <listitem><para>When used in conjunction with the
 719         <command>dot</command> command (see above), this selects which
 720         relationships are shown in the dependency graph. Both options
 721         require a
 722         <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 723         pattern as an argument, which will be matched against the
 724         left-hand and the right-hand, respectively, nodes of a
 725         relationship.</para>
 726
 727         <para>Each of these can be used more than once, in which case
 728         the unit name must match one of the values. When tests for
 729         both sides of the relation are present, a relation must pass
 730         both tests to be shown. When patterns are also specified as
 731         positional arguments, they must match at least one side of the
 732         relation. In other words, patterns specified with those two
 733         options will trim the list of edges matched by the positional
 734         arguments, if any are given, and fully determine the list of
 735         edges shown otherwise.</para></listitem>
 736       </varlistentry>
 737
 738       <varlistentry>
 739         <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
 740
 741         <listitem><para>When used in conjunction with the
 742         <command>critical-chain</command> command (see above), also
 743         show units, which finished <replaceable>timespan</replaceable>
 744         earlier, than the latest unit in the same level. The unit of
 745         <replaceable>timespan</replaceable> is seconds unless
 746         specified with a different unit, e.g.
 747         "50ms".</para></listitem>
 748       </varlistentry>
 749
 750       <varlistentry>
 751         <term><option>--man=no</option></term>
 752
 753         <listitem><para>Do not invoke man to verify the existence of
 754         man pages listed in <varname>Documentation=</varname>.
 755         </para></listitem>
 756       </varlistentry>
 757
 758       <varlistentry>
 759         <term><option>--generators</option></term>
 760
 761         <listitem><para>Invoke unit generators, see
 762         <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 763         Some generators require root privileges. Under a normal user, running with
 764         generators enabled will generally result in some warnings.</para></listitem>
 765       </varlistentry>
 766
 767       <varlistentry>
 768         <term><option>--root=<replaceable>PATH</replaceable></option></term>
 769
 770         <listitem><para>With <command>cat-files</command>, show config files underneath
 771         the specified root path <replaceable>PATH</replaceable>.</para></listitem>
 772       </varlistentry>
 773
 774       <varlistentry>
 775         <term><option>--iterations=<replaceable>NUMBER</replaceable></option></term>
 776
 777         <listitem><para>When used with the <command>calendar</command> command, show the specified number of
 778         iterations the specified calendar expression will elapse next. Defaults to 1.</para></listitem>
 779       </varlistentry>
 780
 781       <xi:include href="user-system-options.xml" xpointer="host" />
 782       <xi:include href="user-system-options.xml" xpointer="machine" />
 783
 784       <xi:include href="standard-options.xml" xpointer="help" />
 785       <xi:include href="standard-options.xml" xpointer="version" />
 786       <xi:include href="standard-options.xml" xpointer="no-pager" />
 787     </variablelist>
 788
 789   </refsect1>
 790
 791   <refsect1>
 792     <title>Exit status</title>
 793
 794     <para>On success, 0 is returned, a non-zero failure code
 795     otherwise.</para>
 796   </refsect1>
 797
 798   <xi:include href="less-variables.xml" />
 799
 800   <refsect1>
 801     <title>See Also</title>
 802     <para>
 803       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 804       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 805     </para>
 806   </refsect1>
 807
 808 </refentry>