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 session 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 session 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>--session</option></term>
183 <listitem><para>Talk to the systemd
184 session 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 session configuŕation
228 directory, thus enabling or disabling
229 a unit file globally for all future
230 sessions 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>--kill-mode=</option></term>
247 <listitem><para>When used with
248 <command>kill</command>, choose the
249 mode how to kill the selected
250 processes. Must be one of
251 <option>control-group</option>,
252 <option>process-group</option> or
253 <option>process</option> to select
254 whether to kill the entire control
255 group, the process group or only the
256 selected process itself. If ommitted
258 <option>control-group</option> if
259 <option>--kill-who=all</option> is
260 set, or <option>process</option>
261 otherwise. You probably never need to
262 use this switch.</para></listitem>
266 <term><option>--kill-who=</option></term>
268 <listitem><para>When used with
269 <command>kill</command>, choose which
270 processes to kill. Must be one of
271 <option>main</option>,
272 <option>control</option> or
273 <option>all</option> to select whether
274 to kill only the main process of the
275 unit, the control process or all
276 processes of the unit. If ommitted
278 <option>all</option>.</para></listitem>
282 <term><option>---signal=</option></term>
283 <term><option>-s</option></term>
285 <listitem><para>When used with
286 <command>kill</command>, choose which
287 signal to send to selected
288 processes. Must be one of the well
289 know signal specifiers such as
290 SIGTERM, SIGINT or SIGSTOP. If
292 <option>SIGTERM</option>.</para></listitem>
296 <term><option>--force</option></term>
297 <term><option>-f</option></term>
299 <listitem><para>When used with
300 <command>enable</command>, override any
302 symlinks.</para></listitem>
304 <listitem><para>When used with
305 <command>halt</command>,
306 <command>poweroff</command>,
307 <command>reboot</command> or
308 <command>kexec</command> execute
309 selected operation without shutting
310 down all units. However, all processes
311 will be killed forcibly and all file
312 systems are unmounted or remounted
313 read-only. This is hence a drastic but
314 relatively safe option to request an
315 immediate reboot.</para></listitem>
319 <term><option>--defaults</option></term>
321 <listitem><para>When used with
322 <command>disable</command>, ensures
323 that only the symlinks created by
324 <command>enable</command> are removed,
325 not all symlinks pointing to the unit
327 disabled.</para></listitem>
331 <para>The following commands are understood:</para>
335 <term><command>list-units</command></term>
337 <listitem><para>List known units.</para></listitem>
340 <term><command>start [NAME...]</command></term>
342 <listitem><para>Start (activate) one
343 or more units specified on the command
344 line.</para></listitem>
347 <term><command>stop [NAME...]</command></term>
349 <listitem><para>Stop (deactivate) one
350 or more units specified on the command
351 line.</para></listitem>
354 <term><command>reload [NAME...]</command></term>
356 <listitem><para>Asks all units listed
357 on the command line to reload their
358 configuration. Note that this will
359 reload the service-specific
360 configuration, not the unit
361 configuration file of systemd. If you
362 want systemd to reload the
363 configuration file of a unit use the
364 <command>daemon-reload</command>
365 command. In other words: for the
366 example case of Apache, this will
368 <filename>httpd.conf</filename> in the
370 <filename>apache.service</filename>
371 systemd unit file. </para>
373 <para>This command should not be
375 <command>daemon-reload</command> or
376 <command>load</command>
377 commands.</para></listitem>
381 <term><command>restart [NAME...]</command></term>
383 <listitem><para>Restart one or more
384 units specified on the command
385 line. If the units are not running yet
387 started.</para></listitem>
390 <term><command>try-restart [NAME...]</command></term>
392 <listitem><para>Restart one or more
393 units specified on the command
394 line. If the units are not running yet
396 fail.</para></listitem>
399 <term><command>reload-or-restart [NAME...]</command></term>
400 <term><command>reload-or-try-restart [NAME...]</command></term>
402 <listitem><para>Reload one or more
403 units if they support it. If not,
404 restart them instead. Note that for
405 compatibility with SysV and Red Hat
407 <command>force-reload</command> and
408 <command>condrestart</command> may be
409 used as equivalent commands to
410 <command>reload-or-try-restart</command>.</para></listitem>
413 <term><command>isolate [NAME]</command></term>
415 <listitem><para>Start the unit
416 specified on the command line and its
417 dependencies and stop all others.</para>
419 <para>This is similar to changing the
420 runlevel in a traditional init system. The
421 <command>isolate</command> command will
422 immediately stop processes that are not
423 enabled in the new unit, possibly including
424 the graphical environment or terminal you
425 are currently using.</para>
427 <para>Note that this works only on units
428 where <option>AllowIsolate=</option> is
430 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
431 for details.</para></listitem>
434 <term><command>kill [NAME...]</command></term>
436 <listitem><para>Send a signal to one
437 or more processes of the unit. Use
438 <option>--kill-who=</option> to select
439 which process to kill. Use
440 <option>--kill-mode=</option> to
441 select the kill mode and
442 <option>--signal=</option> to select
443 the signal to send.</para></listitem>
446 <term><command>is-active [NAME...]</command></term>
448 <listitem><para>Check whether any of
449 the specified units is active
450 (i.e. running). Returns an exit code
451 0 if at least one is active, non-zero
453 <option>--quiet</option> is specified
454 this will also print the current unit
455 state to STDOUT.</para></listitem>
458 <term><command>status [NAME...|PID...]</command></term>
460 <listitem><para>Show terse runtime
461 status information about one or more
462 units. This function is intended to
463 generate human-readable output. If you
464 are looking for computer-parsable
465 output, use <command>show</command>
466 instead. If a PID is passed
467 information about the unit the process
468 of the PID belongs to is
469 shown.</para></listitem>
472 <term><command>show [NAME...|JOB...]</command></term>
474 <listitem><para>Show properties of one
475 or more units, jobs or the manager
476 itself. If no argument is specified
477 properties of the manager will be
478 shown. If a unit name is specified
479 properties of the unit is shown, and
480 if a job id is specified properties of
481 the job is shown. By default, empty
482 properties are suppressed. Use
483 <option>--all</option> to show those
484 too. To select specific properties to
486 <option>--property=</option>. This
487 command is intended to be used
488 whenever computer-parsable output is
490 <command>status</command> if you are
491 looking for formatted human-readable
492 output.</para></listitem>
496 <term><command>reset-failed [NAME...]</command></term>
498 <listitem><para>Reset the
499 '<literal>failed</literal>' state of the
500 specified units, or if no unit name is
501 passed of all units. When a unit fails
502 in some way (i.e. process exiting with
503 non-zero error code, terminating
504 abnormally or timing out) it will
505 automatically enter the
506 '<literal>failed</literal>' state and
507 its exit code and status is recorded
508 for introspection by the administrator
509 until the service is restarted or
511 command.</para></listitem>
515 <term><command>enable [NAME...]</command></term>
517 <listitem><para>Enable one or more
518 unit files, as specified on the
519 command line. This will create a
520 number of symlinks as encoded in the
521 <literal>[Install]</literal> sections
522 of the unit files. After the symlinks
523 have been created the systemd
524 configuration is reloaded (in a way
525 that is equivalent to
526 <command>daemon-reload</command>) to
527 ensure the changes are taken into
528 account immediately. Note that this
529 does not have the effect that any of
530 the units enabled are also started at
531 the same time. If this is desired a
532 separate <command>start</command>
533 command must be invoked for the
536 <para>This command will
537 print the actions executed. This
538 output may be suppressed by passing
539 <option>--quiet</option>.</para>
541 <para>Note that this operation creates
542 only the suggested symlinks for the
543 units. While this command is the
544 recommended way to manipulate the unit
545 configuration directory, the
546 administrator is free to make
547 additional changes manually, by
548 placing or removing symlinks in the
549 directory. This is particular useful
550 to create configurations that deviate
551 from the suggested default
552 installation. In this case the
553 administrator must make sure to invoke
554 <command>daemon-reload</command>
555 manually as necessary, to ensure his
556 changes are taken into account.</para>
558 <para>Enabling units should not be
559 confused with starting (activating)
560 units, as done by the
561 <command>start</command>
562 command. Enabling and starting units
563 is orthogonal: units may be enabled
564 without being started and started
565 without being enabled. Enabling simply
566 hooks the unit into various suggested
567 places (for example, so that the unit
568 is automatically started on boot or
569 when a particular kind of hardware is
570 plugged in). Starting actually spawns
571 the daemon process (in case of service
572 units), or binds the socket (in case
573 of socket units), and so
576 <para>Depending on whether
577 <option>--system</option>,
578 <option>--session</option> or
579 <option>--global</option> is specified
580 this enables the unit for the system,
581 for sessions of the calling user only
582 or for all future session of all
583 users. Note that in the latter case no
584 systemd daemon configuration is
590 <term><command>disable [NAME...]</command></term>
592 <listitem><para>Disables one or more
593 units. This removes all symlinks to
594 the specified unit files from the unit
595 configuration directory, and hence
596 undoes the changes made by
597 <command>enable</command>. Note
598 however that this by default removes
599 all symlinks to the unit files
600 (i.e. including manual additions), not
601 just those actually created by
602 <command>enable</command>. If only the
603 symlinks that are suggested by default
604 shall be removed, pass
605 <option>--defaults</option>. This
606 implicitly reloads the systemd daemon
607 configuration after completing the
608 disabling of the units. Note that this
609 command does not implicitly stop the
610 units that is being disabled. If this
611 is desired an additional
612 <command>stop</command>command should
613 be executed afterwards.</para>
615 <para>This command will print the
616 actions executed. This output may be
617 suppressed by passing
618 <option>--quiet</option>.</para>
621 <para>This command honours
622 <option>--system</option>,
623 <option>--session</option>,
624 <option>--global</option> in a similar
626 <command>enable</command>.</para>
630 <term><command>is-enabled [NAME...]</command></term>
632 <listitem><para>Checks whether any of
633 the specified unit files is enabled
635 <command>enable</command>). Returns an
636 exit code of 0 if at least one is
638 otherwise.</para></listitem>
642 <term><command>load [NAME...]</command></term>
644 <listitem><para>Load one or more units
645 specified on the command line. This
646 will simply load their configuration
647 from disk, but not start them. To
648 start them you need to use the
649 <command>start</command> command which
650 will implicitly load a unit that has
651 not been loaded yet. Note that systemd
652 garbage collects loaded units that are
653 not active or referenced by an active
654 unit. This means that units loaded
655 this way will usually not stay loaded
656 for long. Also note that this command
657 cannot be used to reload unit
658 configuration. Use the
659 <command>daemon-reload</command>
660 command for that. All in all, this
661 command is of little use except for
663 <para>This command should not be
665 <command>daemon-reload</command> or
666 <command>reload</command>
667 commands.</para></listitem>
670 <term><command>list-jobs</command></term>
672 <listitem><para>List jobs that are in progress.</para></listitem>
675 <term><command>cancel [JOB...]</command></term>
677 <listitem><para>Cancel one or more
678 jobs specified on the command line by
680 IDs. If not job id is specified cancels all jobs that are pending.</para></listitem>
683 <term><command>monitor</command></term>
685 <listitem><para>Monitor unit/job
686 changes. This is mostly useful for
687 debugging purposes and prints a line
688 each time systemd loads or unloads a
689 unit configuration file, or a unit
690 property changes.</para></listitem>
693 <term><command>dump</command></term>
695 <listitem><para>Dump server
696 status. This will output a (usually
697 very long) human readable manager
698 status dump. Its format is subject to
699 change without notice and should not
701 applications.</para></listitem>
704 <term><command>dot</command></term>
706 <listitem><para>Generate textual
707 dependency graph description in dot
708 format for further processing with the
710 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
711 tool. Use a command line like
712 <command>systemctl dot | dot -Tsvg >
713 systemd.svg</command> to generate a
714 graphical dependency tree. Unless
715 <option>--order</option> or
716 <option>--require</option> is passed
717 the generated graph will show both
718 ordering and requirement
719 dependencies.</para></listitem>
722 <term><command>snapshot [NAME]</command></term>
724 <listitem><para>Create a snapshot. If
725 a snapshot name is specified, the new
726 snapshot will be named after it. If
727 none is specified an automatic
728 snapshot name is generated. In either
729 case, the snapshot name used is
730 printed to STDOUT, unless
731 <option>--quiet</option> is
734 <para>A snapshot refers to a saved
735 state of the systemd manager. It is
736 implemented itself as unit that is
737 generated dynamically with this
738 command and has dependencies on all
739 units active at the time. At a later
740 time the user may return to this state
742 <command>isolate</command> command on
743 the snapshot unit.</para></listitem>
745 <para>Snapshots are only useful for
746 saving and restoring which units are
747 running or are stopped, they do not
748 save/restore any other
749 state. Snapshots are dynamic and lost
753 <term><command>delete [NAME...]</command></term>
755 <listitem><para>Remove a snapshot
756 previously created with
757 <command>snapshot</command>.</para></listitem>
760 <term><command>daemon-reload</command></term>
762 <listitem><para>Reload systemd manager
763 configuration. This will reload all
764 unit files and recreate the entire
765 dependency tree. While the daemon is
766 reloaded, all sockets systemd listens
767 on on behalf of user configuration will
768 stay accessible.</para> <para>This
769 command should not be confused with
770 the <command>load</command> or
771 <command>reload</command>
772 commands.</para></listitem>
775 <term><command>daemon-reexec</command></term>
777 <listitem><para>Reexecute the systemd
778 manager. This will serialize the
779 manager state, reexecute the process
780 and deserialize the state again. This
781 command is of little use except for
782 debugging and package
783 upgrades. Sometimes it might be
784 helpful as a heavy-weight
785 <command>daemon-reload</command>. While
786 the daemon is reexecuted all sockets
787 systemd listens on on behalf of user
788 configuration will stay
789 accessible.</para></listitem>
792 <term><command>show-environment</command></term>
794 <listitem><para>Dump the systemd
795 manager environment block. The
796 environment block will be dumped in
797 straight-forward form suitable for
798 sourcing into a shell script. This
799 environment block will be passed to
800 all processes the manager
801 spawns.</para></listitem>
804 <term><command>set-environment [NAME=VALUE...]</command></term>
806 <listitem><para>Set one or more
807 systemd manager environment variables,
808 as specified on the command
809 line.</para></listitem>
812 <term><command>unset-environment [NAME...]</command></term>
814 <listitem><para>Unset one or more
815 systemd manager environment
816 variables. If only a variable name is
817 specified it will be removed
818 regardless of its value. If a variable
819 and a value are specified the variable
820 is only removed if it has the
821 specified value.</para></listitem>
824 <term><command>default</command></term>
826 <listitem><para>Enter default
827 mode. This is mostly equivalent to
829 default.target</command>.</para></listitem>
832 <term><command>rescue</command></term>
834 <listitem><para>Enter rescue
835 mode. This is mostly equivalent to
837 rescue.target</command> but also
838 prints a wall message to all
839 users.</para></listitem>
842 <term><command>emergency</command></term>
844 <listitem><para>Enter emergency
845 mode. This is mostly equivalent to
847 emergency.target</command> but also
848 prints a wall message to all
849 users.</para></listitem>
852 <term><command>halt</command></term>
854 <listitem><para>Shut down and halt the
855 system. This is mostly equivalent to
856 <command>start halt.target</command>
857 but also prints a wall message to all
859 combined with <option>--force</option>
860 shutdown of all running services is
861 skipped, however all processes killed
862 and all file systems unmounted or
863 mounted read-only, immediately
865 system halt.</para></listitem>
868 <term><command>poweroff</command></term>
870 <listitem><para>Shut down and
871 power-off the system. This is mostly
872 equivalent to <command>start
873 poweroff.target</command> but also
874 prints a wall message to all
876 combined with <option>--force</option>
877 shutdown of all running services is
878 skipped, however all processes killed
879 and all file systems unmounted or
880 mounted read-only, immediately
882 powering off.</para></listitem>
885 <term><command>reboot</command></term>
887 <listitem><para>Shut down and
888 reboot the system. This is mostly
889 equivalent to <command>start
890 reboot.target</command> but also
891 prints a wall message to all
893 combined with <option>--force</option>
894 shutdown of all running services is
895 skipped, however all processes killed
896 and all file systems unmounted or
897 mounted read-only, immediately
899 reboot.</para></listitem>
902 <term><command>kexec</command></term>
904 <listitem><para>Shut down and reboot
905 the system via kexec. This is mostly
906 equivalent to <command>start
907 kexec.target</command> but also prints
908 a wall message to all users. If
909 combined with <option>--force</option>
910 shutdown of all running services is
911 skipped, however all processes killed
912 and all file systems unmounted or
913 mounted read-only, immediately
915 reboot.</para></listitem>
918 <term><command>exit</command></term>
920 <listitem><para>Ask the systemd
921 manager to quit. This is only
922 supported for session managers
923 (i.e. in conjunction with the
924 <option>--session</option> option) and
925 will fail otherwise.</para></listitem>
932 <title>Exit status</title>
934 <para>On success 0 is returned, a non-zero failure
935 code otherwise.</para>
939 <title>See Also</title>
941 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
942 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
943 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
944 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
945 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>