X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemctl.xml;h=468141c2bde61a677a589fd34f7021e8752a45ca;hb=72b9ed828bd22f3ddd74b6853c183eebf006d6d8;hp=696a5060ad2173b8656b848489ac4eb4a8b5edbf;hpb=7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74;p=elogind.git
diff --git a/man/systemctl.xml b/man/systemctl.xml
index 696a5060a..468141c2b 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -21,7 +21,7 @@
along with systemd; If not, see .
-->
-
+systemctl
@@ -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.
@@ -70,14 +70,22 @@
-
+ Prints a short help
text and exits.
+
+
+
+ Prints a short version
+ string and exits.
+
+
+ When listing units,
limit display to certain unit
@@ -89,27 +97,113 @@
similar.
+
+
+
+
+ When showing
+ unit/job/manager properties, limit
+ display to certain properties as
+ specified as argument. If not
+ specified all set properties are
+ shown. The argument should be a
+ property name, such as
+ MainPID. If
+ specified more than once all
+ properties with the specified names
+ are shown.
+
+
+ When listing units,
show all units, regardless of their
- state, including inactive
- units.
+ state, including inactive units. When
+ 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
+ .
+
+
+
+
+
+ Do not ellipsize unit
+ names and truncate unit descriptions
+ in the output of
+ list-units and
+ list-jobs.
+
+
+
+ If the requested
- operation conflicts with an exisiting
- unfinished operation, replace the
- existing operation by the requested
- operation. If this is not specified
- the requested operation will
- fail.
+ operation conflicts with a pending
+ unfinished job, fail the command. If
+ this is not specified the requested
+ operation will replace the pending job,
+ 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 honoured. This is
+ mostly a debugging and rescue tool for
+ the administrator and should not be
+ used by
+ applications.
+
+
+
+
+
+
+ Suppress output to
+ STDOUT in
+ snapshot,
+ is-active,
+ enable and
+ disable.
+
+
+
+
+
+ Do not synchronously wait for
+ the requested operation to finish. If this is
+ not specified the job will be verified,
+ enqueued and systemctl will
+ wait until it is completed. By passing this
+ argument it is only verified and
+ enqueued.
+
+
+
+
+
+ Do not pipe output into a
+ pager.
+
+
@@ -118,18 +212,36 @@
-
+ Talk to the systemd
- session manager of the calling user.
+ manager of the calling user.
-
-
- Synchronously wait for
- the requested operation to
- finish.
+
+
+
+ When used in
+ conjunction with the
+ dot command (see
+ below), selects which dependencies are
+ shown in the dependency graph. If
+ is passed
+ only dependencies of type
+ After= or
+ Before= are
+ shown. If
+ is passed only dependencies of type
+ Requires=,
+ RequiresOverridable=,
+ Requisite=,
+ RequisiteOverridable=,
+ Wants= and
+ Conflicts= are
+ shown. If neither is passed, shows
+ dependencies of all these
+ types.
@@ -139,96 +251,188 @@
message before
halt, power-off, reboot.
-
- The following commands are understood:
+
+
+
+ When used with
+ enable and
+ disable, operate on the
+ global user configuration
+ directory, thus enabling or disabling
+ a unit file globally for all future
+ logins of all users.
+
-
- list-units
+
+
+ When used with
+ enable and
+ disable, do not
+ implicitly reload daemon configuration
+ after executing the
+ changes.
+
- List known units.
+
+
+
+ When used with
+ 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.
+
- list-jobs
+
+
+ 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
+ .
+
- List jobs that are in progress.
+
+
+
+
+ When used with
+ kill, choose which
+ signal to send to selected
+ processes. Must be one of the well
+ known signal specifiers such as
+ SIGTERM, SIGINT or SIGSTOP. If
+ omitted defaults to
+ .
+
+
+
+
+
+
+ When used with
+ enable, override any
+ existing conflicting
+ symlinks.
+
+ When used with
+ halt,
+ poweroff,
+ reboot or
+ kexec execute
+ 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.
+
- clear-jobs
+
- Cancel all jobs that are in progress.
+ When used with
+ enable/disable/is-enabled (and
+ related commands), use alternative
+ root path when looking for unit
+ files.
+
- load [NAME...]
+
+
+ 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.
+
- Load one or more units
- specified on the command line. This
- will simply load their configuration
- from disk, but not start them. To
- start them you need to use the
- start command which
- will implicitly load a unit that has
- not been loaded yet. Note that systemd
- garbage collects loaded units that are
- not active or referenced by an active
- unit. This means that units loaded
- this way will usually not stay loaded
- for long. Also note that this command
- cannot be used to reload unit
- configuration. Use the
- daemon-reload
- command for that. All in all this
- command is of little use except for
- debugging.
- This command should not be
- confused with the
- daemon-reload or
- reload
- commands.
+
+
+
+
+ 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.
- cancel [JOB...]
+
+
- Cancel one or more
- jobs specified on the command line by
- their numeric job
- IDs.
+ Acquire privileges via
+ PolicyKit before executing the
+ operation.
+
+
+ The following commands are understood:
+
+
- start [NAME...]
+ list-units
- Start one or more
- units specified on the command
- line.
+ List known units.
- stop [NAME...]
+ start [NAME...]
- Stop one or more units
- specified on the command
+ Start (activate) one
+ or more units specified on the command
line.
- restart [NAME...]
+ stop [NAME...]
- Restart one or more
- units specified on the command
+ Stop (deactivate) one
+ or more units specified on the command
line.reload [NAME...]
- Asks all services
- whose units are listed on the command
- line to reload their
+ Asks all units listed
+ on the command line to reload their
configuration. Note that this will
- reload the daemon configuration
- itself, not the unit configuration
- file of systemd. If you want systemd
- to reload the configuration file of a
- unit use the
+ reload the service-specific
+ configuration, not the unit
+ configuration file of systemd. If you
+ want systemd to reload the
+ configuration file of a unit use the
daemon-reload
command. In other words: for the
example case of Apache, this will
@@ -236,30 +440,401 @@
httpd.conf in the
web server, not the
apache.service
- systemd unit file. This
- command should not be confused with
- the daemon-reload
- or load
+ systemd unit file.
+
+ This command should not be
+ confused with the
+ daemon-reload or
+ load
commands.
+
+ restart [NAME...]
+
+ Restart one or more
+ units specified on the command
+ line. If the units are not running yet
+ they will be
+ started.
+
+
+ try-restart [NAME...]
+
+ Restart one or more
+ units specified on the command
+ 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. 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]Start the unit
specified on the command line and its
- dependencies and stop all
- others.
+ dependencies and stop all others.
+
+ This is similar to changing the
+ runlevel in a traditional init system. The
+ isolate command will
+ immediately stop processes that are not
+ enabled in the new unit, possibly including
+ the graphical environment or terminal you
+ are currently using.
+
+ Note that this works only on units
+ where is
+ enabled. See
+ systemd.unit5
+ for details.
+
+
+ kill [NAME...]
+
+ 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.
+
+
+ is-active [NAME...]
+
+ Check whether any of
+ the specified units are active
+ (i.e. running). Returns an exit code
+ 0 if at least one is active, non-zero
+ otherwise. Unless
+ is specified
+ this will also print the current unit
+ state to STDOUT.
+
+
+ status [NAME...|PID...]
+
+ 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.
+
+
+ show [NAME...|JOB...]
+
+ Show properties of one
+ or more units, jobs or the manager
+ itself. If no argument is specified
+ properties of the manager will be
+ shown. If a unit name is specified
+ properties of the unit is shown, and
+ if a job id is specified properties of
+ the job is shown. By default, empty
+ properties are suppressed. Use
+ to show those
+ too. To select specific properties to
+ show use
+ . This
+ command is intended to be used
+ whenever computer-parsable output is
+ required. Use
+ status if you are
+ looking for formatted human-readable
+ output.
+
+
+
+ reset-failed [NAME...]
+
+ Reset the
+ 'failed' state of the
+ specified units, or if no unit name is
+ passed of all units. When a unit fails
+ in some way (i.e. process exiting with
+ non-zero error code, terminating
+ abnormally or timing out) it will
+ automatically enter the
+ 'failed' state and
+ its exit code and status is recorded
+ for introspection by the administrator
+ until the service is restarted or
+ reset with this
+ command.
+
+
+
+ enable [NAME...]
+
+ Enable one or more
+ unit files, 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
+ 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.
+
+ This command will
+ print the actions executed. This
+ output may be suppressed by passing
+ .
+
+ Note that this operation creates
+ only the suggested symlinks for the
+ units. While this command is the
+ recommended way to manipulate the unit
+ configuration directory, the
+ administrator is free to make
+ additional changes manually, by
+ placing or removing symlinks in the
+ directory. This is particularly useful
+ to create configurations that deviate
+ from the suggested default
+ installation. In this case the
+ administrator must make sure to invoke
+ daemon-reload
+ manually as necessary, to ensure his
+ changes are taken into account.
+
+ Enabling units should not be
+ confused with starting (activating)
+ units, as done by the
+ start
+ command. Enabling and starting units
+ is orthogonal: units may be enabled
+ without being started and started
+ without being enabled. Enabling simply
+ hooks the unit into various suggested
+ places (for example, so that the unit
+ is automatically started on boot or
+ when a particular kind of hardware is
+ plugged in). Starting actually spawns
+ the daemon process (in case of service
+ units), or binds the socket (in case
+ of socket units), and so
+ on.
+
+ Depending on whether
+ ,
+ or
+ is specified
+ this enables the unit for the system,
+ 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.
+
+
+
+
+ disable [NAME...]
+
+ Disables one or more
+ units. This removes all symlinks to
+ the specified unit files from the unit
+ configuration directory, and hence
+ undoes the changes made by
+ enable. Note
+ however that this removes
+ all symlinks to the unit files
+ (i.e. including manual additions), not
+ just those actually created by
+ 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
+ is desired an additional
+ stopcommand should
+ be executed afterwards.
+
+ This command will print the
+ actions executed. This output may be
+ suppressed by passing
+ .
+
+
+ This command honors
+ ,
+ ,
+ in a similar
+ way as
+ enable.
+
+
+
+ is-enabled [NAME...]
+
+ Checks whether any of
+ the specified unit files is enabled
+ (as with
+ enable). Returns an
+ exit code of 0 if at least one is
+ 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 a
+ preset file. This has the same effect
+ as disable or
+ enable, depending
+ how the unit is listed in the preset
+ files.
+
+
+
+
+ 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.
+
+
+
+
+ load [NAME...]
+
+ Load one or more units
+ specified on the command line. This
+ will simply load their configuration
+ from disk, but not start them. To
+ start them you need to use the
+ start command which
+ will implicitly load a unit that has
+ not been loaded yet. Note that systemd
+ garbage collects loaded units that are
+ not active or referenced by an active
+ unit. This means that units loaded
+ this way will usually not stay loaded
+ for long. Also note that this command
+ cannot be used to reload unit
+ configuration. Use the
+ daemon-reload
+ command for that. All in all, this
+ command is of little use except for
+ debugging.
+ This command should not be
+ confused with the
+ daemon-reload or
+ reload
+ commands.
- monitor
+ list-jobs
- 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.
+ List jobs that are in progress.
+
+
+ cancel [JOB...]
+
+ Cancel one or more
+ jobs specified on the command line by
+ their numeric job
+ IDs. If no job id is specified, cancel all pending jobs.dump
@@ -272,20 +847,40 @@
be parsed by
applications.
+
+ dot
+
+ Generate textual
+ dependency graph description in dot
+ format for further processing with the
+ GraphViz
+ dot1
+ tool. Use a command line like
+ systemctl 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.
+ snapshot [NAME]Create a snapshot. If
- a snapshot name is specified the new
+ a snapshot name is specified, the new
snapshot will be named after it. If
none is specified an automatic
snapshot name is generated. In either
- case the snapshot name used is printed
- to STDOUT.
+ case, the snapshot name used is
+ printed to STDOUT, unless
+ is
+ specified.
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
@@ -301,6 +896,13 @@
state. Snapshots are dynamic and lost
on reboot.
+
+ delete [NAME...]
+
+ Remove a snapshot
+ previously created with
+ snapshot.
+ daemon-reload
@@ -308,7 +910,7 @@
configuration. This will reload all
unit files and recreate the entire
dependency tree. While the daemon is
- reloaded all sockets systemd listens
+ reloaded, all sockets systemd listens
on on behalf of user configuration will
stay accessible. This
command should not be confused with
@@ -333,16 +935,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
@@ -375,7 +967,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
@@ -383,7 +1002,14 @@
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.
poweroff
@@ -393,7 +1019,14 @@
equivalent to start
poweroff.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
+ powering off.
reboot
@@ -403,35 +1036,40 @@
equivalent to start
reboot.target but also
prints a wall message to all
- users.
-
-
- default
-
- Enter default
- mode. This is mostly equivalent to
- start
- default.target.
+ 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
+ kexec
- Enter rescue
- mode. This is mostly equivalent to
- isolate
- rescue.target but also
- prints a wall message to all
- users.
+ 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.
- emergency
+ exit
- Enter emergency
- mode. This is mostly equivalent to
- isolate
- emergency.service 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.
@@ -444,11 +1082,28 @@
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,
+ systemd-loginctl1,
systemd.unit5,
systemd.special7,
wall1