From c035f3766c7808955a7d2e42316b3f008a236fcc Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 15 Nov 2019 13:30:02 +0100 Subject: [PATCH] man: significantly downgrade the Options section in systemd(1) This structure of the man page originates from the time when systemd was installed on top of sysvinit systems, and users had an actual chance to interact with the systemd binary directly. Nowadays it is almost never called directly, so let's properly explain this in the overview. The Options section is moved down below the kernel command line, those options are only needed in special circumstances. Let's refer the reader to the description of the kernel command line options, and not duplicate the descriptions (which makes the text longer than necessary and increases chances for discrepancies). Systemd is also prominently used as the user manager, let's mention that in the Overview. While at it, use "=" only when an argument is required as we nowadays do. --- man/systemd.xml | 433 +++++++++++++++++++++++------------------------- 1 file changed, 208 insertions(+), 225 deletions(-) diff --git a/man/systemd.xml b/man/systemd.xml index 5caf54b3306..9b2d5ac2805 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -37,19 +37,22 @@ Description - systemd is a system and service manager for Linux operating - systems. When run as first process on boot (as PID 1), it acts as - init system that brings up and maintains userspace - services. - - For compatibility with SysV, if systemd is called as - init and a PID that is not 1, it will execute - telinit and pass all command line arguments - unmodified. That means init and - telinit are mostly equivalent when invoked from - normal login sessions. See - telinit8 - for more information. + systemd is a system and service manager for Linux operating systems. When run as first process on + boot (as PID 1), it acts as init system that brings up and maintains userspace services. Seperate + instances are started for logged-in users to start their services. + + systemd is usually not invoked directly by the user, but is installed as the + /sbin/init symlink and started during early boot. The user manager instances are + started automatically through the + user@.service5 + service. + + For compatibility with SysV, if the binary is called as init and is not the + first process on the machine (PID is not 1), it will execute telinit and pass all + command line arguments unmodified. That means init and telinit are + mostly equivalent when invoked from normal login sessions. See + telinit8 for more + information. When run as a system instance, systemd interprets the configuration file system.conf and the files @@ -61,210 +64,6 @@ for more information. - - Options - - The following options are understood: - - - - - - Determine the initial start-up transaction (i.e. the list of jobs enqueued at - start-up), dump it and exit — without actually executing any of the determined jobs. This option is - useful for debugging only. Note that during regular service manager start-up additional units not - shown by this operation may be started, because hardware, socket, bus or other kinds of activation - might add additional jobs as the transaction is executed. Use to request - the initial transaction of the system service manager (this is also the implied default), combine - with to request the initial transaction of the per-user service manager - instead. - - - - - Dump understood unit configuration items. This - outputs a terse but complete list of configuration items - understood in unit definition files. - - - - - Dump exposed bus properties. This outputs a terse but complete list of properties - exposed on D-Bus. - - - - - Set default unit to activate on startup. If - not specified, defaults to - default.target. - - - - - - - When used in conjunction with , selects whether to calculate - the initial transaction for the system instance or for a per-user instance. These options have no - effect when invoked without , as during regular - (i.e. non-) invocations the service manager will automatically detect whether - it shall operate in system or per-user mode, by checking whether the PID it is run as is 1 or - not. Note that it is not supported booting and maintaining a system with the service manager running - in mode but with a PID other than 1. - - - - - - Enable core dumping on crash. This switch has - no effect when running as user instance. This setting may also - be enabled during boot on the kernel command line via the - systemd.dump_core= option, see - below. - - - - VT - - Switch to a specific virtual console (VT) on - crash. Takes a positive integer in the range 1–63, or a - boolean argument. If an integer is passed, selects which VT to - switch to. If yes, the VT kernel messages - are written to is selected. If no, no VT - switch is attempted. This switch has no effect when running as - user instance. This setting may also be enabled during boot, - on the kernel command line via the - systemd.crash_vt= option, see - - below. - - - - - - Run a shell on crash. This switch has no - effect when running as user instance. This setting may also be - enabled during boot, on the kernel command line via the - systemd.crash_shell= option, see - below. - - - - - - Automatically reboot the system on crash. This - switch has no effect when running as user instance. This - setting may also be enabled during boot, on the kernel command - line via the systemd.crash_reboot= option, - see below. - - - - - - Ask for confirmation when spawning processes. - This switch has no effect when run as user - instance. - - - - - Takes a boolean argument or the special value auto. If on, terse unit - status information is shown on the console during boot-up and shutdown. If off, no such status information is - shown. If set to auto behavior is similar to off, except that it is automatically switched - to on, as soon as the first unit failure or significant boot delay is encountered. This switch has no effect - when invoked as user instance. If specified, overrides both the kernel command line setting - systemd.show_status= (see below) and the configuration file option - , see - systemd-system.conf5. - - - - - Set log target. Argument must be one of - , - , - , - , - . - - - - - Set log level. As - argument this accepts a numerical log - level or the well-known syslog3 - symbolic names (lowercase): - , - , - , - , - , - , - , - . - - - - - Highlight important log messages. Argument is - a boolean value. If the argument is omitted, it defaults to - . - - - - - Include code location in log messages. This is - mostly relevant for debugging purposes. Argument is a boolean - value. If the argument is omitted it defaults to - . - - - - - - Sets the default output or error output for - all services and sockets, respectively. That is, controls the - default for and - (see - systemd.exec5 - for details). Takes one of - , - , - , - , - , - , - . If the - argument is omitted - defaults to - and - to - . - - - - - - Override the machine-id set on the hard drive, - useful for network booting or for containers. May not be set - to all zeros. - - - - - - Globally enable/disable all service watchdog timeouts and emergency - actions. This setting may also be specified during boot, on the kernel - command line via the systemd.service_watchdogs= - option, see below. Defaults to enabled. - - - - - - - Concepts @@ -1007,9 +806,7 @@ it defaults to auto. If specified overrides the system manager configuration file option , see systemd-system.conf5. - However, the process command line option - takes precedence over both this kernel command line option and the - configuration file option. + @@ -1040,11 +837,15 @@ systemd.default_standard_output= systemd.default_standard_error= - Controls default standard output and error - output for services, with the same effect as the - and - command line - arguments described above, respectively. + + Controls default standard output and error output for services and sockets. That is, + controls the default for and (see + systemd.exec5 for + details). Takes one of , , , + , , , + . If the argument is omitted + systemd.default-standard-output= defaults to and + systemd.default-standard-error= to . @@ -1194,6 +995,188 @@ kernel-command-line7. + + Options + + systemd is only very rarely invoked directly, since it is started early and is + already running by the time users may interact with it. Normally, tools like + systemctl1 are used to + give commands to the manager. Since systemd is usually not invoked directly, the + options listed below are mostly useful for debugging and special purposes. + + + Introspection and debugging options + + Those options are used for testing and introspection, and systemd may + be invoked with them at any time: + + + + + + Dump understood unit configuration items. This outputs a terse but complete list of + configuration items understood in unit definition files. + + + + + + Dump exposed bus properties. This outputs a terse but complete list of properties + exposed on D-Bus. + + + + + + Determine the initial start-up transaction (i.e. the list of jobs enqueued at + start-up), dump it and exit — without actually executing any of the determined jobs. This option is + useful for debugging only. Note that during regular service manager start-up additional units not + shown by this operation may be started, because hardware, socket, bus or other kinds of activation + might add additional jobs as the transaction is executed. Use to request + the initial transaction of the system service manager (this is also the implied default), combine + with to request the initial transaction of the per-user service manager + instead. + + + + + + + When used in conjunction with , selects whether to calculate + the initial transaction for the system instance or for a per-user instance. These options have no + effect when invoked without , as during regular + (i.e. non-) invocations the service manager will automatically detect + whether it shall operate in system or per-user mode, by checking whether the PID it is run as is 1 + or not. Note that it is not supported booting and maintaining a system with the service manager + running in mode but with a PID other than 1. + + + + + + + + + Options that duplicate kernel command line settings + + Those options correspond directly to options listed above in "Kernel Command Line". Both forms + may be used equivalently for the system manager, but it is recommended to use the forms listed above in + this context, because they are properly namespaced. When an option is specified both on the kernel + command line, and as a normal command line argument, the latter has higher precedence. + + When systemd is used a user manager, the kernel command line is ignored and + the options described are understood. Nevertheless, systemd is usually started in + this mode through the + user@.service5 + service, which is shared between all users, and it may be more convenient to use configuration files to + modify settings, see + systemd-user.conf5, + or a drop-in that specifies one of the environment variables listed above in "Environment, see + systemd.unit5. + + + + + + Set default unit to activate on startup. If not specified, defaults to + default.target. See systemd.unit= above. + + + + + + Enable core dumping on crash. This switch has no effect when running as user + instance. Same as systemd.dump_core= above. + + + + VT + + Switch to a specific virtual console (VT) on crash. This switch has no effect when + running as user instance. Same as systemd.crash_chvt= above (but not the + different spelling!). + + + + + + Run a shell on crash. This switch has no effect when running as user instance. See + systemd.crash_shell= above. + + + + + + Automatically reboot the system on crash. This switch has no effect when running as + user instance. See systemd.crash_reboot above. + + + + + + Ask for confirmation when spawning processes. This switch has no effect when run as + user instance. See systemd.confirm_spawn above. + + + + + + Show terse unit status information is shown on the console during boot-up and + shutdown. See systemd.show_status above. + + + + + + Set log target. See systemd.log_target above. + + + + + + Set log level. See systemd.log_level above. + + + + + + Highlight important log messages. See systemd.log_color above. + + + + + + + Include code location in log messages. See systemd.log_location + above. + + + + + + Override the machine-id set on the hard drive. See + systemd.machine_id= above. + + + + + + Globally enable/disable all service watchdog timeouts and emergency actions. See + systemd.service_watchdogs above. + + + + + + + Sets the default output or error output for all services and sockets, + respectively. See systemd.default_standard_output= and + systemd.default_standard_error= above. + + + + + Sockets and FIFOs -- 2.47.3