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