diff options
Diffstat (limited to 'man/systemctl.xml')
| -rw-r--r-- | man/systemctl.xml | 1845 |
1 files changed, 0 insertions, 1845 deletions
diff --git a/man/systemctl.xml b/man/systemctl.xml deleted file mode 100644 index dfa00e0c03..0000000000 --- a/man/systemctl.xml +++ /dev/null @@ -1,1845 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2010 Lennart Poettering - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemctl" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemctl</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemctl</refname> - <refpurpose>Control the systemd system and service manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">COMMAND</arg> - <arg choice="opt" rep="repeat">NAME</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemctl</command> may be used to introspect and - control the state of the <literal>systemd</literal> system and - service manager. Please refer to - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for an introduction into the basic concepts and functionality this - tool manages.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-t</option></term> - <term><option>--type=</option></term> - - <listitem> - <para>The argument should be a comma-separated list of unit - types such as <option>service</option> and - <option>socket</option>. - </para> - - <para>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.</para> - - <para>As a special case, if one of the arguments is - <option>help</option>, a list of allowed values will be - printed and the program will exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--state=</option></term> - - <listitem> - <para>The argument should be a comma-separated list of unit - LOAD, SUB, or ACTIVE states. When listing units, show only - those in the specified states. Use <option>--state=failed</option> - to show only failed units.</para> - - <para>As a special case, if one of the arguments is - <option>help</option>, a list of allowed values will be - printed and the program will exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--property=</option></term> - - <listitem> - <para>When showing unit/job/manager properties with the - <command>show</command> command, limit display to properties - specified in the argument. The argument should be a - comma-separated list of property names, such as - <literal>MainPID</literal>. Unless specified, all known - properties are shown. If specified more than once, all - properties with the specified names are shown. Shell - completion is implemented for property names.</para> - - <para>For the manager itself, - <command>systemctl show</command> will show all available - properties. Those properties are documented in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>Properties for units vary by unit type, so showing any - unit (even a non-existent one) is a way to list properties - pertaining to this type. Similarly, showing any job will list - properties pertaining to all jobs. Properties for units are - documented in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and the pages for individual unit types - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - etc.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</option></term> - - <listitem> - <para>When listing units with <command>list-units</command>, also show inactive units and - units which are following other units. When showing unit/job/manager properties, show all - properties regardless whether they are set or not.</para> - - <para>To list all units installed in the file system, use the - <command>list-unit-files</command> command instead.</para> - - <para>When listing units with <command>list-dependencies</command>, recursively show - dependencies of all dependent units (by default only dependencies of target units are - shown).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - <term><option>--recursive</option></term> - - <listitem> - <para>When listing units, also show units of local - containers. Units of local containers will be prefixed with - the container name, separated by a single colon character - (<literal>:</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--reverse</option></term> - - <listitem> - <para>Show reverse dependencies between units with - <command>list-dependencies</command>, i.e. follow - dependencies of type <varname>WantedBy=</varname>, - <varname>RequiredBy=</varname>, - <varname>PartOf=</varname>, <varname>BoundBy=</varname>, - instead of <varname>Wants=</varname> and similar. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--after</option></term> - - <listitem> - <para>With <command>list-dependencies</command>, show the - units that are ordered before the specified unit. In other - words, recursively list units following the - <varname>After=</varname> dependency.</para> - - <para>Note that any <varname>After=</varname> dependency is - automatically mirrored to create a - <varname>Before=</varname> dependency. Temporal dependencies - may be specified explicitly, but are also created implicitly - for units which are <varname>WantedBy=</varname> targets - (see - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>), - and as a result of other directives (for example - <varname>RequiresMountsFor=</varname>). Both explicitly - and implicitly introduced dependencies are shown with - <command>list-dependencies</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--before</option></term> - - <listitem> - <para>With <command>list-dependencies</command>, show the - units that are ordered after the specified unit. In other - words, recursively list units following the - <varname>Before=</varname> dependency.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem> - <para>Do not ellipsize unit names, process tree entries, - journal output, or truncate unit descriptions in the output - of <command>status</command>, <command>list-units</command>, - <command>list-jobs</command>, and - <command>list-timers</command>.</para> - <para>Also, show installation targets in the output of - <command>is-enabled</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--value</option></term> - - <listitem> - <para>When printing properties with <command>show</command>, - only print the value, and skip the property name and - <literal>=</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--show-types</option></term> - - <listitem> - <para>When showing sockets, show the type of the socket.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--job-mode=</option></term> - - <listitem> - <para>When queuing a new job, this option controls how to deal with - already queued jobs. It takes one of <literal>fail</literal>, - <literal>replace</literal>, - <literal>replace-irreversibly</literal>, - <literal>isolate</literal>, - <literal>ignore-dependencies</literal>, - <literal>ignore-requirements</literal> or - <literal>flush</literal>. Defaults to - <literal>replace</literal>, except when the - <command>isolate</command> command is used which implies the - <literal>isolate</literal> job mode.</para> - - <para>If <literal>fail</literal> 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.</para> - - <para>If <literal>replace</literal> (the default) is - specified, any conflicting pending job will be replaced, as - necessary.</para> - - <para>If <literal>replace-irreversibly</literal> is specified, - operate like <literal>replace</literal>, but also mark the new - jobs as irreversible. This prevents future conflicting - transactions from replacing these jobs (or even being enqueued - while the irreversible jobs are still pending). Irreversible - jobs can still be cancelled using the <command>cancel</command> - command.</para> - - <para><literal>isolate</literal> 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 - <command>isolate</command> command is used.</para> - - <para><literal>flush</literal> will cause all queued jobs to - be canceled when the new job is enqueued.</para> - - <para>If <literal>ignore-dependencies</literal> 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.</para> - - <para><literal>ignore-requirements</literal> is similar to - <literal>ignore-dependencies</literal>, but only causes the - requirement dependencies to be ignored, the ordering - dependencies will still be honored.</para> - </listitem> - - </varlistentry> - - <varlistentry> - <term><option>--fail</option></term> - - <listitem> - <para>Shorthand for <option>--job-mode=</option>fail.</para> - <para>When used with the <command>kill</command> command, - if no units were killed, the operation results in an error. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--ignore-inhibitors</option></term> - - <listitem> - <para>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 of whether privileged or not) and a list of active locks - is printed. However, if <option>--ignore-inhibitors</option> - is specified, the locks are ignored and not printed, and the - operation attempted anyway, possibly requiring additional - privileges.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> - - <listitem> - <para>Suppress printing of the results of various commands - and also the hints about truncated log lines. This does not - suppress output of commands for which the printed output is - the only result (like <command>show</command>). Errors are - always printed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-block</option></term> - - <listitem> - <para>Do not synchronously wait for the requested operation - to finish. If this is not specified, the job will be - verified, enqueued and <command>systemctl</command> will - wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued. This option may not be - combined with <option>--wait</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--wait</option></term> - - <listitem> - <para>Synchronously wait for started units to terminate again. - This option may not be combined with <option>--no-block</option>. - Note that this will wait forever if any given unit never terminates - (by itself or by getting stopped explicitly); particularly services - which use <literal>RemainAfterExit=yes</literal>.</para> - </listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="user" /> - <xi:include href="user-system-options.xml" xpointer="system" /> - - <!-- we do not document -failed here, as it has been made - redundant by -state=failed, which it predates. To keep - things simple, we only document the new switch, while - keeping the old one around for compatibility only. --> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem> - <para>Do not send wall message before halt, power-off, - reboot.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--global</option></term> - - <listitem> - <para>When used with <command>enable</command> and - <command>disable</command>, operate on the global user - configuration directory, thus enabling or disabling a unit - file globally for all future logins of all users.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-reload</option></term> - - <listitem> - <para>When used with <command>enable</command> and - <command>disable</command>, do not implicitly reload daemon - configuration after executing the changes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem> - <para>When used with <command>start</command> 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, - <command>systemctl</command> 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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--kill-who=</option></term> - - <listitem> - <para>When used with <command>kill</command>, choose which - processes to send a signal to. Must be one of - <option>main</option>, <option>control</option> or - <option>all</option> to select whether to kill only the main - process, the control process or all processes of the - unit. The main process of the unit is the one that defines - the life-time of it. A control process of a unit is one that - is invoked by the manager to induce state changes of it. For - example, all processes started due to the - <varname>ExecStartPre=</varname>, - <varname>ExecStop=</varname> or - <varname>ExecReload=</varname> settings of service units are - control processes. Note that there is only one control - process per unit at a time, as only one state change is - executed at a time. For services of type - <varname>Type=forking</varname>, the initial process started - by the manager for <varname>ExecStart=</varname> is a - control process, while the process ultimately forked off by - that one is then considered the main process of the unit (if - it can be determined). This is different for service units - of other types, where the process forked off by the manager - for <varname>ExecStart=</varname> is always the main process - itself. A service unit consists of zero or one main process, - zero or one control process plus any number of additional - processes. Not all unit types manage processes of these - types however. For example, for mount units, control processes - are defined (which are the invocations of - <filename>&MOUNT_PATH;</filename> and - <filename>&UMOUNT_PATH;</filename>), but no main process - is defined. If omitted, defaults to - <option>all</option>.</para> - </listitem> - - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <term><option>--signal=</option></term> - - <listitem> - <para>When used with <command>kill</command>, choose which - signal to send to selected processes. Must be one of the - well-known signal specifiers such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or - <constant>SIGSTOP</constant>. If omitted, defaults to - <option>SIGTERM</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - <term><option>--force</option></term> - - <listitem> - <para>When used with <command>enable</command>, overwrite - any existing conflicting symlinks.</para> - - <para>When used with <command>edit</command>, create all of the - specified units which do not already exist.</para> - - <para>When used with <command>halt</command>, <command>poweroff</command>, <command>reboot</command> or - <command>kexec</command>, 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 <option>--force</option> is specified - twice for these operations (with the exception of <command>kexec</command>), they will be executed - immediately, without terminating any processes or unmounting any file systems. Warning: specifying - <option>--force</option> twice with any of these operations might result in data loss. Note that when - <option>--force</option> is specified twice the selected operation is executed by - <command>systemctl</command> itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--message=</option></term> - - <listitem> - <para>When used with <command>halt</command>, - <command>poweroff</command>, <command>reboot</command> or - <command>kexec</command>, set a short message explaining the reason - for the operation. The message will be logged together with the - default shutdown message.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--now</option></term> - - <listitem> - <para>When used with <command>enable</command>, the units - will also be started. When used with <command>disable</command> or - <command>mask</command>, the units will also be stopped. The start - or stop operation is only carried out when the respective enable or - disable operation has been successful.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--root=</option></term> - - <listitem> - <para>When used with - <command>enable</command>/<command>disable</command>/<command>is-enabled</command> - (and related commands), use the specified root path when looking for unit - files. If this option is present, <command>systemctl</command> will operate on - the file system directly, instead of communicating with the <command>systemd</command> - daemon to carry out changes.</para> - </listitem> - - </varlistentry> - - <varlistentry> - <term><option>--runtime</option></term> - - <listitem> - <para>When used with <command>enable</command>, - <command>disable</command>, <command>edit</command>, - (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 - <filename>/etc</filename> but in <filename>/run</filename>, - with identical immediate effects, however, since the latter - is lost on reboot, the changes are lost too.</para> - - <para>Similarly, when used with - <command>set-property</command>, make changes only - temporarily, so that they are lost on the next - reboot.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--preset-mode=</option></term> - - <listitem> - <para>Takes one of <literal>full</literal> (the default), - <literal>enable-only</literal>, - <literal>disable-only</literal>. When used with the - <command>preset</command> or <command>preset-all</command> - commands, controls whether units shall be disabled and - enabled according to the preset rules, or only enabled, or - only disabled.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</option></term> - - <listitem> - <para>When used with <command>status</command>, controls the - number of journal lines to show, counting from the most - recent ones. Takes a positive integer argument. Defaults to - 10.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output=</option></term> - - <listitem> - <para>When used with <command>status</command>, controls the - formatting of the journal entries that are shown. For the - available choices, see - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - Defaults to <literal>short</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--firmware-setup</option></term> - - <listitem> - <para>When used with the <command>reboot</command> command, - indicate to the system's firmware to boot into setup - mode. Note that this is currently only supported on some EFI - systems and only if the system was booted in EFI - mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--plain</option></term> - - <listitem> - <para>When used with <command>list-dependencies</command>, - <command>list-units</command> or <command>list-machines</command>, - the output is printed as a list instead of a tree, and the bullet - circles are omitted.</para> - </listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <refsect2> - <title>Unit Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List units that <command>systemd</command> currently has in memory. This includes units that are - either referenced directly or through a dependency, units that are pinned by applications programmatically, - or units that were active in the past and have failed. By default only units which are active, have pending - jobs, or have failed are shown; this can be changed with option <option>--all</option>. If one or more - <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. The units - that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those - options are specified.</para> - - <para>This is the default command.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List socket units currently in memory, ordered by listening address. If one or more - <replaceable>PATTERN</replaceable>s are specified, only socket units matching one of them are - shown. Produces output similar to - <programlisting> -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.</programlisting> - Note: because the addresses might contains spaces, this output - is not suitable for programmatic consumption. - </para> - - <para>Also see <option>--show-types</option>, <option>--all</option>, and <option>--state=</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List timer units currently in memory, ordered by the time they elapse next. If one or more - <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. - </para> - - <para>Also see <option>--all</option> and <option>--state=</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>start <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Start (activate) one or more units specified on the - command line.</para> - - <para>Note that glob patterns operate on the set of primary names of units currently in memory. Units which - are not active and are not in a failed state usually are not in memory, and will not be matched by any - pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until - the instance has been started. Therefore, using glob patterns with <command>start</command> has limited - usefulness. Also, secondary alias names of units are not considered.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>stop <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Stop (deactivate) one or more units specified on the - command line.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>reload <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>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 - <command>daemon-reload</command> command. In other words: - for the example case of Apache, this will reload Apache's - <filename>httpd.conf</filename> in the web server, not the - <filename>apache.service</filename> systemd unit - file.</para> - - <para>This command should not be confused with the - <command>daemon-reload</command> command.</para> - </listitem> - - </varlistentry> - <varlistentry> - <term><command>restart <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Restart one or more units specified on the command - line. If the units are not running yet, they will be - started.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>try-restart <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Restart one or more units specified on the command - line if the units are running. This does nothing if units are not - running.</para> - <!-- Note that we don't document condrestart here, as that is just compatibility support, and we generally - don't document that. --> - </listitem> - </varlistentry> - <varlistentry> - <term><command>reload-or-restart <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>try-reload-or-restart <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Reload one or more units if they support it. If not, - restart them instead. This does nothing if the units are not - running.</para> - <!-- Note that we don't document force-reload here, as that is just compatibility support, and we generally - don't document that. --> - </listitem> - </varlistentry> - <varlistentry> - <term><command>isolate <replaceable>NAME</replaceable></command></term> - - <listitem> - <para>Start the unit specified on the command line and its - dependencies and stop all others. If a unit name with no - extension is given, an extension of - <literal>.target</literal> will be assumed.</para> - - <para>This is similar to changing the runlevel in a - traditional init system. The <command>isolate</command> - command will immediately stop processes that are not enabled - in the new unit, possibly including the graphical - environment or terminal you are currently using.</para> - - <para>Note that this is allowed only on units where - <option>AllowIsolate=</option> is enabled. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>kill <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Send a signal to one or more processes of the - unit. Use <option>--kill-who=</option> to select which - process to kill. Use <option>--signal=</option> to select - the signal to send.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>is-active <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Check whether any of the specified units are active - (i.e. running). Returns an exit code - <constant>0</constant> if at least one is active, or - non-zero otherwise. Unless <option>--quiet</option> is - specified, this will also print the current unit state to - standard output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>is-failed <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Check whether any of the specified units are in a - "failed" state. Returns an exit code - <constant>0</constant> if at least one has failed, - non-zero otherwise. Unless <option>--quiet</option> is - specified, this will also print the current unit state to - standard output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>status</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...]</optional></term> - - <listitem> - <para>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 system status. If - combined with <option>--all</option>, also show the status of - all units (subject to limitations specified with - <option>-t</option>). If a PID is passed, show information - about the unit the process belongs to.</para> - - <para>This function is intended to generate human-readable - output. If you are looking for computer-parsable output, - use <command>show</command> instead. By default, this - function only shows 10 lines of output and ellipsizes - lines to fit in the terminal window. This can be changed - with <option>--lines</option> and <option>--full</option>, - see above. In addition, <command>journalctl - --unit=<replaceable>NAME</replaceable></command> or - <command>journalctl - --user-unit=<replaceable>NAME</replaceable></command> use - a similar filter for messages and might be more - convenient. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>show</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>JOB</replaceable>...</optional></term> - - <listitem> - <para>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 are shown, and if a job ID is - specified, properties of the job are shown. By default, empty - properties are suppressed. Use <option>--all</option> to - show those too. To select specific properties to show, use - <option>--property=</option>. This command is intended to be - used whenever computer-parsable output is required. Use - <command>status</command> if you are looking for formatted - human-readable output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>cat <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>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. Note that this shows the contents of the backing files - on disk, which may not match the system manager's - understanding of these units if any unit files were - updated on disk and the <command>daemon-reload</command> - command wasn't issued since.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>...</command></term> - - <listitem> - <para>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 - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - may. The changes are applied instantly, and stored on disk - for future boots, unless <option>--runtime</option> 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.</para> - - <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para> - - <para>If the specified unit appears to be inactive, the - changes will be only stored on disk as described - previously hence they will be effective when the unit will - be started.</para> - - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>help <replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...</command></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>reset-failed [<replaceable>PATTERN</replaceable>...]</command></term> - - <listitem> - <para>Reset the <literal>failed</literal> 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 - <literal>failed</literal> state and its exit code and status - is recorded for introspection by the administrator until the - service is restarted or reset with this command.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <command>list-dependencies</command> - <optional><replaceable>NAME</replaceable></optional> - </term> - - <listitem> - <para>Shows units required and wanted by the specified - unit. This recursively lists units following the - <varname>Requires=</varname>, - <varname>Requisite=</varname>, - <varname>ConsistsOf=</varname>, - <varname>Wants=</varname>, <varname>BindsTo=</varname> - dependencies. If no unit is specified, - <filename>default.target</filename> is implied.</para> - - <para>By default, only target units are recursively - expanded. When <option>--all</option> is passed, all other - units are recursively expanded as well.</para> - - <para>Options <option>--reverse</option>, - <option>--after</option>, <option>--before</option> - may be used to change what types of dependencies - are shown.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Unit File Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term> - - <listitem> - <para>List unit files installed on the system, in combination with their enablement state (as reported by - <command>is-enabled</command>). If one or more <replaceable>PATTERN</replaceable>s are specified, only unit - files whose name matches one of them are shown (patterns matching unit file system paths are not - supported).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>enable <replaceable>NAME</replaceable>...</command></term> - <term><command>enable <replaceable>PATH</replaceable>...</command></term> - - <listitem> - <para>Enable one or more units or unit instances. This will create a set of symlinks, as encoded in the - <literal>[Install]</literal> sections of the indicated unit files. After the symlinks have been created, - the system manager configuration is reloaded (in a way equivalent to <command>daemon-reload</command>), in - order to ensure the changes are taken into account immediately. Note that this does - <emphasis>not</emphasis> have the effect of also starting any of the units being enabled. If this is - desired, combine this command with the <option>--now</option> switch, or invoke <command>start</command> - with appropriate arguments later. Note that in case of unit instance enablement (i.e. enablement of units of - the form <filename>foo@bar.service</filename>), symlinks named the same as instances are created in the - unit configuration directory, however they point to the single template unit file they are instantiated - from.</para> - - <para>This command expects either valid unit names (in which case various unit file directories are - automatically searched for unit files with appropriate names), or absolute paths to unit files (in which - case these files are read directly). If a specified unit file is located outside of the usual unit file - directories, an additional symlink is created, linking it into the unit configuration path, thus ensuring - it is found when requested by commands such as <command>start</command>.</para> - - <para>This command will print the file system operations executed. This output may be suppressed by passing - <option>--quiet</option>. - </para> - - <para>Note that this operation creates only the symlinks suggested in the <literal>[Install]</literal> - section of the unit files. 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 - below this 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 - <command>daemon-reload</command> manually as necessary, in order to ensure the changes are taken into - account. - </para> - - <para>Enabling units should not be confused with starting (activating) units, as done by the - <command>start</command> 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.</para> - - <para>Depending on whether <option>--system</option>, <option>--user</option>, <option>--runtime</option>, - or <option>--global</option> 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.</para> - - <para>Using <command>enable</command> on masked units is not supported and results in an error.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>disable <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Disables one or more units. This removes all symlinks to the unit files backing the specified units - from the unit configuration directory, and hence undoes any changes made by <command>enable</command> or - <command>link</command>. Note that this removes <emphasis>all</emphasis> symlinks to matching unit files, - including manually created symlinks, and not just those actually created by <command>enable</command> or - <command>link</command>. Note that while <command>disable</command> undoes the effect of - <command>enable</command>, the two commands are otherwise not symmetric, as <command>disable</command> may - remove more symlinks than a prior <command>enable</command> invocation of the same unit created.</para> - - <para>This command expects valid unit names only, it does not accept paths to unit files.</para> - - <para>In addition to the units specified as arguments, all units are disabled that are listed in the - <varname>Also=</varname> setting contained in the <literal>[Install]</literal> section of any of the unit - files being operated on.</para> - - <para>This command implicitly reloads the system manager configuration after completing the operation. Note - that this command does not implicitly stop the units that are being disabled. If this is desired, either - combine this command with the <option>--now</option> switch, or invoke the <command>stop</command> command - with appropriate arguments later.</para> - - <para>This command will print information about the file system operations (symlink removals) - executed. This output may be suppressed by passing <option>--quiet</option>. - </para> - - <para>This command honors <option>--system</option>, <option>--user</option>, <option>--runtime</option> - and <option>--global</option> in a similar way as <command>enable</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>reenable <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Reenable one or more units, as specified on the command line. This is a combination of - <command>disable</command> and <command>enable</command> and is useful to reset the symlinks a unit file is - enabled with to the defaults configured in its <literal>[Install]</literal> section. This command expects - a unit name only, it does not accept paths to unit files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>preset <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Reset the enable/disable status 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 <command>disable</command> or - <command>enable</command>, depending how the unit is listed in the preset - files.</para> - - <para>Use <option>--preset-mode=</option> to control whether units shall be - enabled and disabled, or only enabled, or only disabled.</para> - - <para>If the unit carries no install information, it will be silently ignored - by this command. <replaceable>NAME</replaceable> must be the real unit name, - any alias names are ignored silently.</para> - - <para>For more information on the preset policy format, see - <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - For more information on the concept of presets, please consult the - <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink> - document.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>preset-all</command></term> - - <listitem> - <para>Resets all installed unit files to the defaults - configured in the preset policy file (see above).</para> - - <para>Use <option>--preset-mode=</option> to control - whether units shall be enabled and disabled, or only - enabled, or only disabled.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>is-enabled <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Checks whether any of the specified unit files are - enabled (as with <command>enable</command>). Returns an - exit code of 0 if at least one is enabled, non-zero - otherwise. Prints the current enable status (see table). - To suppress this output, use <option>--quiet</option>. - To show installation targets, use <option>--full</option>. - </para> - - <table> - <title> - <command>is-enabled</command> output - </title> - - <tgroup cols='3'> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - <entry>Exit Code</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>enabled</literal></entry> - <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or alias symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry> - <entry morerows='1'>0</entry> - </row> - <row> - <entry><literal>enabled-runtime</literal></entry> - </row> - <row> - <entry><literal>linked</literal></entry> - <entry morerows='1'>Made available through one or more symlinks to the unit file (permanently in <filename>/etc/systemd/system/</filename> or transiently in <filename>/run/systemd/system/</filename>), even though the unit file might reside outside of the unit file search path.</entry> - <entry morerows='1'>> 0</entry> - </row> - <row> - <entry><literal>linked-runtime</literal></entry> - </row> - <row> - <entry><literal>masked</literal></entry> - <entry morerows='1'>Completely disabled, so that any start operation on it fails (permanently in <filename>/etc/systemd/system/</filename> or transiently in <filename>/run/systemd/systemd/</filename>).</entry> - <entry morerows='1'>> 0</entry> - </row> - <row> - <entry><literal>masked-runtime</literal></entry> - </row> - <row> - <entry><literal>static</literal></entry> - <entry>The unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> unit file section.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>indirect</literal></entry> - <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>disabled</literal></entry> - <entry>The unit file is not enabled, but contains an <literal>[Install]</literal> section with installation instructions.</entry> - <entry>> 0</entry> - </row> - <row> - <entry><literal>generated</literal></entry> - <entry>The unit file was generated dynamically via a generator tool. See <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Generated unit files may not be enabled, they are enabled implicitly by their generator.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>transient</literal></entry> - <entry>The unit file has been created dynamically with the runtime API. Transient units may not be enabled.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>bad</literal></entry> - <entry>The unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> - <entry>> 0</entry> - </row> - </tbody> - </tgroup> - </table> - - </listitem> - </varlistentry> - - <varlistentry> - <term><command>mask <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Mask one or more units, as specified on the command line. This will link these unit files to - <filename>/dev/null</filename>, making it impossible to start them. This is a stronger version of - <command>disable</command>, since it prohibits all kinds of activation of the unit, including enablement - and manual activation. Use this option with care. This honors the <option>--runtime</option> option to only - mask temporarily until the next reboot of the system. The <option>--now</option> option may be used to - ensure that the units are also stopped. This command expects valid unit names only, it does not accept unit - file paths.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>unmask <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Unmask one or more unit files, as specified on the command line. This will undo the effect of - <command>mask</command>. This command expects valid unit names only, it does not accept unit file - paths.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>link <replaceable>PATH</replaceable>...</command></term> - - <listitem> - <para>Link a unit file that is not in the unit file search paths into the unit file search path. This - command expects an absolute path to a unit file. The effect of this may be undone with - <command>disable</command>. The effect of this command is that a unit file is made available for commands - such as <command>start</command>, even though it is not installed directly in the unit search path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>revert <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Revert one or more unit files to their vendor versions. This command removes drop-in configuration - files that modify the specified units, as well as any user-configured unit file that overrides a matching - vendor supplied unit file. Specifically, for a unit <literal>foo.service</literal> the matching directories - <literal>foo.service.d/</literal> with all their contained files are removed, both below the persistent and - runtime configuration directories (i.e. below <filename>/etc/systemd/system</filename> and - <filename>/run/systemd/system</filename>); if the unit file has a vendor-supplied version (i.e. a unit file - located below <filename>/usr</filename>) any matching persistent or runtime unit file that overrides it is - removed, too. Note that if a unit file has no vendor-supplied version (i.e. is only defined below - <filename>/etc/systemd/system</filename> or <filename>/run/systemd/system</filename>, but not in a unit - file stored below <filename>/usr</filename>), then it is not removed. Also, if a unit is masked, it is - unmasked.</para> - - <para>Effectively, this command may be used to undo all changes made with <command>systemctl - edit</command>, <command>systemctl set-property</command> and <command>systemctl mask</command> and puts - the original unit file with its settings back in effect.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>add-wants <replaceable>TARGET</replaceable> - <replaceable>NAME</replaceable>...</command></term> - <term><command>add-requires <replaceable>TARGET</replaceable> - <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Adds <literal>Wants=</literal> or <literal>Requires=</literal> - dependencies, respectively, to the specified - <replaceable>TARGET</replaceable> for one or more units. </para> - - <para>This command honors <option>--system</option>, - <option>--user</option>, <option>--runtime</option> and - <option>--global</option> in a way similar to - <command>enable</command>.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><command>edit <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Edit a drop-in snippet or a whole replacement file if - <option>--full</option> is specified, to extend or override the - specified unit.</para> - - <para>Depending on whether <option>--system</option> (the default), - <option>--user</option>, or <option>--global</option> is specified, - this command creates a drop-in file for each unit either for the system, - for the calling user, or for all futures logins of all users. Then, - the editor (see the "Environment" section below) is invoked on - temporary files which will be written to the real location if the - editor exits successfully.</para> - - <para>If <option>--full</option> is specified, this will copy the - original units instead of creating drop-in files.</para> - - <para>If <option>--force</option> is specified and any units do - not already exist, new unit files will be opened for editing.</para> - - <para>If <option>--runtime</option> is specified, the changes will - be made temporarily in <filename>/run</filename> and they will be - lost on the next reboot.</para> - - <para>If the temporary file is empty upon exit, the modification of - the related unit is canceled.</para> - - <para>After the units have been edited, systemd configuration is - reloaded (in a way that is equivalent to <command>daemon-reload</command>). - </para> - - <para>Note that this command cannot be used to remotely edit units - and that you cannot temporarily edit units which are in - <filename>/etc</filename>, since they take precedence over - <filename>/run</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>get-default</command></term> - - <listitem> - <para>Return the default target to boot into. This returns - the target unit name <filename>default.target</filename> - is aliased (symlinked) to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>set-default <replaceable>NAME</replaceable></command></term> - - <listitem> - <para>Set the default target to boot into. This sets - (symlinks) the <filename>default.target</filename> alias - to the given target unit.</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect2> - - <refsect2> - <title>Machine Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-machines <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List the host and all running local containers with - their state. If one or more - <replaceable>PATTERN</replaceable>s are specified, only - containers matching one of them are shown. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Job Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-jobs <optional><replaceable>PATTERN...</replaceable></optional></command></term> - - <listitem> - <para>List jobs that are in progress. If one or more - <replaceable>PATTERN</replaceable>s are specified, only - jobs for units matching one of them are shown.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>cancel <replaceable>JOB</replaceable>...</command></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Environment Commands</title> - - <variablelist> - <varlistentry> - <term><command>show-environment</command></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>...</command></term> - - <listitem> - <para>Set one or more systemd manager environment variables, - as specified on the command line.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>unset-environment <replaceable>VARIABLE</replaceable>...</command></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <command>import-environment</command> - <optional><replaceable>VARIABLE...</replaceable></optional> - </term> - - <listitem> - <para>Import all, one or more environment variables set on - the client into the systemd manager environment block. If - no arguments are passed, the entire environment block is - imported. Otherwise, a list of one or more environment - variable names should be passed, whose client-side values - are then imported into the manager's environment - block.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Manager Lifecycle Commands</title> - - <variablelist> - <varlistentry> - <term><command>daemon-reload</command></term> - - <listitem> - <para>Reload the systemd manager configuration. This will - rerun all generators (see - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>), - reload all unit files, and recreate the entire dependency - tree. While the daemon is being reloaded, all sockets - systemd listens on behalf of user configuration will stay - accessible.</para> - - <para>This command should not be confused with the - <command>reload</command> command.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>daemon-reexec</command></term> - - <listitem> - <para>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 <command>daemon-reload</command>. - While the daemon is being reexecuted, all sockets systemd listening - on behalf of user configuration will stay accessible. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>System Commands</title> - - <variablelist> - <varlistentry> - <term><command>is-system-running</command></term> - - <listitem> - <para>Checks whether the system is operational. This - returns success (exit code 0) when the system is fully up - and running, specifically not in startup, shutdown or - maintenance mode, and with no failed services. Failure is - returned otherwise (exit code non-zero). In addition, the - current state is printed in a short string to standard - output, see the table below. Use <option>--quiet</option> to - suppress this output.</para> - - <table> - <title><command>is-system-running</command> output</title> - <tgroup cols='3'> - <colspec colname='name'/> - <colspec colname='description'/> - <colspec colname='exit-code'/> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - <entry>Exit Code</entry> - </row> - </thead> - <tbody> - <row> - <entry><varname>initializing</varname></entry> - <entry><para>Early bootup, before - <filename>basic.target</filename> is reached - or the <varname>maintenance</varname> state entered. - </para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>starting</varname></entry> - <entry><para>Late bootup, before the job queue - becomes idle for the first time, or one of the - rescue targets are reached.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>running</varname></entry> - <entry><para>The system is fully - operational.</para></entry> - <entry>0</entry> - </row> - <row> - <entry><varname>degraded</varname></entry> - <entry><para>The system is operational but one or more - units failed.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>maintenance</varname></entry> - <entry><para>The rescue or emergency target is - active.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>stopping</varname></entry> - <entry><para>The manager is shutting - down.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>offline</varname></entry> - <entry><para>The manager is not - running. Specifically, this is the operational - state if an incompatible program is running as - system manager (PID 1).</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>unknown</varname></entry> - <entry><para>The operational state could not be - determined, due to lack of resources or another - error cause.</para></entry> - <entry>> 0</entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>default</command></term> - - <listitem> - <para>Enter default mode. This is mostly equivalent to - <command>isolate default.target</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>rescue</command></term> - - <listitem> - <para>Enter rescue mode. This is mostly equivalent to - <command>isolate rescue.target</command>, but also prints a - wall message to all users.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>emergency</command></term> - - <listitem> - <para>Enter emergency mode. This is mostly equivalent to - <command>isolate emergency.target</command>, but also prints - a wall message to all users.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>halt</command></term> - - <listitem> - <para>Shut down and halt the system. This is mostly equivalent to <command>start halt.target - --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with - <option>--force</option>, 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 - <option>--force</option> is specified twice, the operation is immediately executed without terminating any - processes or unmounting any file systems. This may result in data loss. Note that when - <option>--force</option> is specified twice the halt operation is executed by - <command>systemctl</command> itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>poweroff</command></term> - - <listitem> - <para>Shut down and power-off the system. This is mostly equivalent to <command>start poweroff.target - --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with - <option>--force</option>, 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 - <option>--force</option> is specified twice, the operation is immediately executed without terminating any - processes or unmounting any file systems. This may result in data loss. Note that when - <option>--force</option> is specified twice the power-off operation is executed by - <command>systemctl</command> itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term> - - <listitem> - <para>Shut down and reboot the system. This is mostly equivalent to <command>start reboot.target - --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with - <option>--force</option>, 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 - <option>--force</option> is specified twice, the operation is immediately executed without terminating any - processes or unmounting any file systems. This may result in data loss. Note that when - <option>--force</option> is specified twice the reboot operation is executed by - <command>systemctl</command> itself, and the system manager is not contacted. This means the command should - succeed even when the system manager hangs or crashed.</para> - - <para>If the optional argument - <replaceable>arg</replaceable> is given, it will be passed - as the optional argument to the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. The value is architecture and firmware - specific. As an example, <literal>recovery</literal> might - be used to trigger system recovery, and - <literal>fota</literal> might be used to trigger a - <quote>firmware over the air</quote> update.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>kexec</command></term> - - <listitem> - <para>Shut down and reboot the system via kexec. This is - mostly equivalent to <command>start kexec.target --job-mode=replace-irreversibly</command>, - but also prints a wall message to all users. If combined - with <option>--force</option>, 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.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term> - - <listitem> - <para>Ask the systemd manager to quit. This is only - supported for user service managers (i.e. in conjunction - with the <option>--user</option> option) or in containers - and is equivalent to <command>poweroff</command> otherwise.</para> - - <para>The systemd manager can exit with a non-zero exit - code if the optional argument - <replaceable>EXIT_CODE</replaceable> is given.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term> - - <listitem> - <para>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 which is loaded from the actual host - volume. 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, equal to the empty string or identical to the path to the systemd binary, 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 phase.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>suspend</command></term> - - <listitem> - <para>Suspend the system. This will trigger activation of - the special <filename>suspend.target</filename> target. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>hibernate</command></term> - - <listitem> - <para>Hibernate the system. This will trigger activation of - the special <filename>hibernate.target</filename> target. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>hybrid-sleep</command></term> - - <listitem> - <para>Hibernate and suspend the system. This will trigger - activation of the special - <filename>hybrid-sleep.target</filename> target.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Parameter Syntax</title> - - <para>Unit commands listed above take either a single unit name (designated as <replaceable>NAME</replaceable>), - or multiple unit specifications (designated as <replaceable>PATTERN</replaceable>...). In the first case, the - unit name with or without a suffix must be given. If the suffix is not specified (unit name is "abbreviated"), - systemctl will append a suitable suffix, <literal>.service</literal> by default, and a type-specific suffix in - case of commands which operate only on specific unit types. For example, - <programlisting># systemctl start sshd</programlisting> and - <programlisting># systemctl start sshd.service</programlisting> - are equivalent, as are - <programlisting># systemctl isolate default</programlisting> - and - <programlisting># systemctl isolate default.target</programlisting> - Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) - paths to mount unit names. - <programlisting># systemctl status /dev/sda -# systemctl status /home</programlisting> - are equivalent to: - <programlisting># systemctl status dev-sda.device -# systemctl status home.mount</programlisting> - In the second case, shell-style globs will be matched against the primary names of all units currently in memory; - literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit - names always refer to exactly one unit, but globs may match zero units and this is not considered an - error.</para> - - <para>Glob patterns use - <citerefentry project='man-pages'><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - so normal shell-style globbing rules are used, and - <literal>*</literal>, <literal>?</literal>, - <literal>[]</literal> may be used. See - <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more details. The patterns are matched against the primary names of - units currently in memory, and patterns which do not match anything - are silently skipped. For example: - <programlisting># systemctl stop sshd@*.service</programlisting> - will stop all <filename>sshd@.service</filename> instances. Note that alias names of units, and units that aren't - in memory are not considered for glob expansion. - </para> - - <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file - (possibly abbreviated, see above), or the absolute path to the unit file: - <programlisting># systemctl enable foo.service</programlisting> - or - <programlisting># systemctl link /path/to/foo.service</programlisting> - </para> - </refsect2> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$SYSTEMD_EDITOR</varname></term> - - <listitem><para>Editor to use when editing units; overrides - <varname>$EDITOR</varname> and <varname>$VISUAL</varname>. If neither - <varname>$SYSTEMD_EDITOR</varname> nor <varname>$EDITOR</varname> nor - <varname>$VISUAL</varname> are present or if it is set to an empty - string or if their execution failed, systemctl will try to execute well - known editors in this order: - <citerefentry project='die-net'><refentrytitle>editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>nano</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>vim</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - <xi:include href="less-variables.xml" xpointer="pager"/> - <xi:include href="less-variables.xml" xpointer="less"/> - <xi:include href="less-variables.xml" xpointer="lesscharset"/> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> |