X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemctl.xml;h=338c1d3280a82cca9b186b6a66370d105de5bcc0;hb=657cf7f4f8d376e082db48022d2be193ff647d06;hp=d6d2c76f2eb9559ad02a8b847135499682a919ce;hpb=66f756d437658cc464bfb5647c97efd0cf77f933;p=elogind.git
diff --git a/man/systemctl.xml b/man/systemctl.xml
index d6d2c76f2..338c1d328 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1,24 +1,24 @@
-
+
.
Description
- systemctl may be used to
- introspect and control the state of the
+ systemctl may be used to introspect and
+ control the state of the systemd system and
+ service manager. Please refer to
systemd1
- system and service manager.
+ for an introduction into the basic concepts and functionality this
+ tool manages.
@@ -72,22 +74,6 @@ along with systemd; If not, see .
The following options are understood:
-
-
-
-
- Prints a short help
- text and exits.
-
-
-
-
-
-
- Prints a short version string and exits.
-
-
-
@@ -112,9 +98,10 @@ along with systemd; If not, see .
- The argument should be a comma-separated list of unit LOAD,
- SUB, or ACTIVE states. When listing units, show only those
- in specified states.
+ The argument should be a comma-separated list of unit
+ LOAD, SUB, or ACTIVE states. When listing units, show only
+ those in specified states. Use
+ to show only failed units.
@@ -147,26 +134,64 @@ along with systemd; If not, see .
+
+
+
+
+
+ When listing units, also show units of local
+ containers. Units of local containers will be prefixed with
+ the container name, separated by a single colon character
+ (:).
+
+
+
Show reverse dependencies between units with
- list-dependencies, i.e. units with
- dependencies of type Wants= or
- Requires= on the given unit.
+ list-dependencies, i.e. follow
+ dependencies of type WantedBy=,
+ RequiredBy=,
+ RequiredByOverrridable=,
+ PartOf=, BoundBy=,
+ instead of Wants= and similar.
+
+
+ With list-dependencies, show the
+ units that are ordered before the specified unit. In other
+ words, recursively list units following the
+ After= dependency.
+
+ Note that any After= dependency is
+ automatically mirrored to create a
+ Before= dependency. Temporal dependencies
+ may be specified explicitly, but are also created implicitly
+ for units which are WantedBy= targets
+ (see
+ systemd.target5),
+ and as a result of other directives (for example
+ RequiresMountsFor=). Both explicitly
+ and implicitly introduced dependencies are shown with
+ list-dependencies.
+
+
+
+
- Show which units are started after or before
- with list-dependencies, respectively.
-
+ With list-dependencies, show the
+ units that are ordered after the specified unit. In other
+ words, recursively list units following the
+ Before= dependency.
@@ -219,8 +244,10 @@ along with systemd; If not, see .
If replace-irreversibly is specified,
operate like replace, but also mark the new
jobs as irreversible. This prevents future conflicting
- transactions from replacing these jobs. The jobs can still be
- cancelled using the cancel command.
+ transactions from replacing these jobs (or even being enqueued
+ while the irreversible jobs are still pending). Irreversible
+ jobs can still be cancelled using the cancel
+ command.
isolate is only valid for start
operations and causes all other units to be stopped when the
@@ -275,6 +302,8 @@ along with systemd; If not, see .
snapshot,
is-active,
is-failed,
+ is-enabled,
+ is-system-running,
enable and
disable.
@@ -292,39 +321,13 @@ along with systemd; If not, see .
-
-
+
+
-
- Do not print the legend, i.e. the column headers and
- the footer with hints.
-
-
-
-
-
-
-
- Do not pipe output into a pager.
-
-
-
-
-
-
-
- Talk to the systemd system manager. (Default)
-
-
-
-
-
-
-
- Talk to the systemd manager of the calling
- user.
-
-
+
@@ -374,7 +377,6 @@ along with systemd; If not, see .
querying the user for authentication for privileged
operations.
-
@@ -382,11 +384,36 @@ along with systemd; If not, see .
When used with kill, choose which
- processes to kill. Must be one of ,
- or to select
- whether to kill only the main process of the unit, the
- control process or all processes of the unit. If omitted,
- defaults to .
+ processes to send a signal to. Must be one of
+ , or
+ to select whether to kill only the main
+ process, the control process or all processes of the
+ unit. The main process of the unit is the one that defines
+ the life-time of it. A control process of a unit is one that
+ is invoked by the manager to induce state changes of it. For
+ example, all processes started due to the
+ ExecStartPre=,
+ ExecStop= or
+ ExecReload= settings of service units are
+ control processes. Note that there is only one control
+ process per unit at a time, as only one state change is
+ executed at a time. For services of type
+ Type=forking, the initial process started
+ by the manager for ExecStart= is a
+ control process, while the process ultimately forked off by
+ that one is then considered the main process of the unit (if
+ it can be determined). This is different for service units
+ of other types, where the process forked off by the manager
+ for ExecStart= is always the main process
+ itself. A service unit consists of zero or one main process,
+ zero or one control process plus any number of additional
+ processes. Not all unit types manage processes of these
+ types however. For example, for mount units, control processes
+ are defined (which are the invocations of
+ /usr/bin/mount and
+ /usr/bin/umount), but no main process
+ is defined. If omitted, defaults to
+ .
@@ -421,7 +448,7 @@ along with systemd; If not, see .
safe option to request an immediate reboot. If
is specified twice for these
operations, they will be executed immediately without
- terminating any processes or umounting any file
+ terminating any processes or unmounting any file
systems. Warning: specifying twice
with any of these operations might result in data
loss.
@@ -445,7 +472,7 @@ along with systemd; If not, see .
When used with enable,
- disable,
+ disable, edit,
(and related commands), make changes only temporarily, so
that they are lost on the next reboot. This will have the
effect that changes are not made in subdirectories of
@@ -461,26 +488,19 @@ along with systemd; If not, see .
-
-
+
- Execute the operation remotely. Specify a hostname, or
- username and hostname separated by @, to
- connect to. This will use SSH to talk to the remote systemd
- instance.
+ Takes one of full (the default),
+ enable-only,
+ disable-only. When used with the
+ preset or preset-all
+ commands, controls whether units shall be disabled and
+ enabled according to the preset rules, or only enabled, or
+ only disabled.
-
-
-
-
- Execute the operation on a local
- container. Specify a container name to connect
- to.
-
-
@@ -515,6 +535,13 @@ along with systemd; If not, see .
+
+
+
+
+
+
+
@@ -561,7 +588,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
See also the options ,
- , and .
+ , and .
@@ -575,7 +602,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
See also the options and
- .
+ .
@@ -620,8 +647,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
file.
This command should not be confused with the
- daemon-reload or load
- commands.
+ daemon-reload command.
@@ -670,7 +696,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
Start the unit specified on the command line and its
- dependencies and stop all others.
+ dependencies and stop all others. If a unit name with no
+ extension is given, an extension of
+ .target will be assumed.
This is similar to changing the runlevel in a
traditional init system. The isolate
@@ -690,9 +718,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
Send a signal to one or more processes of the
unit. Use to select which
- process to kill. Use to select
- the kill mode and to select the
- signal to send.
+ process to kill. Use to select
+ the signal to send.
@@ -725,10 +752,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
Show terse runtime status information about one or
more units, followed by most recent log data from the
- journal. If no units are specified, show all units (subject
- to limitations specified with ). If a PID
- is passed, show information about the unit the process
- belongs to.
+ journal. If no units are specified, show system status. If
+ combined with , also show the status of
+ all units (subject to limitations specified with
+ ). If a PID is passed, show information
+ about the unit the process belongs to.
This function is intended to generate human-readable
output. If you are looking for computer-parsable output,
@@ -824,15 +852,30 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
- list-dependencies NAME
+
+ list-dependencies
+ NAME
+
- Shows required and wanted units of the specified
- unit. If no unit is specified,
- default.target is implied. Target units
- are recursively expanded. When is
- passed, all other units are recursively expanded as
- well.
+ Shows units required and wanted by the specified
+ unit. This recursively lists units following the
+ Requires=,
+ RequiresOverridable=,
+ Requisite=,
+ RequisiteOverridable=,
+ Wants=, BindsTo=
+ dependencies. If no unit is specified,
+ default.target is implied.
+
+ By default, only target units are recursively
+ expanded. When is passed, all other
+ units are recursively expanded as well.
+
+ Options ,
+ ,
+ may be used to change what types of dependencies
+ are shown.
@@ -906,6 +949,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
the system, or for all future logins of all users, or only this
boot. Note that in the last case, no systemd daemon
configuration is reloaded.
+
+ Using enable on masked units
+ results in an error.
@@ -937,6 +983,56 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
+
+ reenable NAME...
+
+
+ Reenable one or more unit files, as specified on the
+ command line. This is a combination of
+ disable and enable and
+ is useful to reset the symlinks a unit is enabled with to
+ the defaults configured in the [Install]
+ section of the unit file.
+
+
+
+
+ preset NAME...
+
+
+ Reset one or more unit files, as specified on the
+ command line, to the defaults configured in the preset
+ policy files. This has the same effect as
+ disable or enable,
+ depending how the unit is listed in the preset files.
+
+ Use to control
+ whether units shall be enabled and disabled, or only
+ enabled, or only disabled.
+
+ For more information on the preset policy format,
+ see
+ systemd.preset5.
+ For more information on the concept of presets, please
+ consult the Preset
+ document.
+
+
+
+
+ preset-all
+
+
+ Resets all installed unit files to the defaults
+ configured in the preset policy file (see above).
+
+ Use to control
+ whether units shall be enabled and disabled, or only
+ enabled, or only disabled.
+
+
+
is-enabled NAME...
@@ -964,7 +1060,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
enabled
- Enabled through a symlink in .wants directory (permanently or just in /run)
+ Enabled through a symlink in .wants directory (permanently or just in /run).0
@@ -972,7 +1068,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
linked
- Made available through a symlink to the unit file (permanently or just in /run)
+ Made available through a symlink to the unit file (permanently or just in /run).1
@@ -980,7 +1076,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
masked
- Disabled entirely (permanently or just in /run)
+ Disabled entirely (permanently or just in /run).1
@@ -988,12 +1084,17 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
static
- Unit is not enabled, but has no provisions for enabling in [Install] section
+ Unit file is not enabled, and has no provisions for enabling in the [Install] section.
+ 0
+
+
+ indirect
+ Unit file itself is not enabled, but it has a non-empty Also= setting in the [Install] section, listing other unit files that might be enabled.0disabled
- Unit is not enabled
+ Unit file is not enabled.1
@@ -1003,37 +1104,6 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
-
- reenable NAME...
-
-
- Reenable one or more unit files, as specified on the
- command line. This is a combination of
- disable and enable and
- is useful to reset the symlinks a unit is enabled with to
- the defaults configured in the [Install]
- section of the unit file.
-
-
-
-
- preset NAME...
-
-
- Reset one or more unit files, as specified on the
- command line, to the defaults configured in the preset
- policy files. This has the same effect as
- disable or enable,
- depending how the unit is listed in the preset files. For
- more information on the preset policy format, see
- systemd.preset5.
- For more information on the concept of presets, please
- consult the
- Preset
- document.
-
-
-
mask NAME...
@@ -1043,10 +1113,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
/dev/null, making it impossible to
start them. This is a stronger version of
disable, since it prohibits all kinds of
- activation of the unit, including manual activation. Use
- this option with care. This honors the
+ activation of the unit, including enablement and manual
+ activation. Use this option with care. This honors the
option to only mask temporarily
- until the next reoobt of the system.
+ until the next reboot of the system.
@@ -1074,12 +1144,69 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
+
+ add-wants TARGET
+ NAME...
+ add-requires TARGET
+ NAME...
+
+
+ Adds Wants= resp. Requires=
+ dependency to the specified TARGET for
+ one or more units.
+
+ This command honors ,
+ , and
+ in a similar way as
+ enable.
+
+
+
+
+
+ edit NAME...
+
+
+ Edit a drop-in snippet or a whole replacement file if
+ is specified, to extend or override the
+ specified unit.
+
+ Depending on whether (the default),
+ , or is specified,
+ this creates a drop-in file for each unit either for the system,
+ for the calling user or for all futures logins of all users. Then,
+ the editor (see the "Environment" section below) is invoked on
+ temporary files which will be written to the real location if the
+ editor exits successfully.
+
+ If is specified, this will copy the
+ original units instead of creating drop-in files.
+
+ If is specified, the changes will
+ be made temporarily in /run and they will be
+ lost on the next reboot.
+
+ If the temporary file is empty upon exit the modification of
+ the related unit is canceled
+
+ After the units have been edited, systemd configuration is
+ reloaded (in a way that is equivalent to daemon-reload).
+
+
+ Note that this command cannot be used to remotely edit units
+ and that you cannot temporarily edit units which are in
+ /etc since they take precedence over
+ /run.
+
+
+
get-default
- Get the default target specified
- via default.target link.
+ Return the default target to boot into. This returns
+ the target unit name default.target
+ is aliased (symlinked) to.
@@ -1087,8 +1214,28 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
set-default NAME
- Set the default target to boot into. Command links
- default.target to the given unit.
+ Set the default target to boot into. This sets
+ (symlinks) the default.target alias
+ to the given target unit.
+
+
+
+
+
+
+
+ Machine Commands
+
+
+
+ list-machines PATTERN...
+
+
+ List the host and all running local containers with
+ their state. If one or more
+ PATTERNs are specified, only
+ containers matching one of them are shown.
+
@@ -1194,7 +1341,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
- import-environment VARIABLE...
+
+ import-environment
+ VARIABLE...
+ Import all, one or more environment variables set on
@@ -1217,13 +1367,16 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
daemon-reload
- Reload systemd manager configuration. This will reload
- all unit files and recreate the entire dependency
- tree. While the daemon is being reloaded, all sockets systemd
- listens on on behalf of user configuration will stay
- accessible.This command should not be confused
- with the load or
- reload commands.
+ Reload systemd manager configuration. This will
+ rerun all generators (see
+ systemd.generator7),
+ reload all unit files, and recreate the entire dependency
+ tree. While the daemon is being reloaded, all sockets
+ systemd listens on behalf of user configuration will stay
+ accessible.
+
+ This command should not be confused with the
+ reload command.
@@ -1247,6 +1400,69 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
System Commands
+
+ is-system-running
+
+
+ Checks whether the system is operational. This
+ returns success when the system is fully up and running,
+ meaning not in startup, shutdown or maintenance
+ mode. Failure is returned otherwise. In addition, the
+ current state is printed in a short string to standard
+ output, see table below. Use to
+ suppress this output.
+
+
+ Manager Operational States
+
+
+
+
+
+ Name
+ Description
+
+
+
+
+ initializing
+ Early bootup, before
+ basic.target is reached
+ or the maintenance state entered.
+
+
+
+ starting
+ Late bootup, before the job queue
+ becomes idle for the first time, or one of the
+ rescue targets are reached.
+
+
+ running
+ The system is fully
+ operational.
+
+
+ degraded
+ The system is operational but one or more
+ units failed.
+
+
+ maintenance
+ The rescue or emergency target is
+ active.
+
+
+ stopping
+ The manager is shutting
+ down.
+
+
+
+
+
+
+
default
@@ -1255,6 +1471,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
isolate default.target.
+
rescue
@@ -1331,6 +1548,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
firmware over the air update.
+
kexec
@@ -1344,6 +1562,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
immediately followed by the reboot.
+
exit
@@ -1353,8 +1572,29 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
with the option) and will fail
otherwise.
+
+
+ switch-root ROOTINIT
+
+
+ Switches to a different root directory and executes a
+ new system manager process below it. This is intended for
+ usage in initial RAM disks ("initrd"), and will transition
+ from the initrd's system manager process (a.k.a "init"
+ process) to the main system manager process. This call takes two
+ arguments: the directory that is to become the new root directory, and
+ the path to the new system manager binary below it to
+ execute as PID 1. If the latter is omitted or the empty
+ string, a systemd binary will automatically be searched for
+ and used as init. If the system manager path is omitted or
+ equal to the empty string, the state of the initrd's system
+ manager process is passed to the main system manager, which
+ allows later introspection of the state of the services
+ involved in the initrd boot.
+
+
suspend
@@ -1364,6 +1604,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
+
hibernate
@@ -1373,6 +1614,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
+
hybrid-sleep
@@ -1382,33 +1624,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
hybrid-sleep.target target.
-
- switch-root ROOTINIT
-
-
- Switches to a different root directory and executes a
- new system manager process below it. This is intended for
- usage in initial RAM disks ("initrd"), and will transition
- from the initrd's system manager process (a.k.a "init"
- process) to the main system manager process. This call takes two
- arguments: the directory that is to become the new root directory, and
- the path to the new system manager binary below it to
- execute as PID 1. If the latter is omitted or the empty
- string, a systemd binary will automatically be searched for
- and used as init. If the system manager path is omitted or
- equal to the empty string, the state of the initrd's system
- manager process is passed to the main system manager, which
- allows later introspection of the state of the services
- involved in the initrd boot.
-
- Parameter Syntax
- Unit ommands listed above take either a single unit name
+ Unit commands listed above take either a single unit name
(designated as NAME), or multiple
unit specifications (designated as
PATTERN...). In the first case, the
@@ -1420,9 +1642,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
# systemctl start sshd and
# systemctl start sshd.service
are equivalent, as are
- # systemctl isolate snapshot-11
+ # systemctl isolate default
and
- # systemctl isolate snapshot-11.snapshot
+ # systemctl isolate default.target
Note that (absolute) paths to device nodes are automatically
converted to device unit names, and other (absolute) paths to
mount unit names.
@@ -1438,11 +1660,11 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
may match zero units and this is not considered an error.Glob patterns use
- fnmatch3,
+ fnmatch3,
so normal shell-style globbing rules are used, and
*, ?,
[] may be used. See
- glob7
+ glob7
for more details. The patterns are matched against the names of
currently loaded units, and patterns which do not match anything
are silently skipped. For example:
@@ -1468,21 +1690,43 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
code otherwise.
-
+
+ Environment
+
+
+
+ $SYSTEMD_EDITOR
+
+ Editor to use when editing units; overrides
+ $EDITOR and $VISUAL. If neither
+ $SYSTEMD_EDITOR nor $EDITOR nor
+ $VISUAL are present or if it is set to an empty
+ string or if their execution failed, systemctl will try to execute well
+ known editors in this order:
+ nano1,
+ vim1,
+ vi1.
+
+
+
+
+
+ See Alsosystemd1,
- systemadm1,
journalctl1,
loginctl1,
+ machinectl1,
systemd.unit5,
systemd.resource-management5,
systemd.special7,
- wall1,
- systemd.preset5
- glob7
+ wall1,
+ systemd.preset5,
+ systemd.generator7,
+ glob7