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>check</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>--system</option></term>
176 <listitem><para>Talk to the systemd
177 system manager. (Default)</para></listitem>
181 <term><option>--user</option></term>
183 <listitem><para>Talk to the systemd
184 manager of the calling user.</para></listitem>
188 <term><option>--order</option></term>
189 <term><option>--require</option></term>
191 <listitem><para>When used in
193 <command>dot</command> command (see
194 below), selects which dependencies are
195 shown in the dependency graph. If
196 <option>--order</option> is passed
197 only dependencies of type
198 <varname>After=</varname> or
199 <varname>Before=</varname> are
200 shown. If <option>--require</option>
201 is passed only dependencies of type
202 <varname>Requires=</varname>,
203 <varname>RequiresOverridable=</varname>,
204 <varname>Requisite=</varname>,
205 <varname>RequisiteOverridable=</varname>,
206 <varname>Wants=</varname> and
207 <varname>Conflicts=</varname> are
208 shown. If neither is passed, shows
209 dependencies of all these
210 types.</para></listitem>
214 <term><option>--no-wall</option></term>
216 <listitem><para>Don't send wall
218 halt, power-off, reboot.</para></listitem>
222 <term><option>--global</option></term>
224 <listitem><para>When used with
225 <command>enable</command> and
226 <command>disable</command>, operate on the
227 global user configuŕation
228 directory, thus enabling or disabling
229 a unit file globally for all future
230 logins of all users.</para></listitem>
234 <term><option>--no-reload</option></term>
236 <listitem><para>When used with
237 <command>enable</command> and
238 <command>disable</command>, do not
239 implicitly reload daemon configuration
241 changes.</para></listitem>
245 <term><option>--no-ask-password</option></term>
247 <listitem><para>When used with
248 <command>start</command> and related
249 commands, disables asking for
250 passwords. Background services may
251 require input of a password or
252 passphrase string, for example to
253 unlock system hard disks or
254 cryptographic certificates. Unless
255 this option is specified and the
256 command is invoked from a terminal
257 <command>systemctl</command> will
258 query the user on the terminal for the
259 necessary secrets. Use this option to
260 switch this behaviour off. In this
261 case the password must be supplied by
262 some other means (for example
263 graphical password agents) or the
264 service might fail.</para></listitem>
268 <term><option>--kill-mode=</option></term>
270 <listitem><para>When used with
271 <command>kill</command>, choose the
272 mode how to kill the selected
273 processes. Must be one of
274 <option>control-group</option>,
275 <option>process-group</option> or
276 <option>process</option> to select
277 whether to kill the entire control
278 group, the process group or only the
279 selected process itself. If ommitted
281 <option>control-group</option> if
282 <option>--kill-who=all</option> is
283 set, or <option>process</option>
284 otherwise. You probably never need to
285 use this switch.</para></listitem>
289 <term><option>--kill-who=</option></term>
291 <listitem><para>When used with
292 <command>kill</command>, choose which
293 processes to kill. Must be one of
294 <option>main</option>,
295 <option>control</option> or
296 <option>all</option> to select whether
297 to kill only the main process of the
298 unit, the control process or all
299 processes of the unit. If ommitted
301 <option>all</option>.</para></listitem>
305 <term><option>---signal=</option></term>
306 <term><option>-s</option></term>
308 <listitem><para>When used with
309 <command>kill</command>, choose which
310 signal to send to selected
311 processes. Must be one of the well
312 know signal specifiers such as
313 SIGTERM, SIGINT or SIGSTOP. If
315 <option>SIGTERM</option>.</para></listitem>
319 <term><option>--force</option></term>
320 <term><option>-f</option></term>
322 <listitem><para>When used with
323 <command>enable</command>, override any
325 symlinks.</para></listitem>
327 <listitem><para>When used with
328 <command>halt</command>,
329 <command>poweroff</command>,
330 <command>reboot</command> or
331 <command>kexec</command> execute
332 selected operation without shutting
333 down all units. However, all processes
334 will be killed forcibly and all file
335 systems are unmounted or remounted
336 read-only. This is hence a drastic but
337 relatively safe option to request an
338 immediate reboot.</para></listitem>
342 <term><option>--defaults</option></term>
344 <listitem><para>When used with
345 <command>disable</command>, ensures
346 that only the symlinks created by
347 <command>enable</command> are removed,
348 not all symlinks pointing to the unit
350 disabled.</para></listitem>
354 <para>The following commands are understood:</para>
358 <term><command>list-units</command></term>
360 <listitem><para>List known units.</para></listitem>
363 <term><command>start [NAME...]</command></term>
365 <listitem><para>Start (activate) one
366 or more units specified on the command
367 line.</para></listitem>
370 <term><command>stop [NAME...]</command></term>
372 <listitem><para>Stop (deactivate) one
373 or more units specified on the command
374 line.</para></listitem>
377 <term><command>reload [NAME...]</command></term>
379 <listitem><para>Asks all units listed
380 on the command line to reload their
381 configuration. Note that this will
382 reload the service-specific
383 configuration, not the unit
384 configuration file of systemd. If you
385 want systemd to reload the
386 configuration file of a unit use the
387 <command>daemon-reload</command>
388 command. In other words: for the
389 example case of Apache, this will
391 <filename>httpd.conf</filename> in the
393 <filename>apache.service</filename>
394 systemd unit file. </para>
396 <para>This command should not be
398 <command>daemon-reload</command> or
399 <command>load</command>
400 commands.</para></listitem>
404 <term><command>restart [NAME...]</command></term>
406 <listitem><para>Restart one or more
407 units specified on the command
408 line. If the units are not running yet
410 started.</para></listitem>
413 <term><command>try-restart [NAME...]</command></term>
415 <listitem><para>Restart one or more
416 units specified on the command
417 line. If the units are not running yet
419 fail.</para></listitem>
422 <term><command>reload-or-restart [NAME...]</command></term>
423 <term><command>reload-or-try-restart [NAME...]</command></term>
425 <listitem><para>Reload one or more
426 units if they support it. If not,
427 restart them instead. Note that for
428 compatibility with SysV and Red Hat
430 <command>force-reload</command> and
431 <command>condrestart</command> may be
432 used as equivalent commands to
433 <command>reload-or-try-restart</command>.</para></listitem>
436 <term><command>isolate [NAME]</command></term>
438 <listitem><para>Start the unit
439 specified on the command line and its
440 dependencies and stop all others.</para>
442 <para>This is similar to changing the
443 runlevel in a traditional init system. The
444 <command>isolate</command> command will
445 immediately stop processes that are not
446 enabled in the new unit, possibly including
447 the graphical environment or terminal you
448 are currently using.</para>
450 <para>Note that this works only on units
451 where <option>AllowIsolate=</option> is
453 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
454 for details.</para></listitem>
457 <term><command>kill [NAME...]</command></term>
459 <listitem><para>Send a signal to one
460 or more processes of the unit. Use
461 <option>--kill-who=</option> to select
462 which process to kill. Use
463 <option>--kill-mode=</option> to
464 select the kill mode and
465 <option>--signal=</option> to select
466 the signal to send.</para></listitem>
469 <term><command>is-active [NAME...]</command></term>
471 <listitem><para>Check whether any of
472 the specified units is active
473 (i.e. running). Returns an exit code
474 0 if at least one is active, non-zero
476 <option>--quiet</option> is specified
477 this will also print the current unit
478 state to STDOUT.</para></listitem>
481 <term><command>status [NAME...|PID...]</command></term>
483 <listitem><para>Show terse runtime
484 status information about one or more
485 units. This function is intended to
486 generate human-readable output. If you
487 are looking for computer-parsable
488 output, use <command>show</command>
489 instead. If a PID is passed
490 information about the unit the process
491 of the PID belongs to is
492 shown.</para></listitem>
495 <term><command>show [NAME...|JOB...]</command></term>
497 <listitem><para>Show properties of one
498 or more units, jobs or the manager
499 itself. If no argument is specified
500 properties of the manager will be
501 shown. If a unit name is specified
502 properties of the unit is shown, and
503 if a job id is specified properties of
504 the job is shown. By default, empty
505 properties are suppressed. Use
506 <option>--all</option> to show those
507 too. To select specific properties to
509 <option>--property=</option>. This
510 command is intended to be used
511 whenever computer-parsable output is
513 <command>status</command> if you are
514 looking for formatted human-readable
515 output.</para></listitem>
519 <term><command>reset-failed [NAME...]</command></term>
521 <listitem><para>Reset the
522 '<literal>failed</literal>' state of the
523 specified units, or if no unit name is
524 passed of all units. When a unit fails
525 in some way (i.e. process exiting with
526 non-zero error code, terminating
527 abnormally or timing out) it will
528 automatically enter the
529 '<literal>failed</literal>' state and
530 its exit code and status is recorded
531 for introspection by the administrator
532 until the service is restarted or
534 command.</para></listitem>
538 <term><command>enable [NAME...]</command></term>
540 <listitem><para>Enable one or more
541 unit files, as specified on the
542 command line. This will create a
543 number of symlinks as encoded in the
544 <literal>[Install]</literal> sections
545 of the unit files. After the symlinks
546 have been created the systemd
547 configuration is reloaded (in a way
548 that is equivalent to
549 <command>daemon-reload</command>) to
550 ensure the changes are taken into
551 account immediately. Note that this
552 does not have the effect that any of
553 the units enabled are also started at
554 the same time. If this is desired a
555 separate <command>start</command>
556 command must be invoked for the
559 <para>This command will
560 print the actions executed. This
561 output may be suppressed by passing
562 <option>--quiet</option>.</para>
564 <para>Note that this operation creates
565 only the suggested symlinks for the
566 units. While this command is the
567 recommended way to manipulate the unit
568 configuration directory, the
569 administrator is free to make
570 additional changes manually, by
571 placing or removing symlinks in the
572 directory. This is particular useful
573 to create configurations that deviate
574 from the suggested default
575 installation. In this case the
576 administrator must make sure to invoke
577 <command>daemon-reload</command>
578 manually as necessary, to ensure his
579 changes are taken into account.</para>
581 <para>Enabling units should not be
582 confused with starting (activating)
583 units, as done by the
584 <command>start</command>
585 command. Enabling and starting units
586 is orthogonal: units may be enabled
587 without being started and started
588 without being enabled. Enabling simply
589 hooks the unit into various suggested
590 places (for example, so that the unit
591 is automatically started on boot or
592 when a particular kind of hardware is
593 plugged in). Starting actually spawns
594 the daemon process (in case of service
595 units), or binds the socket (in case
596 of socket units), and so
599 <para>Depending on whether
600 <option>--system</option>,
601 <option>--user</option> or
602 <option>--global</option> is specified
603 this enables the unit for the system,
604 for the calling user only
605 or for all future logins of all
606 users. Note that in the latter case no
607 systemd daemon configuration is
613 <term><command>disable [NAME...]</command></term>
615 <listitem><para>Disables one or more
616 units. This removes all symlinks to
617 the specified unit files from the unit
618 configuration directory, and hence
619 undoes the changes made by
620 <command>enable</command>. Note
621 however that this by default removes
622 all symlinks to the unit files
623 (i.e. including manual additions), not
624 just those actually created by
625 <command>enable</command>. If only the
626 symlinks that are suggested by default
627 shall be removed, pass
628 <option>--defaults</option>. This
629 implicitly reloads the systemd daemon
630 configuration after completing the
631 disabling of the units. Note that this
632 command does not implicitly stop the
633 units that is being disabled. If this
634 is desired an additional
635 <command>stop</command>command should
636 be executed afterwards.</para>
638 <para>This command will print the
639 actions executed. This output may be
640 suppressed by passing
641 <option>--quiet</option>.</para>
644 <para>This command honours
645 <option>--system</option>,
646 <option>--user</option>,
647 <option>--global</option> in a similar
649 <command>enable</command>.</para>
653 <term><command>is-enabled [NAME...]</command></term>
655 <listitem><para>Checks whether any of
656 the specified unit files is enabled
658 <command>enable</command>). Returns an
659 exit code of 0 if at least one is
661 otherwise.</para></listitem>
665 <term><command>load [NAME...]</command></term>
667 <listitem><para>Load one or more units
668 specified on the command line. This
669 will simply load their configuration
670 from disk, but not start them. To
671 start them you need to use the
672 <command>start</command> command which
673 will implicitly load a unit that has
674 not been loaded yet. Note that systemd
675 garbage collects loaded units that are
676 not active or referenced by an active
677 unit. This means that units loaded
678 this way will usually not stay loaded
679 for long. Also note that this command
680 cannot be used to reload unit
681 configuration. Use the
682 <command>daemon-reload</command>
683 command for that. All in all, this
684 command is of little use except for
686 <para>This command should not be
688 <command>daemon-reload</command> or
689 <command>reload</command>
690 commands.</para></listitem>
693 <term><command>list-jobs</command></term>
695 <listitem><para>List jobs that are in progress.</para></listitem>
698 <term><command>cancel [JOB...]</command></term>
700 <listitem><para>Cancel one or more
701 jobs specified on the command line by
703 IDs. If not job id is specified cancels all jobs that are pending.</para></listitem>
706 <term><command>monitor</command></term>
708 <listitem><para>Monitor unit/job
709 changes. This is mostly useful for
710 debugging purposes and prints a line
711 each time systemd loads or unloads a
712 unit configuration file, or a unit
713 property changes.</para></listitem>
716 <term><command>dump</command></term>
718 <listitem><para>Dump server
719 status. This will output a (usually
720 very long) human readable manager
721 status dump. Its format is subject to
722 change without notice and should not
724 applications.</para></listitem>
727 <term><command>dot</command></term>
729 <listitem><para>Generate textual
730 dependency graph description in dot
731 format for further processing with the
733 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
734 tool. Use a command line like
735 <command>systemctl dot | dot -Tsvg >
736 systemd.svg</command> to generate a
737 graphical dependency tree. Unless
738 <option>--order</option> or
739 <option>--require</option> is passed
740 the generated graph will show both
741 ordering and requirement
742 dependencies.</para></listitem>
745 <term><command>snapshot [NAME]</command></term>
747 <listitem><para>Create a snapshot. If
748 a snapshot name is specified, the new
749 snapshot will be named after it. If
750 none is specified an automatic
751 snapshot name is generated. In either
752 case, the snapshot name used is
753 printed to STDOUT, unless
754 <option>--quiet</option> is
757 <para>A snapshot refers to a saved
758 state of the systemd manager. It is
759 implemented itself as unit that is
760 generated dynamically with this
761 command and has dependencies on all
762 units active at the time. At a later
763 time the user may return to this state
765 <command>isolate</command> command on
766 the snapshot unit.</para></listitem>
768 <para>Snapshots are only useful for
769 saving and restoring which units are
770 running or are stopped, they do not
771 save/restore any other
772 state. Snapshots are dynamic and lost
776 <term><command>delete [NAME...]</command></term>
778 <listitem><para>Remove a snapshot
779 previously created with
780 <command>snapshot</command>.</para></listitem>
783 <term><command>daemon-reload</command></term>
785 <listitem><para>Reload systemd manager
786 configuration. This will reload all
787 unit files and recreate the entire
788 dependency tree. While the daemon is
789 reloaded, all sockets systemd listens
790 on on behalf of user configuration will
791 stay accessible.</para> <para>This
792 command should not be confused with
793 the <command>load</command> or
794 <command>reload</command>
795 commands.</para></listitem>
798 <term><command>daemon-reexec</command></term>
800 <listitem><para>Reexecute the systemd
801 manager. This will serialize the
802 manager state, reexecute the process
803 and deserialize the state again. This
804 command is of little use except for
805 debugging and package
806 upgrades. Sometimes it might be
807 helpful as a heavy-weight
808 <command>daemon-reload</command>. While
809 the daemon is reexecuted all sockets
810 systemd listens on on behalf of user
811 configuration will stay
812 accessible.</para></listitem>
815 <term><command>show-environment</command></term>
817 <listitem><para>Dump the systemd
818 manager environment block. The
819 environment block will be dumped in
820 straight-forward form suitable for
821 sourcing into a shell script. This
822 environment block will be passed to
823 all processes the manager
824 spawns.</para></listitem>
827 <term><command>set-environment [NAME=VALUE...]</command></term>
829 <listitem><para>Set one or more
830 systemd manager environment variables,
831 as specified on the command
832 line.</para></listitem>
835 <term><command>unset-environment [NAME...]</command></term>
837 <listitem><para>Unset one or more
838 systemd manager environment
839 variables. If only a variable name is
840 specified it will be removed
841 regardless of its value. If a variable
842 and a value are specified the variable
843 is only removed if it has the
844 specified value.</para></listitem>
847 <term><command>default</command></term>
849 <listitem><para>Enter default
850 mode. This is mostly equivalent to
852 default.target</command>.</para></listitem>
855 <term><command>rescue</command></term>
857 <listitem><para>Enter rescue
858 mode. This is mostly equivalent to
860 rescue.target</command> but also
861 prints a wall message to all
862 users.</para></listitem>
865 <term><command>emergency</command></term>
867 <listitem><para>Enter emergency
868 mode. This is mostly equivalent to
870 emergency.target</command> but also
871 prints a wall message to all
872 users.</para></listitem>
875 <term><command>halt</command></term>
877 <listitem><para>Shut down and halt the
878 system. This is mostly equivalent to
879 <command>start halt.target</command>
880 but also prints a wall message to all
882 combined with <option>--force</option>
883 shutdown of all running services is
884 skipped, however all processes killed
885 and all file systems unmounted or
886 mounted read-only, immediately
888 system halt.</para></listitem>
891 <term><command>poweroff</command></term>
893 <listitem><para>Shut down and
894 power-off the system. This is mostly
895 equivalent to <command>start
896 poweroff.target</command> but also
897 prints a wall message to all
899 combined with <option>--force</option>
900 shutdown of all running services is
901 skipped, however all processes killed
902 and all file systems unmounted or
903 mounted read-only, immediately
905 powering off.</para></listitem>
908 <term><command>reboot</command></term>
910 <listitem><para>Shut down and
911 reboot the system. This is mostly
912 equivalent to <command>start
913 reboot.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 killed
919 and all file systems unmounted or
920 mounted read-only, immediately
922 reboot.</para></listitem>
925 <term><command>kexec</command></term>
927 <listitem><para>Shut down and reboot
928 the system via kexec. This is mostly
929 equivalent to <command>start
930 kexec.target</command> but also prints
931 a wall message to all users. If
932 combined with <option>--force</option>
933 shutdown of all running services is
934 skipped, however all processes killed
935 and all file systems unmounted or
936 mounted read-only, immediately
938 reboot.</para></listitem>
941 <term><command>exit</command></term>
943 <listitem><para>Ask the systemd
944 manager to quit. This is only
945 supported for user service managers
946 (i.e. in conjunction with the
947 <option>--user</option> option) and
948 will fail otherwise.</para></listitem>
955 <title>Exit status</title>
957 <para>On success 0 is returned, a non-zero failure
958 code otherwise.</para>
962 <title>See Also</title>
964 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
965 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
966 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
967 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
968 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>