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>
288 <xi:include href="user-system-options.xml" xpointer="user" />
289 <xi:include href="user-system-options.xml" xpointer="system" />
292 <term><option>--no-wall</option></term>
295 <para>Do not send wall message before halt, power-off,
301 <term><option>--global</option></term>
304 <para>When used with <command>enable</command> and
305 <command>disable</command>, operate on the global user
306 configuration directory, thus enabling or disabling a unit
307 file globally for all future logins of all users.</para>
312 <term><option>--no-reload</option></term>
315 <para>When used with <command>enable</command> and
316 <command>disable</command>, do not implicitly reload daemon
317 configuration after executing the changes.</para>
322 <term><option>--no-ask-password</option></term>
325 <para>When used with <command>start</command> and related
326 commands, disables asking for passwords. Background services
327 may require input of a password or passphrase string, for
328 example to unlock system hard disks or cryptographic
329 certificates. Unless this option is specified and the
330 command is invoked from a terminal,
331 <command>systemctl</command> will query the user on the
332 terminal for the necessary secrets. Use this option to
333 switch this behavior off. In this case, the password must be
334 supplied by some other means (for example graphical password
335 agents) or the service might fail. This also disables
336 querying the user for authentication for privileged
343 <term><option>--kill-who=</option></term>
346 <para>When used with <command>kill</command>, choose which
347 processes to kill. Must be one of <option>main</option>,
348 <option>control</option> or <option>all</option> to select
349 whether to kill only the main process of the unit, the
350 control process or all processes of the unit. If omitted,
351 defaults to <option>all</option>.</para>
357 <term><option>-s</option></term>
358 <term><option>--signal=</option></term>
361 <para>When used with <command>kill</command>, choose which
362 signal to send to selected processes. Must be one of the
363 well known signal specifiers such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
364 <constant>SIGSTOP</constant>. If omitted, defaults to
365 <option>SIGTERM</option>.</para>
370 <term><option>-f</option></term>
371 <term><option>--force</option></term>
374 <para>When used with <command>enable</command>, overwrite
375 any existing conflicting symlinks.</para>
377 <para>When used with <command>halt</command>,
378 <command>poweroff</command>, <command>reboot</command> or
379 <command>kexec</command>, execute the selected operation
380 without shutting down all units. However, all processes will
381 be killed forcibly and all file systems are unmounted or
382 remounted read-only. This is hence a drastic but relatively
383 safe option to request an immediate reboot. If
384 <option>--force</option> is specified twice for these
385 operations, they will be executed immediately without
386 terminating any processes or umounting any file
387 systems. Warning: specifying <option>--force</option> twice
388 with any of these operations might result in data
394 <term><option>--root=</option></term>
398 <command>enable</command>/<command>disable</command>/<command>is-enabled</command>
399 (and related commands), use alternative root path when
400 looking for unit files.</para>
406 <term><option>--runtime</option></term>
409 <para>When used with <command>enable</command>,
410 <command>disable</command>,
411 (and related commands), make changes only temporarily, so
412 that they are lost on the next reboot. This will have the
413 effect that changes are not made in subdirectories of
414 <filename>/etc</filename> but in <filename>/run</filename>,
415 with identical immediate effects, however, since the latter
416 is lost on reboot, the changes are lost too.</para>
418 <para>Similarly, when used with
419 <command>set-property</command>, make changes only
420 temporarily, so that they are lost on the next
426 <term><option>-H</option></term>
427 <term><option>--host</option></term>
430 <para>Execute the operation remotely. Specify a hostname, or
431 username and hostname separated by <literal>@</literal>, to
432 connect to. This will use SSH to talk to the remote systemd
438 <term><option>-M</option></term>
439 <term><option>--machine=</option></term>
441 <listitem><para>Execute the operation on a local
442 container. Specify a container name to connect
443 to.</para></listitem>
447 <term><option>-n</option></term>
448 <term><option>--lines=</option></term>
451 <para>When used with <command>status</command>, controls the
452 number of journal lines to show, counting from the most
453 recent ones. Takes a positive integer argument. Defaults to
459 <term><option>-o</option></term>
460 <term><option>--output=</option></term>
463 <para>When used with <command>status</command>, controls the
464 formatting of the journal entries that are shown. For the
465 available choices, see
466 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
467 Defaults to <literal>short</literal>.</para>
472 <term><option>--plain</option></term>
475 <para>When used with <command>list-dependencies</command>,
476 the output is printed as a list instead of a tree.</para>
480 <xi:include href="standard-options.xml" xpointer="help" />
481 <xi:include href="standard-options.xml" xpointer="version" />
482 <xi:include href="standard-options.xml" xpointer="no-pager" />
487 <title>Commands</title>
489 <para>The following commands are understood:</para>
492 <title>Unit Commands</title>
496 <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
499 <para>List known units (subject to limitations specified
500 with <option>-t</option>). If one or more
501 <replaceable>PATTERN</replaceable>s are specified, only
502 units matching one of them are shown.</para>
504 <para>This is the default command.</para>
509 <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
512 <para>List socket units ordered by listening address.
513 If one or more <replaceable>PATTERN</replaceable>s are
514 specified, only socket units matching one of them are
515 shown. Produces output similar to
517 LISTEN UNIT ACTIVATES
518 /dev/initctl systemd-initctl.socket systemd-initctl.service
520 [::]:22 sshd.socket sshd.service
521 kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
523 5 sockets listed.</programlisting>
524 Note: because the addresses might contains spaces, this output
525 is not suitable for programmatic consumption.
528 <para>See also the options <option>--show-types</option>,
529 <option>--all</option>, and <option>--failed</option>.</para>
534 <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
537 <para>List timer units ordered by the time they elapse
538 next. If one or more <replaceable>PATTERN</replaceable>s
539 are specified, only units matching one of them are shown.
542 <para>See also the options <option>--all</option> and
543 <option>--failed</option>.</para>
548 <term><command>start <replaceable>PATTERN</replaceable>...</command></term>
551 <para>Start (activate) one or more units specified on the
554 <para>Note that glob patterns operate on a list of currently
555 loaded units. Units which are not active and are not in a
556 failed state usually are not loaded, and would not be
557 matched by any pattern. In addition, in case of
558 instantiated units, systemd is often unaware of the
559 instance name until the instance has been started. Therefore,
560 using glob patterns with <command>start</command>
561 has limited usefulness.</para>
565 <term><command>stop <replaceable>PATTERN</replaceable>...</command></term>
568 <para>Stop (deactivate) one or more units specified on the
573 <term><command>reload <replaceable>PATTERN</replaceable>...</command></term>
576 <para>Asks all units listed on the command line to reload
577 their configuration. Note that this will reload the
578 service-specific configuration, not the unit configuration
579 file of systemd. If you want systemd to reload the
580 configuration file of a unit, use the
581 <command>daemon-reload</command> command. In other words:
582 for the example case of Apache, this will reload Apache's
583 <filename>httpd.conf</filename> in the web server, not the
584 <filename>apache.service</filename> systemd unit
587 <para>This command should not be confused with the
588 <command>daemon-reload</command> or <command>load</command>
594 <term><command>restart <replaceable>PATTERN</replaceable>...</command></term>
597 <para>Restart one or more units specified on the command
598 line. If the units are not running yet, they will be
603 <term><command>try-restart <replaceable>PATTERN</replaceable>...</command></term>
606 <para>Restart one or more units specified on the command
607 line if the units are running. This does nothing if units are not
608 running. Note that, for compatibility with Red Hat init
609 scripts, <command>condrestart</command> is equivalent to this
614 <term><command>reload-or-restart <replaceable>PATTERN</replaceable>...</command></term>
617 <para>Reload one or more units if they support it. If not,
618 restart them instead. If the units are not running yet, they
619 will be started.</para>
623 <term><command>reload-or-try-restart <replaceable>PATTERN</replaceable>...</command></term>
626 <para>Reload one or more units if they support it. If not,
627 restart them instead. This does nothing if the units are not
628 running. Note that, for compatibility with SysV init scripts,
629 <command>force-reload</command> is equivalent to this
634 <term><command>isolate <replaceable>NAME</replaceable></command></term>
637 <para>Start the unit specified on the command line and its
638 dependencies and stop all others.</para>
640 <para>This is similar to changing the runlevel in a
641 traditional init system. The <command>isolate</command>
642 command will immediately stop processes that are not enabled
643 in the new unit, possibly including the graphical
644 environment or terminal you are currently using.</para>
646 <para>Note that this is allowed only on units where
647 <option>AllowIsolate=</option> is enabled. See
648 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
653 <term><command>kill <replaceable>PATTERN</replaceable>...</command></term>
656 <para>Send a signal to one or more processes of the
657 unit. Use <option>--kill-who=</option> to select which
658 process to kill. Use <option>--kill-mode=</option> to select
659 the kill mode and <option>--signal=</option> to select the
660 signal to send.</para>
664 <term><command>is-active <replaceable>PATTERN</replaceable>...</command></term>
667 <para>Check whether any of the specified units are active
668 (i.e. running). Returns an exit code
669 <constant>0</constant> if at least one is active, or
670 non-zero otherwise. Unless <option>--quiet</option> is
671 specified, this will also print the current unit state to
672 standard output.</para>
676 <term><command>is-failed <replaceable>PATTERN</replaceable>...</command></term>
679 <para>Check whether any of the specified units are in a
680 "failed" state. Returns an exit code
681 <constant>0</constant> if at least one has failed,
682 non-zero otherwise. Unless <option>--quiet</option> is
683 specified, this will also print the current unit state to
684 standard output.</para>
688 <term><command>status</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...]</optional></term>
691 <para>Show terse runtime status information about one or
692 more units, followed by most recent log data from the
693 journal. If no units are specified, show all units (subject
694 to limitations specified with <option>-t</option>). If a PID
695 is passed, show information about the unit the process
698 <para>This function is intended to generate human-readable
699 output. If you are looking for computer-parsable output,
700 use <command>show</command> instead. By default this
701 function only shows 10 lines of output and ellipsizes
702 lines to fit in the terminal window. This can be changes
703 with <option>--lines</option> and <option>--full</option>,
704 see above. In addition, <command>journalctl
705 --unit=<replaceable>NAME</replaceable></command> or
707 --user-unit=<replaceable>NAME</replaceable></command> use
708 a similar filter for messages and might be more
714 <term><command>show</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>JOB</replaceable>...</optional></term>
717 <para>Show properties of one or more units, jobs, or the
718 manager itself. If no argument is specified, properties of
719 the manager will be shown. If a unit name is specified,
720 properties of the unit is shown, and if a job id is
721 specified, properties of the job is shown. By default, empty
722 properties are suppressed. Use <option>--all</option> to
723 show those too. To select specific properties to show, use
724 <option>--property=</option>. This command is intended to be
725 used whenever computer-parsable output is required. Use
726 <command>status</command> if you are looking for formatted
727 human-readable output.</para>
731 <term><command>cat <replaceable>PATTERN</replaceable>...</command></term>
734 <para>Show backing files of one or more units. Prints the
735 "fragment" and "drop-ins" (source files) of units. Each
736 file is preceded by a comment which includes the file
741 <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>...</command></term>
744 <para>Set the specified unit properties at runtime where
745 this is supported. This allows changing configuration
746 parameter properties such as resource control settings at
747 runtime. Not all properties may be changed at runtime, but
748 many resource control settings (primarily those in
749 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
750 may. The changes are applied instantly, and stored on disk
751 for future boots, unless <option>--runtime</option> is
752 passed, in which case the settings only apply until the
753 next reboot. The syntax of the property assignment follows
754 closely the syntax of assignments in unit files.</para>
756 <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para>
758 <para>Note that this command allows changing multiple
759 properties at the same time, which is preferable over
760 setting them individually. Like unit file configuration
761 settings, assigning the empty list to list parameters will
762 reset the list.</para>
767 <term><command>help <replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...</command></term>
770 <para>Show manual pages for one or more units, if
771 available. If a PID is given, the manual pages for the unit
772 the process belongs to are shown.</para>
777 <term><command>reset-failed [<replaceable>PATTERN</replaceable>...]</command></term>
780 <para>Reset the <literal>failed</literal> state of the
781 specified units, or if no unit name is passed, reset the state of all
782 units. When a unit fails in some way (i.e. process exiting
783 with non-zero error code, terminating abnormally or timing
784 out), it will automatically enter the
785 <literal>failed</literal> state and its exit code and status
786 is recorded for introspection by the administrator until the
787 service is restarted or reset with this command.</para>
792 <term><command>list-dependencies <replaceable>NAME</replaceable></command></term>
795 <para>Shows required and wanted units of the specified
796 unit. If no unit is specified,
797 <filename>default.target</filename> is implied. Target units
798 are recursively expanded. When <option>--all</option> is
799 passed, all other units are recursively expanded as
807 <title>Unit File Commands</title>
811 <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term>
814 <para>List installed unit files. If one or more
815 <replaceable>PATTERN</replaceable>s are specified, only
816 units whose filename (just the last component of the path)
817 matches one of them are shown.</para>
822 <term><command>enable <replaceable>NAME</replaceable>...</command></term>
825 <para>Enable one or more unit files or unit file instances,
826 as specified on the command line. This will create a number
827 of symlinks as encoded in the <literal>[Install]</literal>
828 sections of the unit files. After the symlinks have been
829 created, the systemd configuration is reloaded (in a way that
830 is equivalent to <command>daemon-reload</command>) to ensure
831 the changes are taken into account immediately. Note that
832 this does <emphasis>not</emphasis> have the effect of also
833 starting any of the units being enabled. If this
834 is desired, a separate <command>start</command> command must
835 be invoked for the unit. Also note that in case of instance
836 enablement, symlinks named the same as instances are created in
837 the install location, however they all point to the same
838 template unit file.</para>
840 <para>This command will print the actions executed. This
841 output may be suppressed by passing <option>--quiet</option>.
844 <para>Note that this operation creates only the suggested
845 symlinks for the units. While this command is the
846 recommended way to manipulate the unit configuration
847 directory, the administrator is free to make additional
848 changes manually by placing or removing symlinks in the
849 directory. This is particularly useful to create
850 configurations that deviate from the suggested default
851 installation. In this case, the administrator must make sure
852 to invoke <command>daemon-reload</command> manually as
853 necessary to ensure the changes are taken into account.
856 <para>Enabling units should not be confused with starting
857 (activating) units, as done by the <command>start</command>
858 command. Enabling and starting units is orthogonal: units
859 may be enabled without being started and started without
860 being enabled. Enabling simply hooks the unit into various
861 suggested places (for example, so that the unit is
862 automatically started on boot or when a particular kind of
863 hardware is plugged in). Starting actually spawns the daemon
864 process (in case of service units), or binds the socket (in
865 case of socket units), and so on.</para>
867 <para>Depending on whether <option>--system</option>,
868 <option>--user</option>, <option>--runtime</option>,
869 or <option>--global</option> is specified, this enables the unit
870 for the system, for the calling user only, for only this boot of
871 the system, or for all future logins of all users, or only this
872 boot. Note that in the last case, no systemd daemon
873 configuration is reloaded.</para>
878 <term><command>disable <replaceable>NAME</replaceable>...</command></term>
881 <para>Disables one or more units. This removes all symlinks
882 to the specified unit files from the unit configuration
883 directory, and hence undoes the changes made by
884 <command>enable</command>. Note however that this removes
885 all symlinks to the unit files (i.e. including manual
886 additions), not just those actually created by
887 <command>enable</command>. This call implicitly reloads the
888 systemd daemon configuration after completing the disabling
889 of the units. Note that this command does not implicitly
890 stop the units that are being disabled. If this is desired,
891 an additional <command>stop</command> command should be
892 executed afterwards.</para>
894 <para>This command will print the actions executed. This
895 output may be suppressed by passing <option>--quiet</option>.
898 <para>This command honors <option>--system</option>,
899 <option>--user</option>, <option>--runtime</option> and
900 <option>--global</option> in a similar way as
901 <command>enable</command>.</para>
906 <term><command>is-enabled <replaceable>NAME</replaceable>...</command></term>
909 <para>Checks whether any of the specified unit files are
910 enabled (as with <command>enable</command>). Returns an
911 exit code of 0 if at least one is enabled, non-zero
912 otherwise. Prints the current enable status (see table).
913 To suppress this output, use <option>--quiet</option>.
918 <command>is-enabled</command> output
924 <entry>Printed string</entry>
925 <entry>Meaning</entry>
926 <entry>Return value</entry>
931 <entry><literal>enabled</literal></entry>
932 <entry morerows='1'>Enabled through a symlink in <filename>.wants</filename> directory (permanently or just in <filename>/run</filename>)</entry>
933 <entry morerows='1'>0</entry>
936 <entry><literal>enabled-runtime</literal></entry>
939 <entry><literal>linked</literal></entry>
940 <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>)</entry>
941 <entry morerows='1'>1</entry>
944 <entry><literal>linked-runtime</literal></entry>
947 <entry><literal>masked</literal></entry>
948 <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>)</entry>
949 <entry morerows='1'>1</entry>
952 <entry><literal>masked-runtime</literal></entry>
955 <entry><literal>static</literal></entry>
956 <entry>Unit is not enabled, but has no provisions for enabling in [Install] section</entry>
960 <entry><literal>disabled</literal></entry>
961 <entry>Unit is not enabled</entry>
972 <term><command>reenable <replaceable>NAME</replaceable>...</command></term>
975 <para>Reenable one or more unit files, as specified on the
976 command line. This is a combination of
977 <command>disable</command> and <command>enable</command> and
978 is useful to reset the symlinks a unit is enabled with to
979 the defaults configured in the <literal>[Install]</literal>
980 section of the unit file.</para>
985 <term><command>preset <replaceable>NAME</replaceable>...</command></term>
988 <para>Reset one or more unit files, as specified on the
989 command line, to the defaults configured in the preset
990 policy files. This has the same effect as
991 <command>disable</command> or <command>enable</command>,
992 depending how the unit is listed in the preset files. For
993 more information on the preset policy format, see
994 <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
995 For more information on the concept of presets, please
997 <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
1003 <term><command>mask <replaceable>NAME</replaceable>...</command></term>
1006 <para>Mask one or more unit files, as specified on the
1007 command line. This will link these units to
1008 <filename>/dev/null</filename>, making it impossible to
1009 start them. This is a stronger version of
1010 <command>disable</command>, since it prohibits all kinds of
1011 activation of the unit, including manual activation. Use
1012 this option with care. This honors the
1013 <option>--runtime</option> option to only mask temporarily
1014 until the next reoobt of the system.</para>
1019 <term><command>unmask <replaceable>NAME</replaceable>...</command></term>
1022 <para>Unmask one or more unit files, as specified on the
1023 command line. This will undo the effect of
1024 <command>mask</command>.</para>
1029 <term><command>link <replaceable>FILENAME</replaceable>...</command></term>
1032 <para>Link a unit file that is not in the unit file search
1033 paths into the unit file search path. This requires an
1034 absolute path to a unit file. The effect of this can be
1035 undone with <command>disable</command>. The effect of this
1036 command is that a unit file is available for
1037 <command>start</command> and other commands although it
1038 is not installed directly in the unit search path.</para>
1043 <term><command>get-default</command></term>
1046 <para>Get the default target specified
1047 via <filename>default.target</filename> link.</para>
1052 <term><command>set-default <replaceable>NAME</replaceable></command></term>
1055 <para>Set the default target to boot into. Command links
1056 <filename>default.target</filename> to the given unit.</para>
1063 <title>Job Commands</title>
1067 <term><command>list-jobs <optional><replaceable>PATTERN...</replaceable></optional></command></term>
1070 <para>List jobs that are in progress. If one or more
1071 <replaceable>PATTERN</replaceable>s are specified, only
1072 jobs for units matching one of them are shown.</para>
1076 <term><command>cancel <replaceable>JOB</replaceable>...</command></term>
1079 <para>Cancel one or more jobs specified on the command line
1080 by their numeric job IDs. If no job ID is specified, cancel
1081 all pending jobs.</para>
1088 <title>Snapshot Commands</title>
1092 <term><command>snapshot <optional><replaceable>NAME</replaceable></optional></command></term>
1095 <para>Create a snapshot. If a snapshot name is specified,
1096 the new snapshot will be named after it. If none is
1097 specified, an automatic snapshot name is generated. In
1098 either case, the snapshot name used is printed to standard
1099 output, unless <option>--quiet</option> is specified.
1102 <para>A snapshot refers to a saved state of the systemd
1103 manager. It is implemented itself as a unit that is
1104 generated dynamically with this command and has dependencies
1105 on all units active at the time. At a later time, the user
1106 may return to this state by using the
1107 <command>isolate</command> command on the snapshot unit.
1110 <para>Snapshots are only useful for saving and restoring
1111 which units are running or are stopped, they do not
1112 save/restore any other state. Snapshots are dynamic and lost
1117 <term><command>delete <replaceable>PATTERN</replaceable>...</command></term>
1120 <para>Remove a snapshot previously created with
1121 <command>snapshot</command>.</para>
1128 <title>Environment Commands</title>
1132 <term><command>show-environment</command></term>
1135 <para>Dump the systemd manager environment block. The
1136 environment block will be dumped in straight-forward form
1137 suitable for sourcing into a shell script. This environment
1138 block will be passed to all processes the manager
1143 <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>...</command></term>
1146 <para>Set one or more systemd manager environment variables,
1147 as specified on the command line.</para>
1151 <term><command>unset-environment <replaceable>VARIABLE</replaceable>...</command></term>
1154 <para>Unset one or more systemd manager environment
1155 variables. If only a variable name is specified, it will be
1156 removed regardless of its value. If a variable and a value
1157 are specified, the variable is only removed if it has the
1158 specified value.</para>
1162 <term><command>import-environment <replaceable>VARIABLE</replaceable>...</command></term>
1165 <para>Import all, one or more environment variables set on
1166 the client into the systemd manager environment block. If
1167 no arguments are passed, the entire environment block is
1168 imported. Otherwise, a list of one or more environment
1169 variable names should be passed, whose client-side values
1170 are then imported into the manager's environment
1178 <title>Manager Lifecycle Commands</title>
1182 <term><command>daemon-reload</command></term>
1185 <para>Reload systemd manager configuration. This will reload
1186 all unit files and recreate the entire dependency
1187 tree. While the daemon is being reloaded, all sockets systemd
1188 listens on on behalf of user configuration will stay
1189 accessible.</para> <para>This command should not be confused
1190 with the <command>load</command> or
1191 <command>reload</command> commands.</para>
1195 <term><command>daemon-reexec</command></term>
1198 <para>Reexecute the systemd manager. This will serialize the
1199 manager state, reexecute the process and deserialize the
1200 state again. This command is of little use except for
1201 debugging and package upgrades. Sometimes, it might be
1202 helpful as a heavy-weight <command>daemon-reload</command>.
1203 While the daemon is being reexecuted, all sockets systemd listening
1204 on behalf of user configuration will stay accessible.
1212 <title>System Commands</title>
1216 <term><command>default</command></term>
1219 <para>Enter default mode. This is mostly equivalent to
1220 <command>isolate default.target</command>.</para>
1224 <term><command>rescue</command></term>
1227 <para>Enter rescue mode. This is mostly equivalent to
1228 <command>isolate rescue.target</command>, but also prints a
1229 wall message to all users.</para>
1233 <term><command>emergency</command></term>
1236 <para>Enter emergency mode. This is mostly equivalent to
1237 <command>isolate emergency.target</command>, but also prints
1238 a wall message to all users.</para>
1242 <term><command>halt</command></term>
1245 <para>Shut down and halt the system. This is mostly equivalent to
1246 <command>start halt.target --irreversible</command>, but also
1247 prints a wall message to all users. If combined with
1248 <option>--force</option>, shutdown of all running services is
1249 skipped, however all processes are killed and all file
1250 systems are unmounted or mounted read-only, immediately
1251 followed by the system halt. If <option>--force</option> is
1252 specified twice, the operation is immediately executed
1253 without terminating any processes or unmounting any file
1254 systems. This may result in data loss.</para>
1258 <term><command>poweroff</command></term>
1261 <para>Shut down and power-off the system. This is mostly
1262 equivalent to <command>start poweroff.target --irreversible</command>,
1263 but also prints a wall message to all users. If combined with
1264 <option>--force</option>, shutdown of all running services is
1265 skipped, however all processes are killed and all file
1266 systems are unmounted or mounted read-only, immediately
1267 followed by the powering off. If <option>--force</option> is
1268 specified twice, the operation is immediately executed
1269 without terminating any processes or unmounting any file
1270 systems. This may result in data loss.</para>
1274 <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
1277 <para>Shut down and reboot the system. This is mostly
1278 equivalent to <command>start reboot.target --irreversible</command>,
1279 but also prints a wall message to all users. If combined with
1280 <option>--force</option>, shutdown of all running services is
1281 skipped, however all processes are killed and all file
1282 systems are unmounted or mounted read-only, immediately
1283 followed by the reboot. If <option>--force</option> is
1284 specified twice, the operation is immediately executed
1285 without terminating any processes or unmounting any file
1286 systems. This may result in data loss.</para>
1288 <para>If the optional argument
1289 <replaceable>arg</replaceable> is given, it will be passed
1290 as the optional argument to the
1291 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1292 system call. The value is architecture and firmware
1293 specific. As an example, <literal>recovery</literal> might
1294 be used to trigger system recovery, and
1295 <literal>fota</literal> might be used to trigger a
1296 <quote>firmware over the air</quote> update.</para>
1300 <term><command>kexec</command></term>
1303 <para>Shut down and reboot the system via kexec. This is
1304 mostly equivalent to <command>start kexec.target --irreversible</command>,
1305 but also prints a wall message to all users. If combined
1306 with <option>--force</option>, shutdown of all running
1307 services is skipped, however all processes are killed and
1308 all file systems are unmounted or mounted read-only,
1309 immediately followed by the reboot.</para>
1313 <term><command>exit</command></term>
1316 <para>Ask the systemd manager to quit. This is only
1317 supported for user service managers (i.e. in conjunction
1318 with the <option>--user</option> option) and will fail
1324 <term><command>suspend</command></term>
1327 <para>Suspend the system. This will trigger activation of
1328 the special <filename>suspend.target</filename> target.
1333 <term><command>hibernate</command></term>
1336 <para>Hibernate the system. This will trigger activation of
1337 the special <filename>hibernate.target</filename> target.
1342 <term><command>hybrid-sleep</command></term>
1345 <para>Hibernate and suspend the system. This will trigger
1346 activation of the special
1347 <filename>hybrid-sleep.target</filename> target.</para>
1351 <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term>
1354 <para>Switches to a different root directory and executes a
1355 new system manager process below it. This is intended for
1356 usage in initial RAM disks ("initrd"), and will transition
1357 from the initrd's system manager process (a.k.a "init"
1358 process) to the main system manager process. This call takes two
1359 arguments: the directory that is to become the new root directory, and
1360 the path to the new system manager binary below it to
1361 execute as PID 1. If the latter is omitted or the empty
1362 string, a systemd binary will automatically be searched for
1363 and used as init. If the system manager path is omitted or
1364 equal to the empty string, the state of the initrd's system
1365 manager process is passed to the main system manager, which
1366 allows later introspection of the state of the services
1367 involved in the initrd boot.</para>
1374 <title>Parameter Syntax</title>
1376 <para>Unit ommands listed above take either a single unit name
1377 (designated as <replaceable>NAME</replaceable>), or multiple
1378 unit specifications (designated as
1379 <replaceable>PATTERN</replaceable>...). In the first case, the
1380 unit name with or without a suffix must be given. If the suffix
1381 is not specified, systemctl will append a suitable suffix,
1382 <literal>.service</literal> by default, and a type-specific
1383 suffix in case of commands which operate only on specific unit
1385 <programlisting># systemctl start sshd</programlisting> and
1386 <programlisting># systemctl start sshd.service</programlisting>
1387 are equivalent, as are
1388 <programlisting># systemctl isolate snapshot-11</programlisting>
1390 <programlisting># systemctl isolate snapshot-11.snapshot</programlisting>
1391 Note that (absolute) paths to device nodes are automatically
1392 converted to device unit names, and other (absolute) paths to
1394 <programlisting># systemctl status /dev/sda
1395 # systemctl status /home</programlisting>
1397 <programlisting># systemctl status dev-sda.device
1398 # systemctl status home.mount</programlisting>
1399 In the second case, shell-style globs will be matched against
1400 currently loaded units; literal unit names, with or without
1401 a suffix, will be treated as in the first case. This means that
1402 literal unit names always refer to exactly one unit, but globs
1403 may match zero units and this is not considered an error.</para>
1405 <para>Glob patterns use
1406 <citerefentry><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
1407 so normal shell-style globbing rules are used, and
1408 <literal>*</literal>, <literal>?</literal>,
1409 <literal>[]</literal> may be used. See
1410 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1411 for more details. The patterns are matched against the names of
1412 currently loaded units, and patterns which do not match anything
1413 are silently skipped. For example:
1414 <programlisting># systemctl stop sshd@*.service</programlisting>
1415 will stop all <filename>sshd@.service</filename> instances.
1418 <para>For unit file commands, the specified
1419 <replaceable>NAME</replaceable> should be the full name of the
1420 unit file, or the absolute path to the unit file:
1421 <programlisting># systemctl enable foo.service</programlisting>
1423 <programlisting># systemctl link /path/to/foo.service</programlisting>
1430 <title>Exit status</title>
1432 <para>On success, 0 is returned, a non-zero failure
1433 code otherwise.</para>
1436 <xi:include href="less-variables.xml" />
1439 <title>See Also</title>
1441 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1442 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1443 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1444 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1445 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1446 <citerefentry><refentrytitle>systemd.resource-management</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1447 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1448 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1449 <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1450 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>