1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemctl"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>systemctl</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>systemctl</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>systemctl</refname>
48 <refpurpose>Control the systemd system and service manager</refpurpose>
53 <command>systemctl</command>
54 <arg choice="opt" rep="repeat">OPTIONS</arg>
55 <arg choice="plain">COMMAND</arg>
56 <arg choice="opt" rep="repeat">NAME</arg>
61 <title>Description</title>
63 <para><command>systemctl</command> may be used to
64 introspect and control the state of the
65 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
66 system and service manager.</para>
70 <title>Options</title>
72 <para>The following options are understood:</para>
76 <term><option>-t</option></term>
77 <term><option>--type=</option></term>
80 <para>The argument should be a comma-separated list of unit
81 types such as <option>service</option> and
82 <option>socket</option>.
85 <para>If one of the arguments is a unit type, when listing
86 units, limit display to certain unit types. Otherwise, units
87 of all types will be shown.</para>
89 <para>As a special case, if one of the arguments is
90 <option>help</option>, a list of allowed values will be
91 printed and the program will exit.</para>
96 <term><option>--state=</option></term>
99 <para>The argument should be a comma-separated list of unit LOAD,
100 SUB, or ACTIVE states. When listing units, show only those
101 in specified states.</para>
106 <term><option>-p</option></term>
107 <term><option>--property=</option></term>
110 <para>When showing unit/job/manager properties with the
111 <command>show</command> command, limit display to certain
112 properties as specified as argument. If not specified, all
113 set properties are shown. The argument should be a
114 comma-separated list of property names, such as
115 <literal>MainPID</literal>. If specified more than once, all
116 properties with the specified names are shown.</para>
121 <term><option>-a</option></term>
122 <term><option>--all</option></term>
125 <para>When listing units, show all loaded units, regardless
126 of their state, including inactive units. When showing
127 unit/job/manager properties, show all properties regardless
128 whether they are set or not.</para>
129 <para>To list all units installed on the system, use the
130 <command>list-unit-files</command> command instead.</para>
135 <term><option>--reverse</option></term>
138 <para>Show reverse dependencies between units with
139 <command>list-dependencies</command>, i.e. units with
140 dependencies of type <varname>Wants=</varname> or
141 <varname>Requires=</varname> on the given unit.
147 <term><option>--after</option></term>
148 <term><option>--before</option></term>
151 <para>Show which units are started after or before
152 with <command>list-dependencies</command>, respectively.
158 <term><option>-l</option></term>
159 <term><option>--full</option></term>
162 <para>Do not ellipsize unit names, process tree entries,
163 journal output, or truncate unit descriptions in the output
164 of <command>status</command>, <command>list-units</command>,
165 <command>list-jobs</command>, and
166 <command>list-timers</command>.</para>
171 <term><option>--show-types</option></term>
174 <para>When showing sockets, show the type of the socket.</para>
179 <term><option>--job-mode=</option></term>
182 <para>When queuing a new job, this option controls how to deal with
183 already queued jobs. It takes one of <literal>fail</literal>,
184 <literal>replace</literal>,
185 <literal>replace-irreversibly</literal>,
186 <literal>isolate</literal>,
187 <literal>ignore-dependencies</literal>,
188 <literal>ignore-requirements</literal> or
189 <literal>flush</literal>. Defaults to
190 <literal>replace</literal>, except when the
191 <command>isolate</command> command is used which implies the
192 <literal>isolate</literal> job mode.</para>
194 <para>If <literal>fail</literal> is specified and a requested
195 operation conflicts with a pending job (more specifically:
196 causes an already pending start job to be reversed into a stop
197 job or vice versa), cause the operation to fail.</para>
199 <para>If <literal>replace</literal> (the default) is
200 specified, any conflicting pending job will be replaced, as
203 <para>If <literal>replace-irreversibly</literal> is specified,
204 operate like <literal>replace</literal>, but also mark the new
205 jobs as irreversible. This prevents future conflicting
206 transactions from replacing these jobs. The jobs can still be
207 cancelled using the <command>cancel</command> command.</para>
209 <para><literal>isolate</literal> is only valid for start
210 operations and causes all other units to be stopped when the
211 specified unit is started. This mode is always used when the
212 <command>isolate</command> command is used.</para>
214 <para><literal>flush</literal> will cause all queued jobs to
215 be canceled when the new job is enqueued.</para>
217 <para>If <literal>ignore-dependencies</literal> is specified,
218 then all unit dependencies are ignored for this new job and
219 the operation is executed immediately. If passed, no required
220 units of the unit passed will be pulled in, and no ordering
221 dependencies will be honored. This is mostly a debugging and
222 rescue tool for the administrator and should not be used by
225 <para><literal>ignore-requirements</literal> is similar to
226 <literal>ignore-dependencies</literal>, but only causes the
227 requirement dependencies to be ignored, the ordering
228 dependencies will still be honoured.</para>
234 <term><option>-i</option></term>
235 <term><option>--ignore-inhibitors</option></term>
238 <para>When system shutdown or a sleep state is requested,
239 ignore inhibitor locks. Applications can establish inhibitor
240 locks to avoid that certain important operations (such as CD
241 burning or suchlike) are interrupted by system shutdown or a
242 sleep state. Any user may take these locks and privileged
243 users may override these locks. If any locks are taken,
244 shutdown and sleep state requests will normally fail
245 (regardless of whether privileged or not) and a list of active locks
246 is printed. However, if <option>--ignore-inhibitors</option>
247 is specified, the locks are ignored and not printed, and the
248 operation attempted anyway, possibly requiring additional
254 <term><option>-q</option></term>
255 <term><option>--quiet</option></term>
258 <para>Suppress output to standard output in
259 <command>snapshot</command>,
260 <command>is-active</command>,
261 <command>is-failed</command>,
262 <command>enable</command> and
263 <command>disable</command>.</para>
268 <term><option>--no-block</option></term>
271 <para>Do not synchronously wait for the requested operation
272 to finish. If this is not specified, the job will be
273 verified, enqueued and <command>systemctl</command> will
274 wait until it is completed. By passing this argument, it is
275 only verified and enqueued.</para>
280 <term><option>--no-legend</option></term>
283 <para>Do not print the legend, i.e. the column headers and
284 the footer with hints.</para>
289 <term><option>--system</option></term>
292 <para>Talk to the systemd system manager. (Default)</para>
297 <term><option>--user</option></term>
300 <para>Talk to the systemd manager of the calling
306 <term><option>--no-wall</option></term>
309 <para>Do not send wall message before halt, power-off,
315 <term><option>--global</option></term>
318 <para>When used with <command>enable</command> and
319 <command>disable</command>, operate on the global user
320 configuration directory, thus enabling or disabling a unit
321 file globally for all future logins of all users.</para>
326 <term><option>--no-reload</option></term>
329 <para>When used with <command>enable</command> and
330 <command>disable</command>, do not implicitly reload daemon
331 configuration after executing the changes.</para>
336 <term><option>--no-ask-password</option></term>
339 <para>When used with <command>start</command> and related
340 commands, disables asking for passwords. Background services
341 may require input of a password or passphrase string, for
342 example to unlock system hard disks or cryptographic
343 certificates. Unless this option is specified and the
344 command is invoked from a terminal,
345 <command>systemctl</command> will query the user on the
346 terminal for the necessary secrets. Use this option to
347 switch this behavior off. In this case, the password must be
348 supplied by some other means (for example graphical password
349 agents) or the service might fail. This also disables
350 querying the user for authentication for privileged
357 <term><option>--kill-who=</option></term>
360 <para>When used with <command>kill</command>, choose which
361 processes to kill. Must be one of <option>main</option>,
362 <option>control</option> or <option>all</option> to select
363 whether to kill only the main process of the unit, the
364 control process or all processes of the unit. If omitted,
365 defaults to <option>all</option>.</para>
371 <term><option>-s</option></term>
372 <term><option>--signal=</option></term>
375 <para>When used with <command>kill</command>, choose which
376 signal to send to selected processes. Must be one of the
377 well known signal specifiers such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
378 <constant>SIGSTOP</constant>. If omitted, defaults to
379 <option>SIGTERM</option>.</para>
384 <term><option>-f</option></term>
385 <term><option>--force</option></term>
388 <para>When used with <command>enable</command>, overwrite
389 any existing conflicting symlinks.</para>
391 <para>When used with <command>halt</command>,
392 <command>poweroff</command>, <command>reboot</command> or
393 <command>kexec</command>, execute the selected operation
394 without shutting down all units. However, all processes will
395 be killed forcibly and all file systems are unmounted or
396 remounted read-only. This is hence a drastic but relatively
397 safe option to request an immediate reboot. If
398 <option>--force</option> is specified twice for these
399 operations, they will be executed immediately without
400 terminating any processes or umounting any file
401 systems. Warning: specifying <option>--force</option> twice
402 with any of these operations might result in data
408 <term><option>--root=</option></term>
412 <command>enable</command>/<command>disable</command>/<command>is-enabled</command>
413 (and related commands), use alternative root path when
414 looking for unit files.</para>
420 <term><option>--runtime</option></term>
423 <para>When used with <command>enable</command>,
424 <command>disable</command>,
425 (and related commands), make changes only temporarily, so
426 that they are lost on the next reboot. This will have the
427 effect that changes are not made in subdirectories of
428 <filename>/etc</filename> but in <filename>/run</filename>,
429 with identical immediate effects, however, since the latter
430 is lost on reboot, the changes are lost too.</para>
432 <para>Similarly, when used with
433 <command>set-property</command>, make changes only
434 temporarily, so that they are lost on the next
440 <term><option>-H</option></term>
441 <term><option>--host</option></term>
444 <para>Execute the operation remotely. Specify a hostname, or
445 username and hostname separated by <literal>@</literal>, to
446 connect to. This will use SSH to talk to the remote systemd
452 <term><option>-M</option></term>
453 <term><option>--machine=</option></term>
455 <listitem><para>Execute the operation on a local
456 container. Specify a container name to connect
457 to.</para></listitem>
461 <term><option>-n</option></term>
462 <term><option>--lines=</option></term>
465 <para>When used with <command>status</command>, controls the
466 number of journal lines to show, counting from the most
467 recent ones. Takes a positive integer argument. Defaults to
473 <term><option>-o</option></term>
474 <term><option>--output=</option></term>
477 <para>When used with <command>status</command>, controls the
478 formatting of the journal entries that are shown. For the
479 available choices, see
480 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
481 Defaults to <literal>short</literal>.</para>
486 <term><option>--plain</option></term>
489 <para>When used with <command>list-dependencies</command>,
490 the output is printed as a list instead of a tree.</para>
494 <xi:include href="standard-options.xml" xpointer="help" />
495 <xi:include href="standard-options.xml" xpointer="version" />
496 <xi:include href="standard-options.xml" xpointer="no-pager" />
501 <title>Commands</title>
503 <para>The following commands are understood:</para>
506 <title>Unit Commands</title>
510 <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
513 <para>List known units (subject to limitations specified
514 with <option>-t</option>). If one or more
515 <replaceable>PATTERN</replaceable>s are specified, only
516 units matching one of them are shown.</para>
518 <para>This is the default command.</para>
523 <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
526 <para>List socket units ordered by listening address.
527 If one or more <replaceable>PATTERN</replaceable>s are
528 specified, only socket units matching one of them are
529 shown. Produces output similar to
531 LISTEN UNIT ACTIVATES
532 /dev/initctl systemd-initctl.socket systemd-initctl.service
534 [::]:22 sshd.socket sshd.service
535 kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
537 5 sockets listed.</programlisting>
538 Note: because the addresses might contains spaces, this output
539 is not suitable for programmatic consumption.
542 <para>See also the options <option>--show-types</option>,
543 <option>--all</option>, and <option>--failed</option>.</para>
548 <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
551 <para>List timer units ordered by the time they elapse
552 next. If one or more <replaceable>PATTERN</replaceable>s
553 are specified, only units matching one of them are shown.
556 <para>See also the options <option>--all</option> and
557 <option>--failed</option>.</para>
562 <term><command>start <replaceable>PATTERN</replaceable>...</command></term>
565 <para>Start (activate) one or more units specified on the
568 <para>Note that glob patterns operate on a list of currently
569 loaded units. Units which are not active and are not in a
570 failed state usually are not loaded, and would not be
571 matched by any pattern. In addition, in case of
572 instantiated units, systemd is often unaware of the
573 instance name until the instance has been started. Therefore,
574 using glob patterns with <command>start</command>
575 has limited usefulness.</para>
579 <term><command>stop <replaceable>PATTERN</replaceable>...</command></term>
582 <para>Stop (deactivate) one or more units specified on the
587 <term><command>reload <replaceable>PATTERN</replaceable>...</command></term>
590 <para>Asks all units listed on the command line to reload
591 their configuration. Note that this will reload the
592 service-specific configuration, not the unit configuration
593 file of systemd. If you want systemd to reload the
594 configuration file of a unit, use the
595 <command>daemon-reload</command> command. In other words:
596 for the example case of Apache, this will reload Apache's
597 <filename>httpd.conf</filename> in the web server, not the
598 <filename>apache.service</filename> systemd unit
601 <para>This command should not be confused with the
602 <command>daemon-reload</command> or <command>load</command>
608 <term><command>restart <replaceable>PATTERN</replaceable>...</command></term>
611 <para>Restart one or more units specified on the command
612 line. If the units are not running yet, they will be
617 <term><command>try-restart <replaceable>PATTERN</replaceable>...</command></term>
620 <para>Restart one or more units specified on the command
621 line if the units are running. This does nothing if units are not
622 running. Note that, for compatibility with Red Hat init
623 scripts, <command>condrestart</command> is equivalent to this
628 <term><command>reload-or-restart <replaceable>PATTERN</replaceable>...</command></term>
631 <para>Reload one or more units if they support it. If not,
632 restart them instead. If the units are not running yet, they
633 will be started.</para>
637 <term><command>reload-or-try-restart <replaceable>PATTERN</replaceable>...</command></term>
640 <para>Reload one or more units if they support it. If not,
641 restart them instead. This does nothing if the units are not
642 running. Note that, for compatibility with SysV init scripts,
643 <command>force-reload</command> is equivalent to this
648 <term><command>isolate <replaceable>NAME</replaceable></command></term>
651 <para>Start the unit specified on the command line and its
652 dependencies and stop all others.</para>
654 <para>This is similar to changing the runlevel in a
655 traditional init system. The <command>isolate</command>
656 command will immediately stop processes that are not enabled
657 in the new unit, possibly including the graphical
658 environment or terminal you are currently using.</para>
660 <para>Note that this is allowed only on units where
661 <option>AllowIsolate=</option> is enabled. See
662 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
667 <term><command>kill <replaceable>PATTERN</replaceable>...</command></term>
670 <para>Send a signal to one or more processes of the
671 unit. Use <option>--kill-who=</option> to select which
672 process to kill. Use <option>--kill-mode=</option> to select
673 the kill mode and <option>--signal=</option> to select the
674 signal to send.</para>
678 <term><command>is-active <replaceable>PATTERN</replaceable>...</command></term>
681 <para>Check whether any of the specified units are active
682 (i.e. running). Returns an exit code
683 <constant>0</constant> if at least one is active, or
684 non-zero otherwise. Unless <option>--quiet</option> is
685 specified, this will also print the current unit state to
686 standard output.</para>
690 <term><command>is-failed <replaceable>PATTERN</replaceable>...</command></term>
693 <para>Check whether any of the specified units are in a
694 "failed" state. Returns an exit code
695 <constant>0</constant> if at least one has failed,
696 non-zero otherwise. Unless <option>--quiet</option> is
697 specified, this will also print the current unit state to
698 standard output.</para>
702 <term><command>status</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...]</optional></term>
705 <para>Show terse runtime status information about one or
706 more units, followed by most recent log data from the
707 journal. If no units are specified, show all units (subject
708 to limitations specified with <option>-t</option>). If a PID
709 is passed, show information about the unit the process
712 <para>This function is intended to generate human-readable
713 output. If you are looking for computer-parsable output,
714 use <command>show</command> instead. By default this
715 function only shows 10 lines of output and ellipsizes
716 lines to fit in the terminal window. This can be changes
717 with <option>--lines</option> and <option>--full</option>,
718 see above. In addition, <command>journalctl
719 --unit=<replaceable>NAME</replaceable></command> or
721 --user-unit=<replaceable>NAME</replaceable></command> use
722 a similar filter for messages and might be more
728 <term><command>show</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>JOB</replaceable>...</optional></term>
731 <para>Show properties of one or more units, jobs, or the
732 manager itself. If no argument is specified, properties of
733 the manager will be shown. If a unit name is specified,
734 properties of the unit is shown, and if a job id is
735 specified, properties of the job is shown. By default, empty
736 properties are suppressed. Use <option>--all</option> to
737 show those too. To select specific properties to show, use
738 <option>--property=</option>. This command is intended to be
739 used whenever computer-parsable output is required. Use
740 <command>status</command> if you are looking for formatted
741 human-readable output.</para>
745 <term><command>cat <replaceable>PATTERN</replaceable>...</command></term>
748 <para>Show backing files of one or more units. Prints the
749 "fragment" and "drop-ins" (source files) of units. Each
750 file is preceded by a comment which includes the file
755 <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>...</command></term>
758 <para>Set the specified unit properties at runtime where
759 this is supported. This allows changing configuration
760 parameter properties such as resource control settings at
761 runtime. Not all properties may be changed at runtime, but
762 many resource control settings (primarily those in
763 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
764 may. The changes are applied instantly, and stored on disk
765 for future boots, unless <option>--runtime</option> is
766 passed, in which case the settings only apply until the
767 next reboot. The syntax of the property assignment follows
768 closely the syntax of assignments in unit files.</para>
770 <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para>
772 <para>Note that this command allows changing multiple
773 properties at the same time, which is preferable over
774 setting them individually. Like unit file configuration
775 settings, assigning the empty list to list parameters will
776 reset the list.</para>
781 <term><command>help <replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...</command></term>
784 <para>Show manual pages for one or more units, if
785 available. If a PID is given, the manual pages for the unit
786 the process belongs to are shown.</para>
791 <term><command>reset-failed [<replaceable>PATTERN</replaceable>...]</command></term>
794 <para>Reset the <literal>failed</literal> state of the
795 specified units, or if no unit name is passed, reset the state of all
796 units. When a unit fails in some way (i.e. process exiting
797 with non-zero error code, terminating abnormally or timing
798 out), it will automatically enter the
799 <literal>failed</literal> state and its exit code and status
800 is recorded for introspection by the administrator until the
801 service is restarted or reset with this command.</para>
806 <term><command>list-dependencies <replaceable>NAME</replaceable></command></term>
809 <para>Shows required and wanted units of the specified
810 unit. If no unit is specified,
811 <filename>default.target</filename> is implied. Target units
812 are recursively expanded. When <option>--all</option> is
813 passed, all other units are recursively expanded as
821 <title>Unit File Commands</title>
825 <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term>
828 <para>List installed unit files. If one or more
829 <replaceable>PATTERN</replaceable>s are specified, only
830 units whose filename (just the last component of the path)
831 matches one of them are shown.</para>
836 <term><command>enable <replaceable>NAME</replaceable>...</command></term>
839 <para>Enable one or more unit files or unit file instances,
840 as specified on the command line. This will create a number
841 of symlinks as encoded in the <literal>[Install]</literal>
842 sections of the unit files. After the symlinks have been
843 created, the systemd configuration is reloaded (in a way that
844 is equivalent to <command>daemon-reload</command>) to ensure
845 the changes are taken into account immediately. Note that
846 this does <emphasis>not</emphasis> have the effect of also
847 starting any of the units being enabled. If this
848 is desired, a separate <command>start</command> command must
849 be invoked for the unit. Also note that in case of instance
850 enablement, symlinks named the same as instances are created in
851 the install location, however they all point to the same
852 template unit file.</para>
854 <para>This command will print the actions executed. This
855 output may be suppressed by passing <option>--quiet</option>.
858 <para>Note that this operation creates only the suggested
859 symlinks for the units. While this command is the
860 recommended way to manipulate the unit configuration
861 directory, the administrator is free to make additional
862 changes manually by placing or removing symlinks in the
863 directory. This is particularly useful to create
864 configurations that deviate from the suggested default
865 installation. In this case, the administrator must make sure
866 to invoke <command>daemon-reload</command> manually as
867 necessary to ensure the changes are taken into account.
870 <para>Enabling units should not be confused with starting
871 (activating) units, as done by the <command>start</command>
872 command. Enabling and starting units is orthogonal: units
873 may be enabled without being started and started without
874 being enabled. Enabling simply hooks the unit into various
875 suggested places (for example, so that the unit is
876 automatically started on boot or when a particular kind of
877 hardware is plugged in). Starting actually spawns the daemon
878 process (in case of service units), or binds the socket (in
879 case of socket units), and so on.</para>
881 <para>Depending on whether <option>--system</option>,
882 <option>--user</option>, <option>--runtime</option>,
883 or <option>--global</option> is specified, this enables the unit
884 for the system, for the calling user only, for only this boot of
885 the system, or for all future logins of all users, or only this
886 boot. Note that in the last case, no systemd daemon
887 configuration is reloaded.</para>
892 <term><command>disable <replaceable>NAME</replaceable>...</command></term>
895 <para>Disables one or more units. This removes all symlinks
896 to the specified unit files from the unit configuration
897 directory, and hence undoes the changes made by
898 <command>enable</command>. Note however that this removes
899 all symlinks to the unit files (i.e. including manual
900 additions), not just those actually created by
901 <command>enable</command>. This call implicitly reloads the
902 systemd daemon configuration after completing the disabling
903 of the units. Note that this command does not implicitly
904 stop the units that are being disabled. If this is desired,
905 an additional <command>stop</command> command should be
906 executed afterwards.</para>
908 <para>This command will print the actions executed. This
909 output may be suppressed by passing <option>--quiet</option>.
912 <para>This command honors <option>--system</option>,
913 <option>--user</option>, <option>--runtime</option> and
914 <option>--global</option> in a similar way as
915 <command>enable</command>.</para>
920 <term><command>is-enabled <replaceable>NAME</replaceable>...</command></term>
923 <para>Checks whether any of the specified unit files are
924 enabled (as with <command>enable</command>). Returns an
925 exit code of 0 if at least one is enabled, non-zero
926 otherwise. Prints the current enable status (see table).
927 To suppress this output, use <option>--quiet</option>.
932 <command>is-enabled</command> output
938 <entry>Printed string</entry>
939 <entry>Meaning</entry>
940 <entry>Return value</entry>
945 <entry><literal>enabled</literal></entry>
946 <entry morerows='1'>Enabled through a symlink in <filename>.wants</filename> directory (permanently or just in <filename>/run</filename>)</entry>
947 <entry morerows='1'>0</entry>
950 <entry><literal>enabled-runtime</literal></entry>
953 <entry><literal>linked</literal></entry>
954 <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>)</entry>
955 <entry morerows='1'>1</entry>
958 <entry><literal>linked-runtime</literal></entry>
961 <entry><literal>masked</literal></entry>
962 <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>)</entry>
963 <entry morerows='1'>1</entry>
966 <entry><literal>masked-runtime</literal></entry>
969 <entry><literal>static</literal></entry>
970 <entry>Unit is not enabled, but has no provisions for enabling in [Install] section</entry>
974 <entry><literal>disabled</literal></entry>
975 <entry>Unit is not enabled</entry>
986 <term><command>reenable <replaceable>NAME</replaceable>...</command></term>
989 <para>Reenable one or more unit files, as specified on the
990 command line. This is a combination of
991 <command>disable</command> and <command>enable</command> and
992 is useful to reset the symlinks a unit is enabled with to
993 the defaults configured in the <literal>[Install]</literal>
994 section of the unit file.</para>
999 <term><command>preset <replaceable>NAME</replaceable>...</command></term>
1002 <para>Reset one or more unit files, as specified on the
1003 command line, to the defaults configured in the preset
1004 policy files. This has the same effect as
1005 <command>disable</command> or <command>enable</command>,
1006 depending how the unit is listed in the preset files. For
1007 more information on the preset policy format, see
1008 <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1009 For more information on the concept of presets, please
1011 <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
1017 <term><command>mask <replaceable>NAME</replaceable>...</command></term>
1020 <para>Mask one or more unit files, as specified on the
1021 command line. This will link these units to
1022 <filename>/dev/null</filename>, making it impossible to
1023 start them. This is a stronger version of
1024 <command>disable</command>, since it prohibits all kinds of
1025 activation of the unit, including manual activation. Use
1026 this option with care. This honors the
1027 <option>--runtime</option> option to only mask temporarily
1028 until the next reoobt of the system.</para>
1033 <term><command>unmask <replaceable>NAME</replaceable>...</command></term>
1036 <para>Unmask one or more unit files, as specified on the
1037 command line. This will undo the effect of
1038 <command>mask</command>.</para>
1043 <term><command>link <replaceable>FILENAME</replaceable>...</command></term>
1046 <para>Link a unit file that is not in the unit file search
1047 paths into the unit file search path. This requires an
1048 absolute path to a unit file. The effect of this can be
1049 undone with <command>disable</command>. The effect of this
1050 command is that a unit file is available for
1051 <command>start</command> and other commands although it
1052 is not installed directly in the unit search path.</para>
1057 <term><command>get-default</command></term>
1060 <para>Get the default target specified
1061 via <filename>default.target</filename> link.</para>
1066 <term><command>set-default <replaceable>NAME</replaceable></command></term>
1069 <para>Set the default target to boot into. Command links
1070 <filename>default.target</filename> to the given unit.</para>
1077 <title>Job Commands</title>
1081 <term><command>list-jobs <optional><replaceable>PATTERN...</replaceable></optional></command></term>
1084 <para>List jobs that are in progress. If one or more
1085 <replaceable>PATTERN</replaceable>s are specified, only
1086 jobs for units matching one of them are shown.</para>
1090 <term><command>cancel <replaceable>JOB</replaceable>...</command></term>
1093 <para>Cancel one or more jobs specified on the command line
1094 by their numeric job IDs. If no job ID is specified, cancel
1095 all pending jobs.</para>
1102 <title>Snapshot Commands</title>
1106 <term><command>snapshot <optional><replaceable>NAME</replaceable></optional></command></term>
1109 <para>Create a snapshot. If a snapshot name is specified,
1110 the new snapshot will be named after it. If none is
1111 specified, an automatic snapshot name is generated. In
1112 either case, the snapshot name used is printed to standard
1113 output, unless <option>--quiet</option> is specified.
1116 <para>A snapshot refers to a saved state of the systemd
1117 manager. It is implemented itself as a unit that is
1118 generated dynamically with this command and has dependencies
1119 on all units active at the time. At a later time, the user
1120 may return to this state by using the
1121 <command>isolate</command> command on the snapshot unit.
1124 <para>Snapshots are only useful for saving and restoring
1125 which units are running or are stopped, they do not
1126 save/restore any other state. Snapshots are dynamic and lost
1131 <term><command>delete <replaceable>PATTERN</replaceable>...</command></term>
1134 <para>Remove a snapshot previously created with
1135 <command>snapshot</command>.</para>
1142 <title>Environment Commands</title>
1146 <term><command>show-environment</command></term>
1149 <para>Dump the systemd manager environment block. The
1150 environment block will be dumped in straight-forward form
1151 suitable for sourcing into a shell script. This environment
1152 block will be passed to all processes the manager
1157 <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>...</command></term>
1160 <para>Set one or more systemd manager environment variables,
1161 as specified on the command line.</para>
1165 <term><command>unset-environment <replaceable>VARIABLE</replaceable>...</command></term>
1168 <para>Unset one or more systemd manager environment
1169 variables. If only a variable name is specified, it will be
1170 removed regardless of its value. If a variable and a value
1171 are specified, the variable is only removed if it has the
1172 specified value.</para>
1176 <term><command>import-environment <replaceable>VARIABLE</replaceable>...</command></term>
1179 <para>Import all, one or more environment variables set on
1180 the client into the systemd manager environment block. If
1181 no arguments are passed, the entire environment block is
1182 imported. Otherwise, a list of one or more environment
1183 variable names should be passed, whose client-side values
1184 are then imported into the manager's environment
1192 <title>Manager Lifecycle Commands</title>
1196 <term><command>daemon-reload</command></term>
1199 <para>Reload systemd manager configuration. This will reload
1200 all unit files and recreate the entire dependency
1201 tree. While the daemon is being reloaded, all sockets systemd
1202 listens on on behalf of user configuration will stay
1203 accessible.</para> <para>This command should not be confused
1204 with the <command>load</command> or
1205 <command>reload</command> commands.</para>
1209 <term><command>daemon-reexec</command></term>
1212 <para>Reexecute the systemd manager. This will serialize the
1213 manager state, reexecute the process and deserialize the
1214 state again. This command is of little use except for
1215 debugging and package upgrades. Sometimes, it might be
1216 helpful as a heavy-weight <command>daemon-reload</command>.
1217 While the daemon is being reexecuted, all sockets systemd listening
1218 on behalf of user configuration will stay accessible.
1226 <title>System Commands</title>
1230 <term><command>default</command></term>
1233 <para>Enter default mode. This is mostly equivalent to
1234 <command>isolate default.target</command>.</para>
1238 <term><command>rescue</command></term>
1241 <para>Enter rescue mode. This is mostly equivalent to
1242 <command>isolate rescue.target</command>, but also prints a
1243 wall message to all users.</para>
1247 <term><command>emergency</command></term>
1250 <para>Enter emergency mode. This is mostly equivalent to
1251 <command>isolate emergency.target</command>, but also prints
1252 a wall message to all users.</para>
1256 <term><command>halt</command></term>
1259 <para>Shut down and halt the system. This is mostly equivalent to
1260 <command>start halt.target --irreversible</command>, but also
1261 prints a wall message to all users. If combined with
1262 <option>--force</option>, shutdown of all running services is
1263 skipped, however all processes are killed and all file
1264 systems are unmounted or mounted read-only, immediately
1265 followed by the system halt. If <option>--force</option> is
1266 specified twice, the operation is immediately executed
1267 without terminating any processes or unmounting any file
1268 systems. This may result in data loss.</para>
1272 <term><command>poweroff</command></term>
1275 <para>Shut down and power-off the system. This is mostly
1276 equivalent to <command>start poweroff.target --irreversible</command>,
1277 but also prints a wall message to all users. If combined with
1278 <option>--force</option>, shutdown of all running services is
1279 skipped, however all processes are killed and all file
1280 systems are unmounted or mounted read-only, immediately
1281 followed by the powering off. If <option>--force</option> is
1282 specified twice, the operation is immediately executed
1283 without terminating any processes or unmounting any file
1284 systems. This may result in data loss.</para>
1288 <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
1291 <para>Shut down and reboot the system. This is mostly
1292 equivalent to <command>start reboot.target --irreversible</command>,
1293 but also prints a wall message to all users. If combined with
1294 <option>--force</option>, shutdown of all running services is
1295 skipped, however all processes are killed and all file
1296 systems are unmounted or mounted read-only, immediately
1297 followed by the reboot. If <option>--force</option> is
1298 specified twice, the operation is immediately executed
1299 without terminating any processes or unmounting any file
1300 systems. This may result in data loss.</para>
1302 <para>If the optional argument
1303 <replaceable>arg</replaceable> is given, it will be passed
1304 as the optional argument to the
1305 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1306 system call. The value is architecture and firmware
1307 specific. As an example, <literal>recovery</literal> might
1308 be used to trigger system recovery, and
1309 <literal>fota</literal> might be used to trigger a
1310 <quote>firmware over the air</quote> update.</para>
1314 <term><command>kexec</command></term>
1317 <para>Shut down and reboot the system via kexec. This is
1318 mostly equivalent to <command>start kexec.target --irreversible</command>,
1319 but also prints a wall message to all users. If combined
1320 with <option>--force</option>, shutdown of all running
1321 services is skipped, however all processes are killed and
1322 all file systems are unmounted or mounted read-only,
1323 immediately followed by the reboot.</para>
1327 <term><command>exit</command></term>
1330 <para>Ask the systemd manager to quit. This is only
1331 supported for user service managers (i.e. in conjunction
1332 with the <option>--user</option> option) and will fail
1338 <term><command>suspend</command></term>
1341 <para>Suspend the system. This will trigger activation of
1342 the special <filename>suspend.target</filename> target.
1347 <term><command>hibernate</command></term>
1350 <para>Hibernate the system. This will trigger activation of
1351 the special <filename>hibernate.target</filename> target.
1356 <term><command>hybrid-sleep</command></term>
1359 <para>Hibernate and suspend the system. This will trigger
1360 activation of the special
1361 <filename>hybrid-sleep.target</filename> target.</para>
1365 <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term>
1368 <para>Switches to a different root directory and executes a
1369 new system manager process below it. This is intended for
1370 usage in initial RAM disks ("initrd"), and will transition
1371 from the initrd's system manager process (a.k.a "init"
1372 process) to the main system manager process. This call takes two
1373 arguments: the directory that is to become the new root directory, and
1374 the path to the new system manager binary below it to
1375 execute as PID 1. If the latter is omitted or the empty
1376 string, a systemd binary will automatically be searched for
1377 and used as init. If the system manager path is omitted or
1378 equal to the empty string, the state of the initrd's system
1379 manager process is passed to the main system manager, which
1380 allows later introspection of the state of the services
1381 involved in the initrd boot.</para>
1388 <title>Parameter Syntax</title>
1390 <para>Unit ommands listed above take either a single unit name
1391 (designated as <replaceable>NAME</replaceable>), or multiple
1392 unit specifications (designated as
1393 <replaceable>PATTERN</replaceable>...). In the first case, the
1394 unit name with or without a suffix must be given. If the suffix
1395 is not specified, systemctl will append a suitable suffix,
1396 <literal>.service</literal> by default, and a type-specific
1397 suffix in case of commands which operate only on specific unit
1399 <programlisting># systemctl start sshd</programlisting> and
1400 <programlisting># systemctl start sshd.service</programlisting>
1401 are equivalent, as are
1402 <programlisting># systemctl isolate snapshot-11</programlisting>
1404 <programlisting># systemctl isolate snapshot-11.snapshot</programlisting>
1405 Note that (absolute) paths to device nodes are automatically
1406 converted to device unit names, and other (absolute) paths to
1408 <programlisting># systemctl status /dev/sda
1409 # systemctl status /home</programlisting>
1411 <programlisting># systemctl status dev-sda.device
1412 # systemctl status home.mount</programlisting>
1413 In the second case, shell-style globs will be matched against
1414 currently loaded units; literal unit names, with or without
1415 a suffix, will be treated as in the first case. This means that
1416 literal unit names always refer to exactly one unit, but globs
1417 may match zero units and this is not considered an error.</para>
1419 <para>Glob patterns use
1420 <citerefentry><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
1421 so normal shell-style globbing rules are used, and
1422 <literal>*</literal>, <literal>?</literal>,
1423 <literal>[]</literal> may be used. See
1424 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1425 for more details. The patterns are matched against the names of
1426 currently loaded units, and patterns which do not match anything
1427 are silently skipped. For example:
1428 <programlisting># systemctl stop sshd@*.service</programlisting>
1429 will stop all <filename>sshd@.service</filename> instances.
1432 <para>For unit file commands, the specified
1433 <replaceable>NAME</replaceable> should be the full name of the
1434 unit file, or the absolute path to the unit file:
1435 <programlisting># systemctl enable foo.service</programlisting>
1437 <programlisting># systemctl link /path/to/foo.service</programlisting>
1444 <title>Exit status</title>
1446 <para>On success, 0 is returned, a non-zero failure
1447 code otherwise.</para>
1450 <xi:include href="less-variables.xml" />
1453 <title>See Also</title>
1455 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1456 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1457 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1458 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1459 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1460 <citerefentry><refentrytitle>systemd.resource-management</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1461 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1462 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1463 <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1464 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>