Add systemd with tizen patches

[external/systemd.git] / man / systemctl.1

'\" t
.\"     Title: systemctl
.\"    Author: Lennart Poettering <lennart@poettering.net>
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 02/15/2012
.\"    Manual: systemctl
.\"    Source: systemd
.\"  Language: English
.\"
.TH "SYSTEMCTL" "1" "02/15/2012" "systemd" "systemctl"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemctl \- Control the systemd system and service manager
.SH "SYNOPSIS"
.HP \w'\fBsystemctl\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB{COMMAND}\fR\fB\ \fR\fB[NAME...]\fR\ 'u
\fBsystemctl \fR\fB[OPTIONS...]\fR\fB \fR\fB{COMMAND}\fR\fB \fR\fB[NAME...]\fR
.SH "DESCRIPTION"
.PP
\fBsystemctl\fR
may be used to introspect and control the state of the
\fBsystemd\fR(1)
system and service manager\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-help\fR, \fB\-h\fR
.RS 4
Prints a short help text and exits\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Prints a short version string and exits\&.
.RE
.PP
\fB\-\-type=\fR, \fB\-t\fR
.RS 4
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
\fBservice\fR,
\fBsocket\fR
and similar\&.
.RE
.PP
\fB\-\-property=\fR, \fB\-p\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-all\fR, \fB\-a\fR
.RS 4
When listing units, show all units, regardless of their state, including inactive units\&. When showing unit/job/manager properties, show all properties regardless whether they are set or not\&.
.RE
.PP
\fB\-\-failed\fR
.RS 4
When listing units, show only failed units\&. Do not confuse with
\fB\-\-fail\fR\&.
.RE
.PP
\fB\-\-full\fR
.RS 4
Do not ellipsize unit names and truncate unit descriptions in the output of
\fBlist\-units\fR
and
\fBlist\-jobs\fR\&.
.RE
.PP
\fB\-\-fail\fR
.RS 4
If the requested 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
\fB\-\-failed\fR\&.
.RE
.PP
\fB\-\-ignore\-dependencies\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-quiet\fR, \fB\-q\fR
.RS 4
Suppress output to STDOUT in
\fBsnapshot\fR,
\fBis\-active\fR,
\fBenable\fR
and
\fBdisable\fR\&.
.RE
.PP
\fB\-\-no\-block\fR
.RS 4
Do not synchronously wait for the requested operation to finish\&. If this is not specified the job will be verified, enqueued and
\fBsystemctl\fR
will wait until it is completed\&. By passing this argument it is only verified and enqueued\&.
.RE
.PP
\fB\-\-no\-legend\fR
.RS 4
Do not print a legend, i\&.e\&. the column headers and the footer with hints\&.
.RE
.PP
\fB\-\-no\-pager\fR
.RS 4
Do not pipe output into a pager\&.
.RE
.PP
\fB\-\-system\fR
.RS 4
Talk to the systemd system manager\&. (Default)
.RE
.PP
\fB\-\-user\fR
.RS 4
Talk to the systemd manager of the calling user\&.
.RE
.PP
\fB\-\-order\fR, \fB\-\-require\fR
.RS 4
When used in conjunction with the
\fBdot\fR
command (see below), selects which dependencies are shown in the dependency graph\&. If
\fB\-\-order\fR
is passed only dependencies of type
\fIAfter=\fR
or
\fIBefore=\fR
are shown\&. If
\fB\-\-require\fR
is passed only dependencies of type
\fIRequires=\fR,
\fIRequiresOverridable=\fR,
\fIRequisite=\fR,
\fIRequisiteOverridable=\fR,
\fIWants=\fR
and
\fIConflicts=\fR
are shown\&. If neither is passed, shows dependencies of all these types\&.
.RE
.PP
\fB\-\-no\-wall\fR
.RS 4
Don\*(Aqt send wall message before halt, power\-off, reboot\&.
.RE
.PP
\fB\-\-global\fR
.RS 4
When used with
\fBenable\fR
and
\fBdisable\fR, operate on the global user configuration directory, thus enabling or disabling a unit file globally for all future logins of all users\&.
.RE
.PP
\fB\-\-no\-reload\fR
.RS 4
When used with
\fBenable\fR
and
\fBdisable\fR, do not implicitly reload daemon configuration after executing the changes\&.
.RE
.PP
\fB\-\-no\-ask\-password\fR
.RS 4
When used with
\fBstart\fR
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
\fBsystemctl\fR
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\&.
.RE
.PP
\fB\-\-kill\-who=\fR
.RS 4
When used with
\fBkill\fR, choose which processes to kill\&. Must be one of
\fBmain\fR,
\fBcontrol\fR
or
\fBall\fR
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
\fBall\fR\&.
.RE
.PP
\fB\-\-signal=\fR, \fB\-s\fR
.RS 4
When used with
\fBkill\fR, 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
\fBSIGTERM\fR\&.
.RE
.PP
\fB\-\-force\fR, \fB\-f\fR
.RS 4
When used with
\fBenable\fR, override any existing conflicting symlinks\&.
When used with
\fBhalt\fR,
\fBpoweroff\fR,
\fBreboot\fR
or
\fBkexec\fR
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\&.
.RE
.PP
\fB\-\-root=\fR
.RS 4
When used with
\fBenable\fR/\fBdisable\fR/\fBis\-enabled\fR
(and related commands), use alternative root path when looking for unit files\&.
.RE
.PP
\fB\-\-runtime\fR
.RS 4
When used with
\fBenable\fR/\fBdisable\fR/\fBis\-enabled\fR
(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\&.
.RE
.PP
\fB\-H\fR, \fB\-\-host\fR
.RS 4
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\&.
.RE
.PP
\fB\-P\fR, \fB\-\-privileged\fR
.RS 4
Acquire privileges via PolicyKit before executing the operation\&.
.RE
.PP
The following commands are understood:
.PP
\fBlist\-units\fR
.RS 4
List known units\&.
.RE
.PP
\fBstart [NAME\&.\&.\&.]\fR
.RS 4
Start (activate) one or more units specified on the command line\&.
.RE
.PP
\fBstop [NAME\&.\&.\&.]\fR
.RS 4
Stop (deactivate) one or more units specified on the command line\&.
.RE
.PP
\fBreload [NAME\&.\&.\&.]\fR
.RS 4
Asks all units listed on the command line to reload their configuration\&. Note that this will 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
\fBdaemon\-reload\fR
command\&. In other words: for the example case of Apache, this will reload Apache\*(Aqs
httpd\&.conf
in the web server, not the
apache\&.service
systemd unit file\&.
.sp
This command should not be confused with the
\fBdaemon\-reload\fR
or
\fBload\fR
commands\&.
.RE
.PP
\fBrestart [NAME\&.\&.\&.]\fR
.RS 4
Restart one or more units specified on the command line\&. If the units are not running yet they will be started\&.
.RE
.PP
\fBtry\-restart [NAME\&.\&.\&.]\fR
.RS 4
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
\fBcondrestart\fR
is equivalent to this command\&.
.RE
.PP
\fBreload\-or\-restart [NAME\&.\&.\&.]\fR
.RS 4
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\&.
.RE
.PP
\fBreload\-or\-try\-restart [NAME\&.\&.\&.]\fR
.RS 4
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
\fBforce\-reload\fR
is equivalent to this command\&.
.RE
.PP
\fBisolate [NAME]\fR
.RS 4
Start the unit specified on the command line and its dependencies and stop all others\&.
.sp
This is similar to changing the runlevel in a traditional init system\&. The
\fBisolate\fR
command will immediately stop processes that are not enabled in the new unit, possibly including the graphical environment or terminal you are currently using\&.
.sp
Note that this works only on units where
\fBAllowIsolate=\fR
is enabled\&. See
\fBsystemd.unit\fR(5)
for details\&.
.RE
.PP
\fBkill [NAME\&.\&.\&.]\fR
.RS 4
Send a signal to one or more processes of the unit\&. Use
\fB\-\-kill\-who=\fR
to select which process to kill\&. Use
\fB\-\-kill\-mode=\fR
to select the kill mode and
\fB\-\-signal=\fR
to select the signal to send\&.
.RE
.PP
\fBis\-active [NAME\&.\&.\&.]\fR
.RS 4
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
\fB\-\-quiet\fR
is specified this will also print the current unit state to STDOUT\&.
.RE
.PP
\fBstatus [NAME\&.\&.\&.|PID\&.\&.\&.]\fR
.RS 4
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
\fBshow\fR
instead\&. If a PID is passed information about the unit the process of the PID belongs to is shown\&.
.RE
.PP
\fBshow [NAME\&.\&.\&.|JOB\&.\&.\&.]\fR
.RS 4
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
\fB\-\-all\fR
to show those too\&. To select specific properties to show use
\fB\-\-property=\fR\&. This command is intended to be used whenever computer\-parsable output is required\&. Use
\fBstatus\fR
if you are looking for formatted human\-readable output\&.
.RE
.PP
\fBreset\-failed [NAME\&.\&.\&.]\fR
.RS 4
Reset the \*(Aqfailed\*(Aq 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 \*(Aqfailed\*(Aq state and its exit code and status is recorded for introspection by the administrator until the service is restarted or reset with this command\&.
.RE
.PP
\fBlist\-unit\-files\fR
.RS 4
List installed unit files\&.
.RE
.PP
\fBenable [NAME\&.\&.\&.]\fR
.RS 4
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
\fBdaemon\-reload\fR) 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
\fBstart\fR
command must be invoked for the unit\&.
.sp
This command will print the actions executed\&. This output may be suppressed by passing
\fB\-\-quiet\fR\&.
.sp
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
\fBdaemon\-reload\fR
manually as necessary, to ensure his changes are taken into account\&.
.sp
Enabling units should not be confused with starting (activating) units, as done by the
\fBstart\fR
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\&.
.sp
Depending on whether
\fB\-\-system\fR,
\fB\-\-user\fR
or
\fB\-\-global\fR
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\&.
.RE
.PP
\fBdisable [NAME\&.\&.\&.]\fR
.RS 4
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
\fBenable\fR\&. Note however that this removes all symlinks to the unit files (i\&.e\&. including manual additions), not just those actually created by
\fBenable\fR\&. 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
\fBstop\fRcommand should be executed afterwards\&.
.sp
This command will print the actions executed\&. This output may be suppressed by passing
\fB\-\-quiet\fR\&.
.PP
This command honors
\fB\-\-system\fR,
\fB\-\-user\fR,
\fB\-\-global\fR
in a similar way as
\fBenable\fR\&.
.RE
.PP
\fBis\-enabled [NAME\&.\&.\&.]\fR
.RS 4
Checks whether any of the specified unit files is enabled (as with
\fBenable\fR)\&. 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
\fB\-\-quiet\fR\&.
.RE
.PP
\fBreenable [NAME\&.\&.\&.]\fR
.RS 4
Reenable one or more unit files, as specified on the command line\&. This is a combination of
\fBdisable\fR
and
\fBenable\fR
and is useful to reset the symlinks a unit is enabled with to the defaults configured in the
[Install]
section of the unit file\&.
.RE
.PP
\fBpreset [NAME\&.\&.\&.]\fR
.RS 4
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
\fBdisable\fR
or
\fBenable\fR, depending how the unit is listed in the preset files\&.
.RE
.PP
\fBmask [NAME\&.\&.\&.]\fR
.RS 4
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
\fBdisable\fR, since it prohibits all kinds of activation of the unit, including manual activation\&. Use this option with care\&.
.RE
.PP
\fBunmask [NAME\&.\&.\&.]\fR
.RS 4
Unmask one or more unit files, as specified on the command line\&. This will undo the effect of
\fBmask\fR\&.
.RE
.PP
\fBlink [NAME\&.\&.\&.]\fR
.RS 4
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
\fBdisable\fR\&. The effect of this command is that a unit file is available for
\fBstart\fR
and other commands although it isn\*(Aqt installed directly in the unit search path\&.
.RE
.PP
\fBload [NAME\&.\&.\&.]\fR
.RS 4
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
\fBstart\fR
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
\fBdaemon\-reload\fR
command for that\&. All in all, this command is of little use except for debugging\&.
.sp
This command should not be confused with the
\fBdaemon\-reload\fR
or
\fBreload\fR
commands\&.
.RE
.PP
\fBlist\-jobs\fR
.RS 4
List jobs that are in progress\&.
.RE
.PP
\fBcancel [JOB\&.\&.\&.]\fR
.RS 4
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\&.
.RE
.PP
\fBdump\fR
.RS 4
Dump server status\&. This will output a (usually very long) human readable manager status dump\&. Its format is subject to change without notice and should not be parsed by applications\&.
.RE
.PP
\fBdot\fR
.RS 4
Generate textual dependency graph description in dot format for further processing with the GraphViz
\fBdot\fR(1)
tool\&. Use a command line like
\fBsystemctl dot | dot \-Tsvg > systemd\&.svg\fR
to generate a graphical dependency tree\&. Unless
\fB\-\-order\fR
or
\fB\-\-require\fR
is passed the generated graph will show both ordering and requirement dependencies\&.
.RE
.PP
\fBsnapshot [NAME]\fR
.RS 4
Create a snapshot\&. If 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, unless
\fB\-\-quiet\fR
is specified\&.
.sp
A snapshot refers to a saved state of the systemd manager\&. It 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 time the user may return to this state by using the
\fBisolate\fR
command on the snapshot unit\&.
.PP
Snapshots are only useful for saving and restoring which units are running or are stopped, they do not save/restore any other state\&. Snapshots are dynamic and lost on reboot\&.
.RE
.PP
\fBdelete [NAME\&.\&.\&.]\fR
.RS 4
Remove a snapshot previously created with
\fBsnapshot\fR\&.
.RE
.PP
\fBdaemon\-reload\fR
.RS 4
Reload systemd manager configuration\&. This will reload all unit files and recreate the entire dependency tree\&. While the daemon is reloaded, all sockets systemd listens on on behalf of user configuration will stay accessible\&.
.sp
This command should not be confused with the
\fBload\fR
or
\fBreload\fR
commands\&.
.RE
.PP
\fBdaemon\-reexec\fR
.RS 4
Reexecute the systemd manager\&. This will serialize the manager state, reexecute the process and deserialize the state again\&. This command is of little use except for debugging and package upgrades\&. Sometimes it might be helpful as a heavy\-weight
\fBdaemon\-reload\fR\&. While the daemon is reexecuted all sockets systemd listens on on behalf of user configuration will stay accessible\&.
.RE
.PP
\fBshow\-environment\fR
.RS 4
Dump the systemd manager environment block\&. The environment block will be dumped in straight\-forward form suitable for sourcing into a shell script\&. This environment block will be passed to all processes the manager spawns\&.
.RE
.PP
\fBset\-environment [NAME=VALUE\&.\&.\&.]\fR
.RS 4
Set one or more systemd manager environment variables, as specified on the command line\&.
.RE
.PP
\fBunset\-environment [NAME\&.\&.\&.]\fR
.RS 4
Unset one or more systemd manager environment variables\&. If only a variable name is specified it will be removed regardless of its value\&. If a variable and a value are specified the variable is only removed if it has the specified value\&.
.RE
.PP
\fBdefault\fR
.RS 4
Enter default mode\&. This is mostly equivalent to
\fBstart default\&.target\fR\&.
.RE
.PP
\fBrescue\fR
.RS 4
Enter rescue mode\&. This is mostly equivalent to
\fBisolate rescue\&.target\fR
but also prints a wall message to all users\&.
.RE
.PP
\fBemergency\fR
.RS 4
Enter emergency mode\&. This is mostly equivalent to
\fBisolate emergency\&.target\fR
but also prints a wall message to all users\&.
.RE
.PP
\fBhalt\fR
.RS 4
Shut down and halt the system\&. This is mostly equivalent to
\fBstart halt\&.target\fR
but also prints a wall message to all users\&. If combined with
\fB\-\-force\fR
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\&.
.RE
.PP
\fBpoweroff\fR
.RS 4
Shut down and power\-off the system\&. This is mostly equivalent to
\fBstart poweroff\&.target\fR
but also prints a wall message to all users\&. If combined with
\fB\-\-force\fR
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\&.
.RE
.PP
\fBreboot\fR
.RS 4
Shut down and reboot the system\&. This is mostly equivalent to
\fBstart reboot\&.target\fR
but also prints a wall message to all users\&. If combined with
\fB\-\-force\fR
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\&.
.RE
.PP
\fBkexec\fR
.RS 4
Shut down and reboot the system via kexec\&. This is mostly equivalent to
\fBstart kexec\&.target\fR
but also prints a wall message to all users\&. If combined with
\fB\-\-force\fR
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\&.
.RE
.PP
\fBexit\fR
.RS 4
Ask the systemd manager to quit\&. This is only supported for user service managers (i\&.e\&. in conjunction with the
\fB\-\-user\fR
option) and will fail otherwise\&.
.RE
.SH "EXIT STATUS"
.PP
On success 0 is returned, a non\-zero failure code otherwise\&.
.SH "ENVIRONMENT"
.PP
\fI$SYSTEMD_PAGER\fR
.RS 4
Pager to use when
\fB\-\-no\-pager\fR
is not given; overrides
\fI$PAGER\fR\&. Setting this to an empty string or the value
cat
is equivalent to passing
\fB\-\-no\-pager\fR\&.
.RE
.SH "SEE ALSO"
.PP

\fBsystemd\fR(1),
\fBsystemadm\fR(1),
\fBsystemd-loginctl\fR(1),
\fBsystemd.unit\fR(5),
\fBsystemd.special\fR(7),
\fBwall\fR(1)
.SH "AUTHOR"
.PP
\fBLennart Poettering\fR <\&lennart@poettering\&.net\&>
.RS 4
Developer
.RE