From a2e00522971897909db2a81b4daf10e5700f453e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Mar 2019 10:13:55 +0100 Subject: [PATCH] man: reorder and add examples to systemd-analyze(1) The number of verbs supported by systemd-analyze has grown quite a bit, and the man page has become an unreadable wall of text. Let's put each verb in a separate subsection, grouping similar verbs together, and add a lot of examples to guide the user. (cherry picked from commit d323a99001c1f7625e8ac902e18deb514a4ca18d) Related: #1750343 --- man/systemd-analyze.xml | 678 +++++++++++++++++++++++++--------------- 1 file changed, 429 insertions(+), 249 deletions(-) diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index f3b595880f..7c873cbdd1 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -41,46 +41,50 @@ critical-chain UNIT + systemd-analyze OPTIONS - plot - > file.svg + log-level + LEVEL systemd-analyze OPTIONS - dot - PATTERN - > file.dot + log-target + TARGET systemd-analyze OPTIONS - dump + service-watchdogs + BOOL + systemd-analyze OPTIONS - cat-config - NAME|PATH + dump + systemd-analyze OPTIONS - unit-paths + plot + >file.svg systemd-analyze OPTIONS - log-level - LEVEL + dot + PATTERN + >file.dot + systemd-analyze OPTIONS - log-target - TARGET + unit-paths systemd-analyze @@ -91,20 +95,20 @@ systemd-analyze OPTIONS - verify - FILES + calendar + SPECS systemd-analyze OPTIONS - calendar - SPECS + timespan + SPAN systemd-analyze OPTIONS - service-watchdogs - BOOL + cat-config + NAME|PATH systemd-analyze @@ -123,73 +127,299 @@ verify the correctness of unit files. It is also used to access special functions useful for advanced system manager debugging. - systemd-analyze time 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. - - systemd-analyze blame 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: systemd-analyze blame doesn't display - results for services with Type=simple, - because systemd considers such services to be started immediately, - hence no measurement of the initialization delays can be done. - - systemd-analyze critical-chain - [UNIT…] prints a tree of - the time-critical chain of units (for each of the specified - UNITs 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. - - systemd-analyze plot prints an SVG - graphic detailing which system services have been started at what - time, highlighting the time they spent on initialization. - - systemd-analyze dot generates textual - dependency graph description in dot format for further processing - with the GraphViz - dot1 - tool. Use a command line like systemd-analyze dot | dot - -Tsvg > systemd.svg to generate a graphical dependency - tree. Unless or - is passed, the generated graph will - show both ordering and requirement dependencies. Optional pattern - globbing style specifications (e.g. *.target) - 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. - - systemd-analyze dump 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. - - systemd-analyze cat-config is similar - to systemctl cat, 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 /etc/systemd/logind.conf or - /usr/lib/systemd/logind.conf), or a name - relative to the prefix (such as systemd/logind.conf). - + If no command is passed, systemd-analyze + time is implied. + + + <command>systemd-analyze time</command> + + This 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. + + + <command>Show how long the boot took</command> + + # in a container +$ systemd-analyze time +Startup finished in 296ms (userspace) +multi-user.target reached after 275ms in userspace + +# on a real machine +$ systemd-analyze time +Startup finished in 2.584s (kernel) + 19.176s (initrd) + 47.847s (userspace) = 1min 9.608s +multi-user.target reached after 47.820s in userspace + + + + + + <command>systemd-analyze blame</command> + + This 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: systemd-analyze blame doesn't display results for + services with Type=simple, because systemd considers such services to be started + immediately, hence no measurement of the initialization delays can be done. + + + <command>Show which units took the most time during boot</command> + + $ systemd-analyze blame + 32.875s pmlogger.service + 20.905s systemd-networkd-wait-online.service + 13.299s dev-vda1.device + ... + 23ms sysroot.mount + 11ms initrd-udevadm-cleanup-db.service + 3ms sys-kernel-config.mount + + + + + + <command>systemd-analyze critical-chain <optional><replaceable>UNIT</replaceable>...</optional></command> + + This command prints a tree of the time-critical chain of units (for each of the specified + UNITs 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 services might + depend on socket activation and because of the parallel execution of units. + + + <command>systemd-analyze time</command> + + $ systemd-analyze critical-chain +multi-user.target @47.820s +└─pmie.service @35.968s +548ms + └─pmcd.service @33.715s +2.247s + └─network-online.target @33.712s + └─systemd-networkd-wait-online.service @12.804s +20.905s + └─systemd-networkd.service @11.109s +1.690s + └─systemd-udevd.service @9.201s +1.904s + └─systemd-tmpfiles-setup-dev.service @7.306s +1.776s + └─kmod-static-nodes.service @6.976s +177ms + └─systemd-journald.socket + └─system.slice + └─-.slice + + + + + + <command>systemd-analyze log-level [<replaceable>LEVEL</replaceable>]</command> + + systemd-analyze log-level prints the current log level of the + systemd daemon. If an optional argument LEVEL is + provided, then the command changes the current log level of the systemd daemon to + LEVEL (accepts the same values as described in + systemd1). + + + + <command>systemd-analyze log-target [<replaceable>TARGET</replaceable>]</command> + + systemd-analyze log-target prints the current log target of the + systemd daemon. If an optional argument TARGET is + provided, then the command changes the current log target of the systemd daemon to + TARGET (accepts the same values as , described + in systemd1). + + + + <command>systemd-analyze service-watchdogs [yes|no]</command> + + systemd-analyze service-watchdogs prints the current state of service runtime + watchdogs of the systemd daemon. If an optional boolean argument is provided, then + globally enables or disables the service runtime watchdogs () and + emergency actions (e.g. or ); see + systemd.service5. + The hardware watchdog is not affected by this setting. + + + + <command>systemd-analyze dump</command> + + This 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. + + + Show the internal state of user manager + + $ systemd-analyze --user dump +Timestamp userspace: Thu 2019-03-14 23:28:07 CET +Timestamp finish: Thu 2019-03-14 23:28:07 CET +Timestamp generators-start: Thu 2019-03-14 23:28:07 CET +Timestamp generators-finish: Thu 2019-03-14 23:28:07 CET +Timestamp units-load-start: Thu 2019-03-14 23:28:07 CET +Timestamp units-load-finish: Thu 2019-03-14 23:28:07 CET +-> Unit proc-timer_list.mount: + Description: /proc/timer_list + ... +-> Unit default.target: + Description: Main user target +... + + + + + + <command>systemd-analyze plot</command> + + This command prints an SVG graphic detailing which system services have been started at what + time, highlighting the time they spent on initialization. + + + <command>Plot a bootchart</command> + + $ systemd-analyze plot >bootup.svg +$ eog bootup.svg& + + + + + + <command>systemd-analyze dot [<replaceable>pattern</replaceable>...]</command> + + This command generates textual dependency graph description in dot format for further processing + with the GraphViz + dot1 + tool. Use a command line like systemd-analyze dot | dot -Tsvg >systemd.svg to + generate a graphical dependency tree. Unless or is + passed, the generated graph will show both ordering and requirement dependencies. Optional pattern + globbing style specifications (e.g. *.target) 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. + + + Plot all dependencies of any unit whose name starts with <literal>avahi-daemon</literal> + + + $ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg >avahi.svg +$ eog avahi.svg + + + + Plot the dependencies between all known target units - - Showing logind configuration - $ systemd-analyze cat-config systemd/logind.conf + $ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' \ + | dot -Tsvg >targets.svg +$ eog targets.svg + + + + + <command>systemd-analyze unit-paths</command> + + This command outputs a list of all directories from which unit files, .d + overrides, and .wants, .requires symlinks may be + loaded. Combine with to retrieve the list for the user manager instance, and + for the global configuration of user manager instances. + + + <command>Show all paths for generated units</command> + + $ systemd-analyze unit-paths | grep '^/run' +/run/systemd/system.control +/run/systemd/transient +/run/systemd/generator.early +/run/systemd/system +/run/systemd/system.attached +/run/systemd/generator +/run/systemd/generator.late + + + + Note that this verb prints the list that is compiled into systemd-analyze + itself, and does not comunicate with the running manager. Use + systemctl [--user] [--global] show -p UnitPath --value + to retrieve the actual list that the manager uses, with any empty directories omitted. + + + + <command>systemd-analyze syscall-filter <optional><replaceable>SET</replaceable>...</optional></command> + + This command will list system calls contained in the specified system call set + SET, or all known sets if no sets are specified. Argument + SET must include the @ prefix. + + + + <command>systemd-analyze calendar <replaceable>EXPRESSION</replaceable>...</command> + + This command will parse and normalize repetitive calendar time events, and will calculate when + they elapse next. This takes the same input as the OnCalendar= setting in + systemd.timer5, + following the syntax described in + systemd.time7. By + default, only the next time the calendar expression will elapse is shown; use + to show the specified number of next times the expression + elapses. + + + Show leap days in the near future + + $ systemd-analyze calendar --iterations=5 '*-2-29 0:0:0' + Original form: *-2-29 0:0:0 +Normalized form: *-02-29 00:00:00 + Next elapse: Sat 2020-02-29 00:00:00 UTC + From now: 11 months 15 days left + Iter. #2: Thu 2024-02-29 00:00:00 UTC + From now: 4 years 11 months left + Iter. #3: Tue 2028-02-29 00:00:00 UTC + From now: 8 years 11 months left + Iter. #4: Sun 2032-02-29 00:00:00 UTC + From now: 12 years 11 months left + Iter. #5: Fri 2036-02-29 00:00:00 UTC + From now: 16 years 11 months left + + + + + + <command>systemd-analyze timespan <replaceable>EXPRESSION</replaceable>...</command> + + This command parses a time span and outputs the normalized form and the equivalent value in + microseconds. The time span should adhere to the same syntax documented in + systemd.time7. + Values without associated magnitudes are parsed as seconds. + + + Show parsing of timespans + + $ systemd-analyze timespan 1s 300s '1year 0.000001s' +Original: 1s + μs: 1000000 + Human: 1s + +Original: 300s + μs: 300000000 + Human: 5min + +Original: 1year 0.000001s + μs: 31557600000001 + Human: 1y 1us + + + + + + <command>systemd-analyze cat-config</command> + <replaceable>NAME</replaceable>|<replaceable>PATH</replaceable>... + + This command is similar to systemctl cat, 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 /etc/systemd/logind.conf or + /usr/lib/systemd/logind.conf), or a name relative to the prefix (such as + systemd/logind.conf). + + + Showing logind configuration + $ systemd-analyze cat-config systemd/logind.conf # /etc/systemd/logind.conf ... [Login] @@ -201,90 +431,122 @@ NAutoVTs=8 # /etc/systemd/logind.conf.d/50-override.conf ... some administrator override - - - - systemd-analyze unit-paths outputs a list of all - directories from which unit files, .d overrides, and - .wants, .requires symlinks may be - loaded. Combine with to retrieve the list for the user - manager instance, and for the global configuration of - user manager instances. Note that this verb prints the list that is compiled into - systemd-analyze itself, and does not comunicate with the - running manager. Use - systemctl [--user] [--global] show -p UnitPath --value - to retrieve the actual list that the manager uses, with any empty directories - omitted. - - systemd-analyze log-level - prints the current log level of the systemd daemon. - If an optional argument LEVEL is provided, then the command changes the current log - level of the systemd daemon to LEVEL (accepts the same values as - described in - systemd1). - - systemd-analyze log-target - prints the current log target of the systemd daemon. - If an optional argument TARGET is provided, then the command changes the current log - target of the systemd daemon to TARGET (accepts the same values as - , described in - systemd1). - - systemd-analyze syscall-filter SET… - will list system calls contained in the specified system call set SET, - or all known sets if no sets are specified. Argument SET must include - the @ prefix. - - systemd-analyze verify 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 $SYSTEMD_UNIT_PATH is supported, and may be - used to replace or augment the compiled in set of unit load paths; see - systemd.unit5). - All units files present in the directories containing the command line arguments will - be used in preference to the other paths. - - systemd-analyze calendar will parse and normalize repetitive calendar time events, and - will calculate when they will elapse next. This takes the same input as the OnCalendar= setting - in systemd.timer5, following the - syntax described in - systemd.time7. - - systemd-analyze service-watchdogs - prints the current state of service runtime watchdogs of the systemd daemon. - If an optional boolean argument is provided, then globally enables or disables the service - runtime watchdogs () and emergency actions (e.g. - or ); see - systemd.service5. - The hardware watchdog is not affected by this setting. - - systemd-analyze security 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. + + + - If no command is passed, systemd-analyze - time is implied. + + <command>systemd-analyze verify <replaceable>FILE</replaceable>...</command> + + This 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 $SYSTEMD_UNIT_PATH is supported, and may be used to replace or + augment the compiled in set of unit load paths; see + systemd.unit5). All + units files present in the directories containing the command line arguments will be used in preference + to the other paths. + + The following errors are currently detected: + + unknown sections and directives, + + missing dependencies which are required to start the given unit, + + man pages listed in Documentation= which are not found in the + system, + + commands listed in ExecStart= and similar which are not found in + the system or not executable. + + + Misspelt directives + + $ 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 + + + + + Missing service units + + $ 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. + + + + + + <command>systemd-analyze security <optional><replaceable>UNIT</replaceable>...</optional></command> + + This 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. + + + Analyze <filename noindex="true">systemd-logind.service</filename> + + $ systemd-analyze security --no-pager systemd-logind.service + NAME DESCRIPTION EXPOSURE +✗ PrivateNetwork= Service has access to the host's network 0.5 +✗ User=/DynamicUser= Service runs as root user 0.4 +✗ DeviceAllow= Service has no device ACL 0.2 +✓ IPAddressDeny= Service blocks all IP address ranges +... +→ Overall exposure level for systemd-logind.service: 4.1 OK 🙂 + + + @@ -408,88 +670,6 @@ NAutoVTs=8 otherwise. - - Examples for <command>dot</command> - - - Plots all dependencies of any unit whose name starts with - <literal>avahi-daemon</literal> - - $ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg -$ eog avahi.svg - - - - Plots the dependencies between all known target units - - $ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg -$ eog targets.svg - - - - - Examples for <command>verify</command> - - The following errors are currently detected: - - unknown sections and directives, - - - missing dependencies which are required to start - the given unit, - - man pages listed in - Documentation= which are not found in the - system, - - commands listed in ExecStart= - and similar which are not found in the system or not - executable. - - - - Misspelt directives - - $ 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 - - - - - Missing service units - - $ 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. - - - -