| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <!-- |
| SPDX-License-Identifier: LGPL-2.1+ |
| --> |
| |
| <refentry id="systemd-analyze" |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| |
| <refentryinfo> |
| <title>systemd-analyze</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>systemd-analyze</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>systemd-analyze</refname> |
| <refpurpose>Analyze and debug system manager</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg>time</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">blame</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">critical-chain</arg> |
| <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">plot</arg> |
| <arg choice="opt">> file.svg</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">dot</arg> |
| <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg> |
| <arg choice="opt">> file.dot</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">dump</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">cat-config</arg> |
| <arg choice="plain" rep="repeat"><replaceable>NAME</replaceable>|<replaceable>PATH</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">unit-paths</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">log-level</arg> |
| <arg choice="opt"><replaceable>LEVEL</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">log-target</arg> |
| <arg choice="opt"><replaceable>TARGET</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">syscall-filter</arg> |
| <arg choice="opt"><replaceable>SET</replaceable>…</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">verify</arg> |
| <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">calendar</arg> |
| <arg choice="plain" rep="repeat"><replaceable>SPECS</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">service-watchdogs</arg> |
| <arg choice="opt"><replaceable>BOOL</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">timespan</arg> |
| <arg choice="plain" rep="repeat"><replaceable>SPAN</replaceable></arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| <command>systemd-analyze</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="plain">security</arg> |
| <arg choice="plain" rep="repeat"><replaceable>UNIT</replaceable></arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><command>systemd-analyze</command> may be used to determine |
| system boot-up performance statistics and retrieve other state and |
| tracing information from the system and service manager, and to |
| verify the correctness of unit files. It is also used to access |
| special functions useful for advanced system manager debugging.</para> |
| |
| <para><command>systemd-analyze time</command> prints the time |
| spent in the kernel before userspace has been reached, the time |
| spent in the initial RAM disk (initrd) before normal system |
| userspace has been reached, and the time normal system userspace |
| took to initialize. Note that these measurements simply measure |
| the time passed up to the point where all system services have |
| been spawned, but not necessarily until they fully finished |
| initialization or the disk is idle.</para> |
| |
| <para><command>systemd-analyze blame</command> prints a list of |
| all running units, ordered by the time they took to initialize. |
| This information may be used to optimize boot-up times. Note that |
| the output might be misleading as the initialization of one |
| service might be slow simply because it waits for the |
| initialization of another service to complete. |
| Also note: <command>systemd-analyze blame</command> doesn't display |
| results for services with <varname>Type=simple</varname>, |
| because systemd considers such services to be started immediately, |
| hence no measurement of the initialization delays can be done.</para> |
| |
| <para><command>systemd-analyze critical-chain |
| [<replaceable>UNIT…</replaceable>]</command> prints a tree of |
| the time-critical chain of units (for each of the specified |
| <replaceable>UNIT</replaceable>s or for the default target |
| otherwise). The time after the unit is active or started is |
| printed after the "@" character. The time the unit takes to start |
| is printed after the "+" character. Note that the output might be |
| misleading as the initialization of one service might depend on |
| socket activation and because of the parallel execution of |
| units.</para> |
| |
| <para><command>systemd-analyze plot</command> prints an SVG |
| graphic detailing which system services have been started at what |
| time, highlighting the time they spent on initialization.</para> |
| |
| <para><command>systemd-analyze dot</command> generates textual |
| dependency graph description in dot format for further processing |
| with the GraphViz |
| <citerefentry project='die-net'><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| tool. Use a command line like <command>systemd-analyze dot | dot |
| -Tsvg > systemd.svg</command> to generate a graphical dependency |
| tree. Unless <option>--order</option> or |
| <option>--require</option> is passed, the generated graph will |
| show both ordering and requirement dependencies. Optional pattern |
| globbing style specifications (e.g. <filename>*.target</filename>) |
| may be given at the end. A unit dependency is included in the |
| graph if any of these patterns match either the origin or |
| destination node.</para> |
| |
| <para><command>systemd-analyze dump</command> outputs a (usually |
| very long) human-readable serialization of the complete server |
| state. Its format is subject to change without notice and should |
| not be parsed by applications.</para> |
| |
| <para><command>systemd-analyze cat-config</command> is similar |
| to <command>systemctl cat</command>, but operates on config files. |
| It will copy the contents of a config file and any drop-ins to standard |
| output, using the usual systemd set of directories and rules for |
| precedence. Each argument must be either an absolute path including |
| the prefix (such as <filename>/etc/systemd/logind.conf</filename> or |
| <filename>/usr/lib/systemd/logind.conf</filename>), or a name |
| relative to the prefix (such as <filename>systemd/logind.conf</filename>). |
| </para> |
| |
| <example> |
| <title>Showing logind configuration</title> |
| <programlisting>$ systemd-analyze cat-config systemd/logind.conf |
| # /etc/systemd/logind.conf |
| ... |
| [Login] |
| NAutoVTs=8 |
| ... |
| |
| # /usr/lib/systemd/logind.conf.d/20-test.conf |
| ... some override from another package |
| |
| # /etc/systemd/logind.conf.d/50-override.conf |
| ... some administrator override |
| </programlisting> |
| </example> |
| |
| <para><command>systemd-analyze unit-paths</command> outputs a list of all |
| directories from which unit files, <filename>.d</filename> overrides, and |
| <filename>.wants</filename>, <filename>.requires</filename> symlinks may be |
| loaded. Combine with <option>--user</option> to retrieve the list for the user |
| manager instance, and <option>--global</option> for the global configuration of |
| user manager instances. Note that this verb prints the list that is compiled into |
| <command>systemd-analyze</command> itself, and does not comunicate with the |
| running manager. Use |
| <programlisting>systemctl [--user] [--global] show -p UnitPath --value</programlisting> |
| to retrieve the actual list that the manager uses, with any empty directories |
| omitted.</para> |
| |
| <para><command>systemd-analyze log-level</command> |
| prints the current log level of the <command>systemd</command> daemon. |
| If an optional argument <replaceable>LEVEL</replaceable> is provided, then the command changes the current log |
| level of the <command>systemd</command> daemon to <replaceable>LEVEL</replaceable> (accepts the same values as |
| <option>--log-level=</option> described in |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> |
| |
| <para><command>systemd-analyze log-target</command> |
| prints the current log target of the <command>systemd</command> daemon. |
| If an optional argument <replaceable>TARGET</replaceable> is provided, then the command changes the current log |
| target of the <command>systemd</command> daemon to <replaceable>TARGET</replaceable> (accepts the same values as |
| <option>--log-target=</option>, described in |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> |
| |
| <para><command>systemd-analyze syscall-filter <optional><replaceable>SET</replaceable>…</optional></command> |
| will list system calls contained in the specified system call set <replaceable>SET</replaceable>, |
| or all known sets if no sets are specified. Argument <replaceable>SET</replaceable> must include |
| the <literal>@</literal> prefix.</para> |
| |
| <para><command>systemd-analyze verify</command> will load unit files and print |
| warnings if any errors are detected. Files specified on the command line will be |
| loaded, but also any other units referenced by them. The full unit search path is |
| formed by combining the directories for all command line arguments, and the usual unit |
| load paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be |
| used to replace or augment the compiled in set of unit load paths; see |
| <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
| All units files present in the directories containing the command line arguments will |
| be used in preference to the other paths.</para> |
| |
| <para><command>systemd-analyze calendar</command> will parse and normalize repetitive calendar time events, and |
| will calculate when they will elapse next. This takes the same input as the <varname>OnCalendar=</varname> setting |
| in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, following the |
| syntax described in |
| <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> |
| |
| <para><command>systemd-analyze service-watchdogs</command> |
| prints the current state of service runtime watchdogs of the <command>systemd</command> daemon. |
| If an optional boolean argument is provided, then globally enables or disables the service |
| runtime watchdogs (<option>WatchdogSec=</option>) and emergency actions (e.g. |
| <option>OnFailure=</option> or <option>StartLimitAction=</option>); see |
| <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. |
| The hardware watchdog is not affected by this setting.</para> |
| |
| <para><command>systemd-analyze timespan</command> parses a time span and outputs the equivalent value in microseconds, and as a reformatted timespan. |
| The time span should adhere to the same syntax documented in <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. |
| Values without associated magnitudes are parsed as seconds.</para> |
| |
| <para><command>systemd-analyze security</command> analyzes the security and sandboxing settings of one or more |
| specified service units. If at least one unit name is specified the security settings of the specified service |
| units are inspected and a detailed analysis is shown. If no unit name is specified, all currently loaded, |
| long-running service units are inspected and a terse table with results shown. The command checks for various |
| security-related service settings, assigning each a numeric "exposure level" value, depending on how important a |
| setting is. It then calculates an overall exposure level for the whole unit, which is an estimation in the range |
| 0.0…10.0 indicating how exposed a service is security-wise. High exposure levels indicate very little applied |
| sandboxing. Low exposure levels indicate tight sandboxing and strongest security restrictions. Note that this only |
| analyzes the per-service security features systemd itself implements. This means that any additional security |
| mechanisms applied by the service code itself are not accounted for. The exposure level determined this way should |
| not be misunderstood: a high exposure level neither means that there is no effective sandboxing applied by the |
| service code itself, nor that the service is actually vulnerable to remote or local attacks. High exposure levels |
| do indicate however that most likely the service might benefit from additional settings applied to them. Please |
| note that many of the security and sandboxing settings individually can be circumvented — unless combined with |
| others. For example, if a service retains the privilege to establish or undo mount points many of the sandboxing |
| options can be undone by the service code itself. Due to that is essential that each service uses the most |
| comprehensive and strict sandboxing and security settings possible. The tool will take into account some of these |
| combinations and relationships between the settings, but not all. Also note that the security and sandboxing |
| settings analyzed here only apply to the operations executed by the service code itself. If a service has access to |
| an IPC system (such as D-Bus) it might request operations from other services that are not subject to the same |
| restrictions. Any comprehensive security and sandboxing analysis is hence incomplete if the IPC access policy is |
| not validated too.</para> |
| |
| <para>If no command is passed, <command>systemd-analyze |
| time</command> is implied.</para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The following options are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--system</option></term> |
| |
| <listitem><para>Operates on the system systemd instance. This |
| is the implied default.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--user</option></term> |
| |
| <listitem><para>Operates on the user systemd |
| instance.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--global</option></term> |
| |
| <listitem><para>Operates on the system-wide configuration for |
| user systemd instance.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--order</option></term> |
| <term><option>--require</option></term> |
| |
| <listitem><para>When used in conjunction with the |
| <command>dot</command> command (see above), selects which |
| dependencies are shown in the dependency graph. If |
| <option>--order</option> is passed, only dependencies of type |
| <varname>After=</varname> or <varname>Before=</varname> are |
| shown. If <option>--require</option> is passed, only |
| dependencies of type <varname>Requires=</varname>, |
| <varname>Requisite=</varname>, |
| <varname>Wants=</varname> and <varname>Conflicts=</varname> |
| are shown. If neither is passed, this shows dependencies of |
| all these types.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--from-pattern=</option></term> |
| <term><option>--to-pattern=</option></term> |
| |
| <listitem><para>When used in conjunction with the |
| <command>dot</command> command (see above), this selects which |
| relationships are shown in the dependency graph. Both options |
| require a |
| <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> |
| pattern as an argument, which will be matched against the |
| left-hand and the right-hand, respectively, nodes of a |
| relationship.</para> |
| |
| <para>Each of these can be used more than once, in which case |
| the unit name must match one of the values. When tests for |
| both sides of the relation are present, a relation must pass |
| both tests to be shown. When patterns are also specified as |
| positional arguments, they must match at least one side of the |
| relation. In other words, patterns specified with those two |
| options will trim the list of edges matched by the positional |
| arguments, if any are given, and fully determine the list of |
| edges shown otherwise.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--fuzz=</option><replaceable>timespan</replaceable></term> |
| |
| <listitem><para>When used in conjunction with the |
| <command>critical-chain</command> command (see above), also |
| show units, which finished <replaceable>timespan</replaceable> |
| earlier, than the latest unit in the same level. The unit of |
| <replaceable>timespan</replaceable> is seconds unless |
| specified with a different unit, e.g. |
| "50ms".</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--man=no</option></term> |
| |
| <listitem><para>Do not invoke man to verify the existence of |
| man pages listed in <varname>Documentation=</varname>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--generators</option></term> |
| |
| <listitem><para>Invoke unit generators, see |
| <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. |
| Some generators require root privileges. Under a normal user, running with |
| generators enabled will generally result in some warnings.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--root=<replaceable>PATH</replaceable></option></term> |
| |
| <listitem><para>With <command>cat-files</command>, show config files underneath |
| the specified root path <replaceable>PATH</replaceable>.</para></listitem> |
| </varlistentry> |
| |
| <xi:include href="user-system-options.xml" xpointer="host" /> |
| <xi:include href="user-system-options.xml" xpointer="machine" /> |
| |
| <xi:include href="standard-options.xml" xpointer="help" /> |
| <xi:include href="standard-options.xml" xpointer="version" /> |
| <xi:include href="standard-options.xml" xpointer="no-pager" /> |
| </variablelist> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Exit status</title> |
| |
| <para>On success, 0 is returned, a non-zero failure code |
| otherwise.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples for <command>dot</command></title> |
| |
| <example> |
| <title>Plots all dependencies of any unit whose name starts with |
| <literal>avahi-daemon</literal></title> |
| |
| <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg |
| $ eog avahi.svg</programlisting> |
| </example> |
| |
| <example> |
| <title>Plots the dependencies between all known target units</title> |
| |
| <programlisting>$ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg |
| $ eog targets.svg</programlisting> |
| </example> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples for <command>verify</command></title> |
| |
| <para>The following errors are currently detected:</para> |
| <itemizedlist> |
| <listitem><para>unknown sections and directives, |
| </para></listitem> |
| |
| <listitem><para>missing dependencies which are required to start |
| the given unit,</para></listitem> |
| |
| <listitem><para>man pages listed in |
| <varname>Documentation=</varname> which are not found in the |
| system,</para></listitem> |
| |
| <listitem><para>commands listed in <varname>ExecStart=</varname> |
| and similar which are not found in the system or not |
| executable.</para></listitem> |
| </itemizedlist> |
| |
| <example> |
| <title>Misspelt directives</title> |
| |
| <programlisting>$ cat ./user.slice |
| [Unit] |
| WhatIsThis=11 |
| Documentation=man:nosuchfile(1) |
| Requires=different.service |
| |
| [Service] |
| Description=x |
| |
| $ systemd-analyze verify ./user.slice |
| [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit' |
| [./user.slice:13] Unknown section 'Service'. Ignoring. |
| Error: org.freedesktop.systemd1.LoadFailed: |
| Unit different.service failed to load: |
| No such file or directory. |
| Failed to create user.slice/start: Invalid argument |
| user.slice: man nosuchfile(1) command failed with code 16 |
| </programlisting> |
| </example> |
| |
| <example> |
| <title>Missing service units</title> |
| |
| <programlisting>$ tail ./a.socket ./b.socket |
| ==> ./a.socket <== |
| [Socket] |
| ListenStream=100 |
| |
| ==> ./b.socket <== |
| [Socket] |
| ListenStream=100 |
| Accept=yes |
| |
| $ systemd-analyze verify ./a.socket ./b.socket |
| Service a.service not loaded, a.socket cannot be started. |
| Service b@0.service not loaded, b.socket cannot be started. |
| </programlisting> |
| </example> |
| </refsect1> |
| |
| <xi:include href="less-variables.xml" /> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |