X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=9cd6e88988cb65ad883a3da970d6bb48e93928c6;hp=760115acb55444789b12f804fdddaf45d638439c;hb=4f8f66cb4236783cd3cbee97fefc9aaa8469ac08;hpb=265a7a2a604a9cf92e8aa167ed48afb78e6602ea diff --git a/man/systemctl.xml b/man/systemctl.xml index 760115acb..9cd6e8898 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1,1289 +1,1382 @@ +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - systemctl - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - systemctl - 1 - - - - systemctl - Control the systemd system and service manager - - - - - systemctl OPTIONS COMMAND NAME - - - - - Description - - systemctl may be used to - introspect and control the state of the - systemd1 - system and service manager. - - - - Options - - The following options are understood: - - - - - - - Prints a short help - text and exits. - - - - - - Prints a short version - string and exits. - - - - - - - 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. - - - - - - - - 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. 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, cgroup members, and truncate unit descriptions - in the output of - list-units and - list-jobs. - - - - - - 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 - . - - - - - - 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. - - - - - - - When system shutdown - or a sleep state is requested, ignore - inhibitor locks. Applications can - establish inhibitor locks to avoid - that certain important operations - (such as CD burning or suchlike) are - interrupted by system shutdown or a - sleep state. Any user may take these - locks and privileged users may - override these locks. If any locks are - taken, shutdown and sleep state - requests will normally fail - (regardless if privileged or not) and - list of active locks is - printed. However if - - is specified the locks are ignored and - not printed, and the operation - attempted anyway, possibly requiring - additional - privileges. - - - - - - - Suppress output to - STDOUT in - snapshot, - is-active, - is-failed, - 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 print a 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. - - - - - - Don't send wall - message before - halt, power-off, reboot. - - - - - - 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. - - - - - - When used with - enable and - disable, do not - implicitly reload daemon configuration - after executing the - changes. - - - - - - 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. This also disables querying the - user for authentication for privileged - operations. - - - - - - 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 - . - - - - - - - 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, 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 - 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: - - - - list-units - - List known units (subject to limitations - specified with ). - - This is the default command. - - - start [NAME...] - - Start (activate) one - or more units specified on the command - line. - - - stop [NAME...] - - Stop (deactivate) one - or more units specified on the command - line. - - - reload [NAME...] - - 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 - daemon-reload - command. In other words: for the - example case of Apache, this will - reload Apache's - 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 - 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. - - 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. - - - is-failed [NAME...] - - Check whether any of - the specified units are failed. - Returns an exit code - 0 if at least one is failed, 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, 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. - - This function is intended to - generate human-readable output. If you - are looking for computer-parsable - output, use show - instead. - - - 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. - - - 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...] - - 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. - - - - list-unit-files - - List installed unit files. - - - - - enable [NAME...] - - 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 - 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. - 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 - 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 are being disabled. If this - is desired an additional - stop command 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 are 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 - 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. - - - - - 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. - - - list-jobs - - 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 - - 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. - - - 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 aare - recursively expanded as well. - - - - snapshot [NAME] - - 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 - is - specified. - - 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 - isolate command on - the snapshot unit. - - 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. - - - delete [NAME...] - - Remove a snapshot - previously created with - snapshot. - - - daemon-reload - - 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. This - command should not be confused with - the load or - reload - commands. - - - daemon-reexec - - 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 - daemon-reload. While - the daemon is reexecuted all sockets - systemd listens on on behalf of user - configuration will stay - accessible. - - - show-environment - - 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. - - - set-environment [NAME=VALUE...] - - Set one or more - systemd manager environment variables, - as specified on the command - line. - - - unset-environment [NAME...] - - 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. - - - 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 - - Shut down and halt the - system. This is mostly equivalent to - start halt.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 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 - - Shut down and - power-off the system. This is mostly - equivalent to start - poweroff.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 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 - reboot.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. If - is specified - twice the operation is immediately - executed without terminating any - processes or unmounting any file - systems. This may result in data - loss. - - - kexec - - 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. - - - exit - - 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. - - - suspend - - 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. - - - - - - - Exit status - - On success 0 is returned, a non-zero failure - 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 Also - - systemd1, - systemadm1, - journalctl1, - loginctl1, - systemd.unit5, - systemd.special7, - wall1, - systemd.preset5 - - + + systemctl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemctl + 1 + + + + systemctl + Control the systemd system and service manager + + + + + systemctl + OPTIONS + COMMAND + NAME + + + + + Description + + systemctl may be used to + introspect and control the state of the + systemd1 + system and service manager. + + + + Options + + The following options are understood: + + + + + + + Prints a short help + text and exits. + + + + + + + Prints a short version string and exits. + + + + + + + + + The argument should be a comma-separated list of unit + types such as and + . + + + If one of the arguments is a unit type, when listing + units, limit display to certain unit types. Otherwise, units + of all types will be shown. + + As a special case, if one of the arguments is + , a list of allowed values will be + printed and the program will exit. + + + + + + + + The argument should be a comma-separated list of unit LOAD, + SUB, or ACTIVE states. When listing units, show only those + in specified states. + + + + + + + + + When showing unit/job/manager properties with the + show command, limit display to certain + properties as specified as argument. If not specified, all + set properties are shown. The argument should be a + comma-separated list of property names, such as + MainPID. If specified more than once, all + properties with the specified names are shown. + + + + + + + + + When listing units, show all loaded units, regardless + of their state, including inactive units. When showing + unit/job/manager properties, show all properties regardless + whether they are set or not. + To list all units installed on the system, use the + list-unit-files command instead. + + + + + + + + Show reverse dependencies between units with + list-dependencies, i.e. units with + dependencies of type Wants= or + Requires= on the given unit. + + + + + + + + + + Show which units are started after or before + with list-dependencies, respectively. + + + + + + + + + + Do not ellipsize unit names, process tree entries, and + truncate unit descriptions in the output of + list-units and + list-jobs. + + + + + + + + When showing sockets, show the type of the socket. + + + + + + + + When queuing a new job, control how to deal with already + queued jobs. Takes one of fail, + replace, + replace-irreversibly, + isolate, + ignore-dependencies, + ignore-requirements or + flush. Defaults to + replace, except when the + isolate command is used which implies the + isolate job mode. + + If fail is specified and a requested + operation conflicts with a pending job (more specifically: + causes an already pending start job to be reversed into a stop + job or vice versa), cause the operation to fail. + + If replace (the default) is + specified, any conflicting pending job will be replaced, as + necessary. + + 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. + + isolate is only valid for start + operations and causes all other units to be stopped when the + specified unit is started. This mode is always used when the + isolate command is used. + + flush will cause all queued jobs to + be canceled when the new job is enqueued. + + If ignore-dependencies is specified, + then all unit dependencies are ignored for this new job and + the operation is executed 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. + + ignore-requirements is similar to + ignore-dependencies but only causes the + requirement dependencies to be ignored, the ordering + dependencies will still be honoured. + + + + + + + + + + When system shutdown or a sleep state is requested, + ignore inhibitor locks. Applications can establish inhibitor + locks to avoid that certain important operations (such as CD + burning or suchlike) are interrupted by system shutdown or a + sleep state. Any user may take these locks and privileged + users may override these locks. If any locks are taken, + shutdown and sleep state requests will normally fail + (regardless if privileged or not) and a list of active locks + is printed. However, if + is specified, the locks are ignored and not printed, and the + operation attempted anyway, possibly requiring additional + privileges. + + + + + + + + + Suppress output to standard output in + snapshot, + is-active, + is-failed, + 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 print a 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. + + + + + + + + Do not send wall message before halt, power-off, + reboot. + + + + + + + + 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. + + + + + + + + When used with enable and + disable, do not implicitly reload daemon + configuration after executing the changes. + + + + + + + + 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. This also disables + querying the user for authentication for privileged + operations. + + + + + + + + + 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 . + + + + + + + + + + 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, 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 lost 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. + + Similar, when used with + set-property, make changes only + temporarily, so that they are lost on the next + reboot. + + + + + + + + + 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. + + + + + + + + Execute the operation on a local + container. Specify a container name to connect + to. + + + + + + + + When used with 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. + + + + + + + + When used with list-dependencies, + the output is printed as a list instead of a tree. + + + + + + + + Commands + + The following commands are understood: + + + Unit Commands + + + + list-units PATTERN... + + + List known units (subject to limitations specified + with ). If one or more + PATTERNs are specified, only + units matching one of them are shown. + + This is the default command. + + + + + list-sockets PATTERN... + + + List socket units ordered by the listening address. + If one or more PATTERNs are + specified, only socket units matching one of them are + shown. Produces output similar to + +LISTEN UNIT ACTIVATES +/dev/initctl systemd-initctl.socket systemd-initctl.service +... +[::]:22 sshd.socket sshd.service +kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service + +5 sockets listed. + + Note: because the addresses might contains spaces, this output + is not suitable for programmatic consumption. + + + See also the options , + , and . + + + + + list-timers PATTERN... + + + List timer units ordered by the time they elapse + next. If one or more PATTERNs + are specified, only units matching one of them are shown. + + + See also the options and + . + + + + + start NAME... + + + Start (activate) one or more units specified on the + command line. + + + + stop NAME... + + + Stop (deactivate) one or more units specified on the + command line. + + + + reload NAME... + + + 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 + daemon-reload command. In other words: + for the example case of Apache, this will reload Apache's + 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 + 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. This does 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. This does 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. + + 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 is allowed 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. + + + + is-failed NAME... + + + Check whether any of the specified units are in a "failed" state. + Returns an exit code 0 if at least one has failed, 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, 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. + + This function is intended to generate human-readable + output. If you are looking for computer-parsable output, use + show instead. + + + + 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. + + + + cat NAME... + + + Show backing files of one or more units. Prints the + "fragment" and "drop-ins" (source files) of units. Each + file is preceded by a comment which includes the file + name. + + + + set-property NAME ASSIGNMENT... + + + Set the specified unit properties at runtime where + this is supported. This allows changing configuration + parameter properties such as resource control settings at + runtime. Not all properties may be changed at runtime, but + many resource control settings (primarily those in + systemd.resource-control5) + may. The changes are applied instantly, and stored on disk + for future boots, unless is + passed, in which case the settings only apply until the + next reboot. The syntax of the property assignment follows + closely the syntax of assignments in unit files. + + Example: systemctl set-property foobar.service CPUShares=777 + + Note that this command allows changing multiple + properties at the same time, which is preferable over + setting them individually. Like unit file configuration + settings, assigning the empty list to list parameters will + reset the list. + + + + + help NAME...|PID... + + + Show manual pages for one or more units, if + available. If a PID is given, the manual pages for the unit + the process belongs to are shown. + + + + + reset-failed [NAME...] + + + Reset the failed state of the + specified units, or if no unit name is passed, reset the state 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. + + + + + 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. + + + + + + + Unit File Commands + + + + list-unit-files PATTERN... + + + List installed unit files. If one or more + PATTERNs are specified, only + units whose filename (just the last component of the path) + matches one of them are shown. + + + + + enable NAME... + + + 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 account immediately. Note that + this does not have the effect of also + starting any of the units being enabled. If this + is desired, a separate start command must + be invoked for the unit. Also note that in case of instance + enablement, symlinks named the same as instances are created in + the install location, however they all point to the same + template unit file. + + 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 the 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, for only this boot of + 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. + + + + + 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 are being disabled. If this is desired, + an additional stop command should be + executed afterwards. + + This command will print the actions executed. This + output may be suppressed by passing . + + + This command honors , + , and + in a similar way as + enable. + + + + + is-enabled NAME... + + + Checks whether any of the specified unit files are + 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 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... + + + 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. This honors the + option to only mask temporarily + until the next reoobt of the system. + + + + + unmask NAME... + + + Unmask one or more unit files, as specified on the + command line. This will undo the effect of + mask. + + + + + link FILENAME... + + + 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 + is not installed directly in the unit search path. + + + + + get-default + + + Get the default target specified + via default.target link. + + + + + set-default NAME + + + Set the default target to boot into. Command links + default.target to the given unit. + + + + + + + Job Commands + + + + list-jobs PATTERN... + + + List jobs that are in progress. If one or more + PATTERNs are specified, only + jobs for units matching one of them are shown. + + + + 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. + + + + + + + Snapshot Commands + + + + snapshot NAME + + + 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 + is specified. + + 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 + isolate command on the snapshot unit. + + + 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. + + + + delete NAME... + + + Remove a snapshot previously created with + snapshot. + + + + + + + Environment Commands + + + + show-environment + + + 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. + + + + set-environment VARIABLE=VALUE... + + + Set one or more systemd manager environment variables, + as specified on the command line. + + + + unset-environment VARIABLE... + + + 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. + + + + + + + Manager Lifecycle Commands + + + + 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. + + + + daemon-reexec + + + 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 daemon-reload. + While the daemon is being reexecuted, all sockets systemd listening + on behalf of user configuration will stay accessible. + + + + + + + + System Commands + + + + default + + + Enter default mode. This is mostly equivalent to + isolate 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 + + + Shut down and halt the system. This is mostly equivalent to + start halt.target --irreversible, 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 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 + + + Shut down and power-off the system. This is mostly + equivalent to start poweroff.target --irreversible, + 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 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 arg + + + Shut down and reboot the system. This is mostly + equivalent to start reboot.target --irreversible, + 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. If is + specified twice, the operation is immediately executed + without terminating any processes or unmounting any file + systems. This may result in data loss. + + If the optional argument + arg is given, it will be passed + as the optional argument to the + reboot2 + system call. The value is architecture and firmware + specific. As an example, recovery might + be used to trigger system recovery, and + fota might be used to trigger a + firmware over the air update. + + + + kexec + + + Shut down and reboot the system via kexec. This is + mostly equivalent to start kexec.target --irreversible, + 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. + + + + exit + + + 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. + + + + + suspend + + + 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. 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 + + For unit commands the specified + NAME should be the full name of the + unit, or an abbreviated name which is automatically extended with + the .service suffix. + # systemctl start foo.service is equivalent to: + # systemctl start foo + Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) paths to mount unit names. + # systemctl status /dev/sda +# systemctl status /home is equivalent to: + # systemctl status dev-sda.device +# systemctl status home.mount + + For unit file commands the + specified NAME should be the full name + of the unit file, or the absolute path to the unit file. + # systemctl link /path/to/foo.service + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + 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 Also + + systemd1, + systemadm1, + journalctl1, + loginctl1, + systemd.unit5, + systemd.resource-management5, + systemd.special7, + wall1, + systemd.preset5 + +