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 General Public License as published by
12 the Free Software Foundation; either version 2 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 General Public License for more details.
20 You should have received a copy of the GNU General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemctl">
27 <title>systemctl</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemctl</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>systemctl</refname>
47 <refpurpose>Control the systemd system and service manager</refpurpose>
52 <command>systemctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
57 <title>Description</title>
59 <para><command>systemctl</command> may be used to
60 introspect and control the state of the
61 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
62 system and service manager.</para>
66 <title>Options</title>
68 <para>The following options are understood:</para>
72 <term><option>--help</option></term>
73 <term><option>-h</option></term>
75 <listitem><para>Prints a short help
76 text and exits.</para></listitem>
80 <term><option>--version</option></term>
82 <listitem><para>Prints a short version
83 string and exits.</para></listitem>
87 <term><option>--type=</option></term>
88 <term><option>-t</option></term>
90 <listitem><para>When listing units,
91 limit display to certain unit
92 types. If not specified units of all
93 types will be shown. The argument
94 should be a unit type name such as
95 <option>service</option>,
96 <option>socket</option> and
97 similar.</para></listitem>
101 <term><option>--property=</option></term>
102 <term><option>-p</option></term>
104 <listitem><para>When showing
105 unit/job/manager information, limit
106 display to certain properties as
107 specified as argument. If not
108 specified all set properties are
109 shown. The argument should be a
110 property name, such as
111 <literal>MainPID</literal>. If
112 specified more than once all
113 properties with the specified names
114 are shown.</para></listitem>
118 <term><option>--all</option></term>
119 <term><option>-a</option></term>
121 <listitem><para>When listing units,
122 show all units, regardless of their
123 state, including inactive units. When
124 showing unit/job/manager information,
125 show all properties regardless whether
126 they are set or not.</para></listitem>
130 <term><option>--full</option></term>
132 <listitem><para>Do not ellipsize unit
133 names and truncate unit descriptions
135 <command>list-units</command> and
136 <command>list-jobs</command>.</para></listitem>
140 <term><option>--fail</option></term>
142 <listitem><para>If the requested
143 operation conflicts with a pending
144 unfinished job, fail the command. If
145 this is not specified the requested
146 operation will replace the pending job,
147 if necessary.</para></listitem>
151 <term><option>--quiet</option></term>
152 <term><option>-q</option></term>
154 <listitem><para>Suppress output to
156 <command>snapshot</command>,
157 <command>is-active</command>,
158 <command>enable</command> and
159 <command>disable</command>.</para></listitem>
163 <term><option>--no-block</option></term>
165 <listitem><para>Do not synchronously wait for
166 the requested operation to finish. If this is
167 not specified the job will be verified,
168 enqueued and <command>systemctl</command> will
169 wait until it is completed. By passing this
170 argument it is only verified and
171 enqueued.</para></listitem> </varlistentry>
174 <term><option>--no-pager</option></term>
176 <listitem><para>Do not pipe output into a
177 pager.</para></listitem>
181 <term><option>--system</option></term>
183 <listitem><para>Talk to the systemd
184 system manager. (Default)</para></listitem>
188 <term><option>--user</option></term>
190 <listitem><para>Talk to the systemd
191 manager of the calling user.</para></listitem>
195 <term><option>--order</option></term>
196 <term><option>--require</option></term>
198 <listitem><para>When used in
200 <command>dot</command> command (see
201 below), selects which dependencies are
202 shown in the dependency graph. If
203 <option>--order</option> is passed
204 only dependencies of type
205 <varname>After=</varname> or
206 <varname>Before=</varname> are
207 shown. If <option>--require</option>
208 is passed only dependencies of type
209 <varname>Requires=</varname>,
210 <varname>RequiresOverridable=</varname>,
211 <varname>Requisite=</varname>,
212 <varname>RequisiteOverridable=</varname>,
213 <varname>Wants=</varname> and
214 <varname>Conflicts=</varname> are
215 shown. If neither is passed, shows
216 dependencies of all these
217 types.</para></listitem>
221 <term><option>--no-wall</option></term>
223 <listitem><para>Don't send wall
225 halt, power-off, reboot.</para></listitem>
229 <term><option>--global</option></term>
231 <listitem><para>When used with
232 <command>enable</command> and
233 <command>disable</command>, operate on the
234 global user configuration
235 directory, thus enabling or disabling
236 a unit file globally for all future
237 logins of all users.</para></listitem>
241 <term><option>--no-reload</option></term>
243 <listitem><para>When used with
244 <command>enable</command> and
245 <command>disable</command>, do not
246 implicitly reload daemon configuration
248 changes.</para></listitem>
252 <term><option>--no-ask-password</option></term>
254 <listitem><para>When used with
255 <command>start</command> and related
256 commands, disables asking for
257 passwords. Background services may
258 require input of a password or
259 passphrase string, for example to
260 unlock system hard disks or
261 cryptographic certificates. Unless
262 this option is specified and the
263 command is invoked from a terminal
264 <command>systemctl</command> will
265 query the user on the terminal for the
266 necessary secrets. Use this option to
267 switch this behavior off. In this
268 case the password must be supplied by
269 some other means (for example
270 graphical password agents) or the
271 service might fail.</para></listitem>
275 <term><option>--kill-mode=</option></term>
277 <listitem><para>When used with
278 <command>kill</command>, choose the
279 mode how to kill the selected
280 processes. Must be one of
281 <option>control-group</option>,
282 <option>process-group</option> or
283 <option>process</option> to select
284 whether to kill the entire control
285 group, the process group or only the
286 selected process itself. If omitted
288 <option>control-group</option> if
289 <option>--kill-who=all</option> is
290 set, or <option>process</option>
291 otherwise. You probably never need to
292 use this switch.</para></listitem>
296 <term><option>--kill-who=</option></term>
298 <listitem><para>When used with
299 <command>kill</command>, choose which
300 processes to kill. Must be one of
301 <option>main</option>,
302 <option>control</option> or
303 <option>all</option> to select whether
304 to kill only the main process of the
305 unit, the control process or all
306 processes of the unit. If omitted
308 <option>all</option>.</para></listitem>
312 <term><option>--signal=</option></term>
313 <term><option>-s</option></term>
315 <listitem><para>When used with
316 <command>kill</command>, choose which
317 signal to send to selected
318 processes. Must be one of the well
319 known signal specifiers such as
320 SIGTERM, SIGINT or SIGSTOP. If
322 <option>SIGTERM</option>.</para></listitem>
326 <term><option>--force</option></term>
327 <term><option>-f</option></term>
329 <listitem><para>When used with
330 <command>enable</command>, override any
332 symlinks.</para></listitem>
334 <listitem><para>When used with
335 <command>halt</command>,
336 <command>poweroff</command>,
337 <command>reboot</command> or
338 <command>kexec</command> execute
339 selected operation without shutting
340 down all units. However, all processes
341 will be killed forcibly and all file
342 systems are unmounted or remounted
343 read-only. This is hence a drastic but
344 relatively safe option to request an
345 immediate reboot.</para></listitem>
349 <term><option>--defaults</option></term>
351 <listitem><para>When used with
352 <command>disable</command>, ensures
353 that only the symlinks created by
354 <command>enable</command> are removed,
355 not all symlinks pointing to the unit
357 disabled.</para></listitem>
361 <para>The following commands are understood:</para>
365 <term><command>list-units</command></term>
367 <listitem><para>List known units.</para></listitem>
370 <term><command>start [NAME...]</command></term>
372 <listitem><para>Start (activate) one
373 or more units specified on the command
374 line.</para></listitem>
377 <term><command>stop [NAME...]</command></term>
379 <listitem><para>Stop (deactivate) one
380 or more units specified on the command
381 line.</para></listitem>
384 <term><command>reload [NAME...]</command></term>
386 <listitem><para>Asks all units listed
387 on the command line to reload their
388 configuration. Note that this will
389 reload the service-specific
390 configuration, not the unit
391 configuration file of systemd. If you
392 want systemd to reload the
393 configuration file of a unit use the
394 <command>daemon-reload</command>
395 command. In other words: for the
396 example case of Apache, this will
398 <filename>httpd.conf</filename> in the
400 <filename>apache.service</filename>
401 systemd unit file. </para>
403 <para>This command should not be
405 <command>daemon-reload</command> or
406 <command>load</command>
407 commands.</para></listitem>
411 <term><command>restart [NAME...]</command></term>
413 <listitem><para>Restart one or more
414 units specified on the command
415 line. If the units are not running yet
417 started.</para></listitem>
420 <term><command>try-restart [NAME...]</command></term>
422 <listitem><para>Restart one or more
423 units specified on the command
424 line. If the units are not running yet
426 fail. Note that for compatibility
427 with Red Hat init scripts
428 <command>condrestart</command> is
429 equivalent to this command.</para></listitem>
432 <term><command>reload-or-restart [NAME...]</command></term>
434 <listitem><para>Reload one or more
435 units if they support it. If not,
436 restart them instead. If the units
437 are not running yet they will be
438 started.</para></listitem>
441 <term><command>reload-or-try-restart [NAME...]</command></term>
443 <listitem><para>Reload one or more
444 units if they support it. If not,
445 restart them instead. If the units
446 are not running yet the operation
447 will fail. Note that for
448 compatibility with SysV init scripts
449 <command>force-reload</command> is
450 equivalent to this command.</para></listitem>
453 <term><command>isolate [NAME]</command></term>
455 <listitem><para>Start the unit
456 specified on the command line and its
457 dependencies and stop all others.</para>
459 <para>This is similar to changing the
460 runlevel in a traditional init system. The
461 <command>isolate</command> command will
462 immediately stop processes that are not
463 enabled in the new unit, possibly including
464 the graphical environment or terminal you
465 are currently using.</para>
467 <para>Note that this works only on units
468 where <option>AllowIsolate=</option> is
470 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
471 for details.</para></listitem>
474 <term><command>kill [NAME...]</command></term>
476 <listitem><para>Send a signal to one
477 or more processes of the unit. Use
478 <option>--kill-who=</option> to select
479 which process to kill. Use
480 <option>--kill-mode=</option> to
481 select the kill mode and
482 <option>--signal=</option> to select
483 the signal to send.</para></listitem>
486 <term><command>is-active [NAME...]</command></term>
488 <listitem><para>Check whether any of
489 the specified units are active
490 (i.e. running). Returns an exit code
491 0 if at least one is active, non-zero
493 <option>--quiet</option> is specified
494 this will also print the current unit
495 state to STDOUT.</para></listitem>
498 <term><command>status [NAME...|PID...]</command></term>
500 <listitem><para>Show terse runtime
501 status information about one or more
502 units. This function is intended to
503 generate human-readable output. If you
504 are looking for computer-parsable
505 output, use <command>show</command>
506 instead. If a PID is passed
507 information about the unit the process
508 of the PID belongs to is
509 shown.</para></listitem>
512 <term><command>show [NAME...|JOB...]</command></term>
514 <listitem><para>Show properties of one
515 or more units, jobs or the manager
516 itself. If no argument is specified
517 properties of the manager will be
518 shown. If a unit name is specified
519 properties of the unit is shown, and
520 if a job id is specified properties of
521 the job is shown. By default, empty
522 properties are suppressed. Use
523 <option>--all</option> to show those
524 too. To select specific properties to
526 <option>--property=</option>. This
527 command is intended to be used
528 whenever computer-parsable output is
530 <command>status</command> if you are
531 looking for formatted human-readable
532 output.</para></listitem>
536 <term><command>reset-failed [NAME...]</command></term>
538 <listitem><para>Reset the
539 '<literal>failed</literal>' state of the
540 specified units, or if no unit name is
541 passed of all units. When a unit fails
542 in some way (i.e. process exiting with
543 non-zero error code, terminating
544 abnormally or timing out) it will
545 automatically enter the
546 '<literal>failed</literal>' state and
547 its exit code and status is recorded
548 for introspection by the administrator
549 until the service is restarted or
551 command.</para></listitem>
555 <term><command>enable [NAME...]</command></term>
557 <listitem><para>Enable one or more
558 unit files, as specified on the
559 command line. This will create a
560 number of symlinks as encoded in the
561 <literal>[Install]</literal> sections
562 of the unit files. After the symlinks
563 have been created the systemd
564 configuration is reloaded (in a way
565 that is equivalent to
566 <command>daemon-reload</command>) to
567 ensure the changes are taken into
568 account immediately. Note that this
569 does not have the effect that any of
570 the units enabled are also started at
571 the same time. If this is desired a
572 separate <command>start</command>
573 command must be invoked for the
576 <para>This command will
577 print the actions executed. This
578 output may be suppressed by passing
579 <option>--quiet</option>.</para>
581 <para>Note that this operation creates
582 only the suggested symlinks for the
583 units. While this command is the
584 recommended way to manipulate the unit
585 configuration directory, the
586 administrator is free to make
587 additional changes manually, by
588 placing or removing symlinks in the
589 directory. This is particularly useful
590 to create configurations that deviate
591 from the suggested default
592 installation. In this case the
593 administrator must make sure to invoke
594 <command>daemon-reload</command>
595 manually as necessary, to ensure his
596 changes are taken into account.</para>
598 <para>Enabling units should not be
599 confused with starting (activating)
600 units, as done by the
601 <command>start</command>
602 command. Enabling and starting units
603 is orthogonal: units may be enabled
604 without being started and started
605 without being enabled. Enabling simply
606 hooks the unit into various suggested
607 places (for example, so that the unit
608 is automatically started on boot or
609 when a particular kind of hardware is
610 plugged in). Starting actually spawns
611 the daemon process (in case of service
612 units), or binds the socket (in case
613 of socket units), and so
616 <para>Depending on whether
617 <option>--system</option>,
618 <option>--user</option> or
619 <option>--global</option> is specified
620 this enables the unit for the system,
621 for the calling user only
622 or for all future logins of all
623 users. Note that in the latter case no
624 systemd daemon configuration is
630 <term><command>disable [NAME...]</command></term>
632 <listitem><para>Disables one or more
633 units. This removes all symlinks to
634 the specified unit files from the unit
635 configuration directory, and hence
636 undoes the changes made by
637 <command>enable</command>. Note
638 however that this by default removes
639 all symlinks to the unit files
640 (i.e. including manual additions), not
641 just those actually created by
642 <command>enable</command>. If only the
643 symlinks that are suggested by default
644 shall be removed, pass
645 <option>--defaults</option>. This
646 implicitly reloads the systemd daemon
647 configuration after completing the
648 disabling of the units. Note that this
649 command does not implicitly stop the
650 units that is being disabled. If this
651 is desired an additional
652 <command>stop</command>command should
653 be executed afterwards.</para>
655 <para>This command will print the
656 actions executed. This output may be
657 suppressed by passing
658 <option>--quiet</option>.</para>
661 <para>This command honors
662 <option>--system</option>,
663 <option>--user</option>,
664 <option>--global</option> in a similar
666 <command>enable</command>.</para>
670 <term><command>is-enabled [NAME...]</command></term>
672 <listitem><para>Checks whether any of
673 the specified unit files is enabled
675 <command>enable</command>). Returns an
676 exit code of 0 if at least one is
678 otherwise.</para></listitem>
682 <term><command>load [NAME...]</command></term>
684 <listitem><para>Load one or more units
685 specified on the command line. This
686 will simply load their configuration
687 from disk, but not start them. To
688 start them you need to use the
689 <command>start</command> command which
690 will implicitly load a unit that has
691 not been loaded yet. Note that systemd
692 garbage collects loaded units that are
693 not active or referenced by an active
694 unit. This means that units loaded
695 this way will usually not stay loaded
696 for long. Also note that this command
697 cannot be used to reload unit
698 configuration. Use the
699 <command>daemon-reload</command>
700 command for that. All in all, this
701 command is of little use except for
703 <para>This command should not be
705 <command>daemon-reload</command> or
706 <command>reload</command>
707 commands.</para></listitem>
710 <term><command>list-jobs</command></term>
712 <listitem><para>List jobs that are in progress.</para></listitem>
715 <term><command>cancel [JOB...]</command></term>
717 <listitem><para>Cancel one or more
718 jobs specified on the command line by
720 IDs. If no job id is specified, cancel all pending jobs.</para></listitem>
723 <term><command>monitor</command></term>
725 <listitem><para>Monitor unit/job
726 changes. This is mostly useful for
727 debugging purposes and prints a line
728 each time systemd loads or unloads a
729 unit configuration file, or a unit
730 property changes.</para></listitem>
733 <term><command>dump</command></term>
735 <listitem><para>Dump server
736 status. This will output a (usually
737 very long) human readable manager
738 status dump. Its format is subject to
739 change without notice and should not
741 applications.</para></listitem>
744 <term><command>dot</command></term>
746 <listitem><para>Generate textual
747 dependency graph description in dot
748 format for further processing with the
750 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
751 tool. Use a command line like
752 <command>systemctl dot | dot -Tsvg >
753 systemd.svg</command> to generate a
754 graphical dependency tree. Unless
755 <option>--order</option> or
756 <option>--require</option> is passed
757 the generated graph will show both
758 ordering and requirement
759 dependencies.</para></listitem>
762 <term><command>snapshot [NAME]</command></term>
764 <listitem><para>Create a snapshot. If
765 a snapshot name is specified, the new
766 snapshot will be named after it. If
767 none is specified an automatic
768 snapshot name is generated. In either
769 case, the snapshot name used is
770 printed to STDOUT, unless
771 <option>--quiet</option> is
774 <para>A snapshot refers to a saved
775 state of the systemd manager. It is
776 implemented itself as a unit that is
777 generated dynamically with this
778 command and has dependencies on all
779 units active at the time. At a later
780 time the user may return to this state
782 <command>isolate</command> command on
783 the snapshot unit.</para></listitem>
785 <para>Snapshots are only useful for
786 saving and restoring which units are
787 running or are stopped, they do not
788 save/restore any other
789 state. Snapshots are dynamic and lost
793 <term><command>delete [NAME...]</command></term>
795 <listitem><para>Remove a snapshot
796 previously created with
797 <command>snapshot</command>.</para></listitem>
800 <term><command>daemon-reload</command></term>
802 <listitem><para>Reload systemd manager
803 configuration. This will reload all
804 unit files and recreate the entire
805 dependency tree. While the daemon is
806 reloaded, all sockets systemd listens
807 on on behalf of user configuration will
808 stay accessible.</para> <para>This
809 command should not be confused with
810 the <command>load</command> or
811 <command>reload</command>
812 commands.</para></listitem>
815 <term><command>daemon-reexec</command></term>
817 <listitem><para>Reexecute the systemd
818 manager. This will serialize the
819 manager state, reexecute the process
820 and deserialize the state again. This
821 command is of little use except for
822 debugging and package
823 upgrades. Sometimes it might be
824 helpful as a heavy-weight
825 <command>daemon-reload</command>. While
826 the daemon is reexecuted all sockets
827 systemd listens on on behalf of user
828 configuration will stay
829 accessible.</para></listitem>
832 <term><command>show-environment</command></term>
834 <listitem><para>Dump the systemd
835 manager environment block. The
836 environment block will be dumped in
837 straight-forward form suitable for
838 sourcing into a shell script. This
839 environment block will be passed to
840 all processes the manager
841 spawns.</para></listitem>
844 <term><command>set-environment [NAME=VALUE...]</command></term>
846 <listitem><para>Set one or more
847 systemd manager environment variables,
848 as specified on the command
849 line.</para></listitem>
852 <term><command>unset-environment [NAME...]</command></term>
854 <listitem><para>Unset one or more
855 systemd manager environment
856 variables. If only a variable name is
857 specified it will be removed
858 regardless of its value. If a variable
859 and a value are specified the variable
860 is only removed if it has the
861 specified value.</para></listitem>
864 <term><command>default</command></term>
866 <listitem><para>Enter default
867 mode. This is mostly equivalent to
869 default.target</command>.</para></listitem>
872 <term><command>rescue</command></term>
874 <listitem><para>Enter rescue
875 mode. This is mostly equivalent to
877 rescue.target</command> but also
878 prints a wall message to all
879 users.</para></listitem>
882 <term><command>emergency</command></term>
884 <listitem><para>Enter emergency
885 mode. This is mostly equivalent to
887 emergency.target</command> but also
888 prints a wall message to all
889 users.</para></listitem>
892 <term><command>halt</command></term>
894 <listitem><para>Shut down and halt the
895 system. This is mostly equivalent to
896 <command>start halt.target</command>
897 but also prints a wall message to all
899 combined with <option>--force</option>
900 shutdown of all running services is
901 skipped, however all processes are killed
902 and all file systems are unmounted or
903 mounted read-only, immediately
905 system halt.</para></listitem>
908 <term><command>poweroff</command></term>
910 <listitem><para>Shut down and
911 power-off the system. This is mostly
912 equivalent to <command>start
913 poweroff.target</command> but also
914 prints a wall message to all
916 combined with <option>--force</option>
917 shutdown of all running services is
918 skipped, however all processes are killed
919 and all file systems are unmounted or
920 mounted read-only, immediately
922 powering off.</para></listitem>
925 <term><command>reboot</command></term>
927 <listitem><para>Shut down and
928 reboot the system. This is mostly
929 equivalent to <command>start
930 reboot.target</command> but also
931 prints a wall message to all
933 combined with <option>--force</option>
934 shutdown of all running services is
935 skipped, however all processes are killed
936 and all file systems are unmounted or
937 mounted read-only, immediately
939 reboot.</para></listitem>
942 <term><command>kexec</command></term>
944 <listitem><para>Shut down and reboot
945 the system via kexec. This is mostly
946 equivalent to <command>start
947 kexec.target</command> but also prints
948 a wall message to all users. If
949 combined with <option>--force</option>
950 shutdown of all running services is
951 skipped, however all processes are killed
952 and all file systems are unmounted or
953 mounted read-only, immediately
955 reboot.</para></listitem>
958 <term><command>exit</command></term>
960 <listitem><para>Ask the systemd
961 manager to quit. This is only
962 supported for user service managers
963 (i.e. in conjunction with the
964 <option>--user</option> option) and
965 will fail otherwise.</para></listitem>
972 <title>Exit status</title>
974 <para>On success 0 is returned, a non-zero failure
975 code otherwise.</para>
979 <title>See Also</title>
981 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
982 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
983 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
984 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
985 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>