X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemctl.xml;h=62446d7a5747b407858870dc31a6ccdc34c98db4;hb=7a529f63e60dfdccc23d61808c20ba40d9901e47;hp=ca654ca5bc232e56ac17a52cb13c074413e8ef09;hpb=8a0867d6c5b47c8697d1ddd815116a548433c718;p=elogind.git
diff --git a/man/systemctl.xml b/man/systemctl.xml
index ca654ca5b..62446d7a5 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -8,16 +8,16 @@
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see .
-->
@@ -44,7 +44,7 @@
systemctl
- Control the systemd system and session manager
+ Control the systemd system and service manager
@@ -59,7 +59,7 @@
systemctl may be used to
introspect and control the state of the
systemd1
- system and session manager.
+ system and service manager.
@@ -76,18 +76,42 @@
text and exits.
+
+
+
+ Prints a short version
+ string and exits.
+
+
- When listing units,
- limit display to certain unit
- types. If not specified units of all
- types will be shown. The argument
- should be a unit type name such as
- ,
- and
- similar.
+ The argument should
+ be a unit type name such as
+ and
+ ,
+ or a unit load state such as
+ and
+ .
+
+
+ If the argument is a unit type,
+ when listing units, limit display to
+ certain unit types. If not specified
+ units of all types will be shown.
+
+ If the argument is a unit load state,
+ when listing units, limit display to
+ certain unit types. If not specified
+ units of in all load states will be
+ shown.
+
+ As a special case, if the argument
+ is , a list of
+ allowed values will be printed and the
+ program will exit.
+
@@ -95,7 +119,7 @@
When showing
- unit/job/manager information, limit
+ unit/job/manager properties, limit
display to certain properties as
specified as argument. If not
specified all set properties are
@@ -114,11 +138,20 @@
When listing units,
show all units, regardless of their
state, including inactive units. When
- showing unit/job/manager information,
+ showing unit/job/manager properties,
show all properties regardless whether
they are set or not.
+
+
+
+ When listing units,
+ show only failed units. Do not confuse
+ with
+ .
+
+
@@ -137,7 +170,24 @@
unfinished job, fail the command. If
this is not specified the requested
operation will replace the pending job,
- if necessary.
+ if necessary. Do not confuse
+ with
+ .
+
+
+
+
+
+ When enqueuing a new
+ job ignore all its dependencies and
+ execute it immediately. If passed no
+ required units of the unit passed will
+ be pulled in, and no ordering
+ dependencies will be honored. This is
+ mostly a debugging and rescue tool for
+ the administrator and should not be
+ used by
+ applications.
@@ -147,7 +197,7 @@
Suppress output to
STDOUT in
snapshot,
- check,
+ is-active,
enable and
disable.
@@ -161,7 +211,23 @@
enqueued and systemctl will
wait until it is completed. By passing this
argument it is only verified and
- enqueued.
+ enqueued.
+
+
+
+
+
+ Do not print a legend, i.e.
+ the column headers and the footer with hints.
+
+
+
+
+
+
+ Do not pipe output into a
+ pager.
+
@@ -171,10 +237,10 @@
-
+ Talk to the systemd
- session manager of the calling user.
+ manager of the calling user.
@@ -217,10 +283,10 @@
When used with
enable and
disable, operate on the
- global session configuŕation
+ global user configuration
directory, thus enabling or disabling
a unit file globally for all future
- sessions of all users.
+ logins of all users.
@@ -235,24 +301,28 @@
-
+ When used with
- kill, choose the
- mode how to kill the selected
- processes. Must be one of
- ,
- or
- to select
- whether to kill the entire control
- group, the process group or only the
- selected process itself. If ommitted
- defaults to
- if
- is
- set, or
- otherwise. You probably never need to
- use this switch.
+ start and related
+ commands, disables asking for
+ passwords. Background services may
+ require input of a password or
+ passphrase string, for example to
+ unlock system hard disks or
+ cryptographic certificates. Unless
+ this option is specified and the
+ command is invoked from a terminal
+ systemctl will
+ query the user on the terminal for the
+ necessary secrets. Use this option to
+ switch this behavior off. In this case
+ the password must be supplied by some
+ other means (for example graphical
+ password agents) or the service might
+ fail. This also disables querying the
+ user for authentication for privileged
+ operations.
@@ -266,45 +336,131 @@
to select whether
to kill only the main process of the
unit, the control process or all
- processes of the unit. If ommitted
+ processes of the unit. If omitted
defaults to
.
-
+ When used with
kill, choose which
signal to send to selected
processes. Must be one of the well
- know signal specifiers such as
+ known signal specifiers such as
SIGTERM, SIGINT or SIGSTOP. If
- ommitted defaults to
+ omitted defaults to
.
+ When used with
- enable, override any
+ enable, overwrite any
existing conflicting
symlinks.
+
+ When used with
+ halt,
+ poweroff,
+ reboot or
+ kexec execute the
+ selected operation without shutting
+ down all units. However, all processes
+ will be killed forcibly and all file
+ systems are unmounted or remounted
+ read-only. This is hence a drastic but
+ relatively 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 systems. Warning: specifying
+ twice with
+ any of these operations might result
+ in data loss.
+
+
+
+
+
+ When used with
+ enable/disable/is-enabled (and
+ related commands), use alternative
+ root path when looking for unit
+ files.
+
+
+
+
+
+ When used with
+ enable/disable/is-enabled (and related commands), make
+ changes only temporarily, so that they
+ are dropped on the next reboot. This
+ will have the effect that changes are
+ not made in subdirectories of
+ /etc but in
+ /run, with
+ identical immediate effects, however,
+ since the latter is lost on reboot,
+ the changes are lost
+ too.
+
+
+
+
+
+
+ Execute 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.
+
+
+
+
+
+
+ Acquire privileges via
+ PolicyKit before executing the
+ operation.
-
+
+ When used with
- disable, ensures
- that only the symlinks created by
- enable are removed,
- not all symlinks pointing to the unit
- file that shall be
- disabled.
+ status controls the
+ number of journal lines to show,
+ counting from the most recent
+ ones. Takes a positive integer
+ argument. Defaults to
+ 10.
+
+
+
+
+
+ When used with
+ status controls the
+ formatting of the journal entries that
+ are shown. For the available choices
+ see
+ journalctl1. Defaults
+ to
+ short.
+
+
The following commands are understood:
@@ -370,23 +526,34 @@
Restart one or more
units specified on the command
- line. If the units are not running yet
- the operation will
- fail.
+ line if the units are running. Do
+ nothing if units are not running.
+ Note that for compatibility
+ with Red Hat init scripts
+ condrestart is
+ equivalent to this command.
reload-or-restart [NAME...]
+
+ Reload one or more
+ units if they support it. If not,
+ restart them instead. If the units
+ are not running yet they will be
+ started.
+
+ reload-or-try-restart [NAME...]Reload one or more
units if they support it. If not,
- restart them instead. Note that for
- compatibility with SysV and Red Hat
- init scripts
- force-reload and
- condrestart may be
- used as equivalent commands to
- reload-or-try-restart.
+ restart them instead. Do nothing if
+ the units are not running. Note that
+ for compatibility with SysV init
+ scripts
+ force-reload is
+ equivalent to this
+ command.
isolate [NAME]
@@ -425,7 +592,7 @@
is-active [NAME...]Check whether any of
- the specified units is active
+ the specified units are active
(i.e. running). Returns an exit code
0 if at least one is active, non-zero
otherwise. Unless
@@ -438,14 +605,15 @@
Show terse runtime
status information about one or more
- units. This function is intended to
- generate human-readable output. If you
- are looking for computer-parsable
- output, use show
- instead. If a PID is passed
- information about the unit the process
- of the PID belongs to is
- shown.
+ units, followed by its most recent log
+ data from the journal. This function
+ is intended to generate human-readable
+ output. If you are looking for
+ computer-parsable output, use
+ show instead. If a
+ PID is passed information about the
+ unit the process of the PID belongs to
+ is shown.show [NAME...|JOB...]
@@ -470,7 +638,15 @@
looking for formatted human-readable
output.
+
+ help [NAME...|PID...]
+ Show manual pages for
+ one or more units, if available. If a
+ PID is passed the manual pages for the
+ unit the process of the PID belongs to
+ is shown.
+ reset-failed [NAME...]
@@ -490,27 +666,39 @@
command.
+
+ list-unit-files
+
+ List installed unit files.
+
+
+
enable [NAME...]
- Enable one or more
- unit files, as specified on the
+ Enable one or
+ more unit files or unit file
+ instances, as specified on the
command line. This will create a
- number of symlinks as encoded in the
- [Install] sections
- of the unit files. After the symlinks
- have been created the systemd
- configuration is reloaded (in a way
- that is equivalent to
- daemon-reload) to
- ensure the changes are taken into
+ number of symlinks as encoded in
+ the [Install]
+ sections of the unit files. After
+ the symlinks have been created the
+ systemd configuration is reloaded
+ (in a way that is equivalent to
+ daemon-reload)
+ to ensure the changes are taken into
account immediately. Note that this
does not have the effect that any of
the units enabled are also started at
- the same time. If this is desired a
- separate start
- command must be invoked for the
- unit.
+ the same time. If this is desired
+ a separate start
+ command must be invoked for the unit.
+ Also note that in case of instance
+ enablement, symlinks named same as
+ instances are created in install
+ location, however they all point to
+ the same template unit file.This command will
print the actions executed. This
@@ -525,7 +713,7 @@
administrator is free to make
additional changes manually, by
placing or removing symlinks in the
- directory. This is particular useful
+ directory. This is particularly useful
to create configurations that deviate
from the suggested default
installation. In this case the
@@ -554,11 +742,11 @@
Depending on whether
,
- or
+ or
is specified
this enables the unit for the system,
- for sessions of the calling user only
- or for all future session of all
+ for the calling user only
+ or for all future logins of all
users. Note that in the latter case no
systemd daemon configuration is
reloaded.
@@ -574,21 +762,18 @@
configuration directory, and hence
undoes the changes made by
enable. Note
- however that this by default removes
+ however that this removes
all symlinks to the unit files
(i.e. including manual additions), not
just those actually created by
- enable. If only the
- symlinks that are suggested by default
- shall be removed, pass
- . This
+ enable. This call
implicitly reloads the systemd daemon
configuration after completing the
disabling of the units. Note that this
command does not implicitly stop the
- units that is being disabled. If this
+ units that are being disabled. If this
is desired an additional
- stopcommand should
+ stop command should
be executed afterwards.This command will print the
@@ -597,9 +782,9 @@
.
- This command honours
+ This command honors
,
- ,
+ ,
in a similar
way as
enable.
@@ -609,12 +794,96 @@
is-enabled [NAME...]Checks whether any of
- the specified unit files is enabled
+ the specified unit files are enabled
(as with
enable). Returns an
exit code of 0 if at least one is
- enabled, non-zero
- otherwise.
+ enabled, non-zero otherwise. Prints
+ the current enable status. To suppress
+ this output use
+ .
+
+
+
+ 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 preset
+ policy format see
+ systemd.preset5. For
+ more information on the concept of
+ presets please consult the Preset
+ document.
+
+
+
+
+ mask [NAME...]
+
+ Mask one or more unit
+ files, as specified on the command
+ line. This will link these units to
+ /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.
+
+
+
+
+ unmask [NAME...]
+
+ Unmask one or more
+ unit files, as specified on the
+ command line. This will undo the
+ effect of
+ mask.
+
+
+
+
+ link [NAME...]
+
+ Link a unit file that
+ is not in the unit file search paths
+ into the unit file search path. This
+ requires an absolute path to a unit
+ file. The effect of this can be undone
+ with disable. The
+ effect of this command is that a unit
+ file is available for
+ start and other
+ commands although it isn't installed
+ directly in the unit search
+ path.
+
@@ -656,17 +925,7 @@
Cancel one or more
jobs specified on the command line by
their numeric job
- IDs. If not job id is specified cancels all jobs that are pending.
-
-
- monitor
-
- Monitor unit/job
- changes. This is mostly useful for
- debugging purposes and prints a line
- each time systemd loads or unloads a
- unit configuration file, or a unit
- property changes.
+ IDs. If no job id is specified, cancel all pending jobs.
dump
@@ -712,7 +971,7 @@
A snapshot refers to a saved
state of the systemd manager. It is
- implemented itself as unit that is
+ implemented itself as a unit that is
generated dynamically with this
command and has dependencies on all
units active at the time. At a later
@@ -767,16 +1026,6 @@
configuration will stay
accessible.
-
- daemon-exit
-
- Ask the systemd
- manager to quit. This is only
- supported for session managers
- (i.e. in conjunction with the
- option) and
- will fail otherwise.
- show-environment
@@ -809,7 +1058,34 @@
is only removed if it has the
specified value.
+
+ default
+ Enter default
+ mode. This is mostly equivalent to
+ start
+ default.target.
+
+
+ rescue
+
+ Enter rescue
+ mode. This is mostly equivalent to
+ isolate
+ rescue.target but also
+ prints a wall message to all
+ users.
+
+
+ emergency
+
+ Enter emergency
+ mode. This is mostly equivalent to
+ isolate
+ emergency.target but also
+ prints a wall message to all
+ users.
+ halt
@@ -817,7 +1093,19 @@
system. This is mostly equivalent to
start halt.target
but also prints a wall message to all
- users.
+ users. If combined with
+ shutdown of
+ all running services is skipped,
+ however all processes are killed and
+ all file systems are unmounted or
+ mounted read-only, immediately
+ followed by the system halt. If
+ is specified
+ twice the operation is immediately
+ executed without terminating any
+ processes or unmounting any file
+ systems. This may result in data
+ loss.
poweroff
@@ -826,46 +1114,120 @@
power-off the system. This is mostly
equivalent to start
poweroff.target but also
- prints a wall message to all
- users.
+ prints a wall message to all users. If
+ combined with
+ shutdown of all running services is
+ skipped, however all processes are
+ killed and all file systems are
+ unmounted or mounted read-only,
+ immediately followed by the powering
+ off. If is
+ specified twice the operation is
+ immediately executed without
+ terminating any processes or
+ unmounting any file systems. This may
+ result in data loss.
reboot
- Shut down and
- reboot the system. This is mostly
- equivalent to start
+ Shut down and reboot
+ the system. This is mostly equivalent
+ to start
reboot.target but also
- prints a wall message to all
- users.
+ prints a wall message to all users. If
+ combined with
+ shutdown of all running services is
+ skipped, however all processes are
+ killed and all file systems are
+ unmounted or mounted read-only,
+ immediately followed by the reboot. If
+ is specified
+ twice the operation is immediately
+ executed without terminating any
+ processes or unmounting any file
+ systems. This may result in data
+ loss.
- default
+ kexec
- Enter default
- mode. This is mostly equivalent to
- start
- default.target.
+ Shut down and reboot
+ the system via kexec. This is mostly
+ equivalent to start
+ kexec.target but also prints
+ a wall message to all users. If
+ combined with
+ shutdown of all running services is
+ skipped, however all processes are killed
+ and all file systems are unmounted or
+ mounted read-only, immediately
+ followed by the
+ reboot.
- rescue
+ exit
- Enter rescue
- mode. This is mostly equivalent to
- isolate
- rescue.target but also
- prints a wall message to all
- users.
+ Ask the systemd
+ manager to quit. This is only
+ supported for user service managers
+ (i.e. in conjunction with the
+ option) and
+ will fail otherwise.
- emergency
+ suspend
- Enter emergency
- mode. This is mostly equivalent to
- isolate
- emergency.target but also
- prints a wall message to all
- users.
+ Suspend the
+ system. This will trigger activation
+ of the special
+ suspend.target
+ target.
+
+
+ hibernate
+
+ Hibernate the
+ system. This will trigger activation
+ of the special
+ hibernate.target
+ target.
+
+
+ hybrid-sleep
+
+ Hibernate and suspend
+ the system. This will trigger
+ activation of the special
+ hybrid-sleep.target
+ target.
+
+
+ switch-root [ROOT] [INIT]
+
+ 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. Takes two arguments: the
+ directory to make 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 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.
@@ -878,14 +1240,33 @@
code otherwise.
+
+ Environment
+
+
+
+ $SYSTEMD_PAGER
+ Pager to use when
+ is not given;
+ overrides $PAGER. Setting
+ this to an empty string or the value
+ cat is equivalent to passing
+ .
+
+
+
+
See Alsosystemd1,
systemadm1,
+ journalctl1,
+ loginctl1,
systemd.unit5,
systemd.special7,
- wall1
+ wall1,
+ systemd.preset5