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>--type=</option></term>
81 <term><option>-t</option></term>
83 <listitem><para>When listing units,
84 limit display to certain unit
85 types. If not specified units of all
86 types will be shown. The argument
87 should be a unit type name such as
88 <option>service</option>,
89 <option>socket</option> and
90 similar.</para></listitem>
94 <term><option>--property=</option></term>
95 <term><option>-p</option></term>
97 <listitem><para>When showing
98 unit/job/manager information, limit
99 display to certain properties as
100 specified as argument. If not
101 specified all set properties are
102 shown. The argument should be a
103 property name, such as
104 <literal>MainPID</literal>. If
105 specified more than once all
106 properties with the specified names
107 are shown.</para></listitem>
111 <term><option>--all</option></term>
112 <term><option>-a</option></term>
114 <listitem><para>When listing units,
115 show all units, regardless of their
116 state, including inactive units. When
117 showing unit/job/manager information,
118 show all properties regardless whether
119 they are set or not.</para></listitem>
123 <term><option>--full</option></term>
125 <listitem><para>Do not ellipsize unit
126 names in the output of
127 <command>list-units</command> and
128 <command>list-jobs</command>.</para></listitem>
132 <term><option>--fail</option></term>
134 <listitem><para>If the requested
135 operation conflicts with a pending
136 unfinished job, fail the command. If
137 this is not specified the requested
138 operation will replace the pending job,
139 if necessary.</para></listitem>
143 <term><option>--quiet</option></term>
144 <term><option>-q</option></term>
146 <listitem><para>Suppress output to
148 <command>snapshot</command>,
149 <command>check</command>,
150 <command>enable</command> and
151 <command>disable</command>.</para></listitem>
155 <term><option>--no-block</option></term>
157 <listitem><para>Do not synchronously wait for
158 the requested operation to finish. If this is
159 not specified the job will be verified,
160 enqueued and <command>systemctl</command> will
161 wait until it is completed. By passing this
162 argument it is only verified and
163 enqueued.</para></listitem> </varlistentry>
166 <term><option>--system</option></term>
168 <listitem><para>Talk to the systemd
169 system manager. (Default)</para></listitem>
173 <term><option>--session</option></term>
175 <listitem><para>Talk to the systemd
176 session manager of the calling user.</para></listitem>
180 <term><option>--order</option></term>
181 <term><option>--require</option></term>
183 <listitem><para>When used in
185 <command>dot</command> command (see
186 below), selects which dependencies are
187 shown in the dependency graph. If
188 <option>--order</option> is passed
189 only dependencies of type
190 <varname>After=</varname> or
191 <varname>Before=</varname> are
192 shown. If <option>--require</option>
193 is passed only dependencies of type
194 <varname>Requires=</varname>,
195 <varname>RequiresOverridable=</varname>,
196 <varname>Requisite=</varname>,
197 <varname>RequisiteOverridable=</varname>,
198 <varname>Wants=</varname> and
199 <varname>Conflicts=</varname> are
200 shown. If neither is passed, shows
201 dependencies of all these
202 types.</para></listitem>
206 <term><option>--no-wall</option></term>
208 <listitem><para>Don't send wall
210 halt, power-off, reboot.</para></listitem>
214 <term><option>--global</option></term>
216 <listitem><para>When used with
217 <command>enable</command> and
218 <command>disable</command>, operate on the
219 global session configuŕation
220 directory, thus enabling or disabling
221 a unit file globally for all future
222 sessions of all users.</para></listitem>
226 <term><option>--no-reload</option></term>
228 <listitem><para>When used with
229 <command>enable</command> and
230 <command>disable</command>, do not
231 implicitly reload daemon configuration
233 changes.</para></listitem>
237 <term><option>--force</option></term>
239 <listitem><para>When used with
240 <command>enable</command>, override any
242 symlinks.</para></listitem>
246 <term><option>--defaults</option></term>
248 <listitem><para>When used with
249 <command>disable</command>, ensures
250 that only the symlinks created by
251 <command>enable</command> are removed,
252 not all symlinks pointing to the unit
254 disabled.</para></listitem>
258 <para>The following commands are understood:</para>
262 <term><command>list-units</command></term>
264 <listitem><para>List known units.</para></listitem>
267 <term><command>start [NAME...]</command></term>
269 <listitem><para>Start (activate) one
270 or more units specified on the command
271 line.</para></listitem>
274 <term><command>stop [NAME...]</command></term>
276 <listitem><para>Stop (deactivate) one
277 or more units specified on the command
278 line.</para></listitem>
281 <term><command>reload [NAME...]</command></term>
283 <listitem><para>Asks all units listed
284 on the command line to reload their
285 configuration. Note that this will
286 reload the service-specific
287 configuration, not the unit
288 configuration file of systemd. If you
289 want systemd to reload the
290 configuration file of a unit use the
291 <command>daemon-reload</command>
292 command. In other words: for the
293 example case of Apache, this will
295 <filename>httpd.conf</filename> in the
297 <filename>apache.service</filename>
298 systemd unit file. </para>
300 <para>This command should not be
302 <command>daemon-reload</command> or
303 <command>load</command>
304 commands.</para></listitem>
308 <term><command>restart [NAME...]</command></term>
310 <listitem><para>Restart one or more
311 units specified on the command
312 line. If the units are not running yet
314 started.</para></listitem>
317 <term><command>try-restart [NAME...]</command></term>
319 <listitem><para>Restart one or more
320 units specified on the command
321 line. If the units are not running yet
323 fail.</para></listitem>
326 <term><command>reload-or-restart [NAME...]</command></term>
327 <term><command>reload-or-try-restart [NAME...]</command></term>
329 <listitem><para>Reload one or more
330 units if they support it. If not,
331 restart them instead. Note that for
332 compatibility with SysV and Red Hat
334 <command>force-reload</command> and
335 <command>condrestart</command> may be
336 used as equivalent commands to
337 <command>reload-or-try-restart</command>.</para></listitem>
340 <term><command>isolate [NAME]</command></term>
342 <listitem><para>Start the unit
343 specified on the command line and its
344 dependencies and stop all others. Note
345 that this works only on units where
346 <option>AllowIsolate=</option> is
348 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
349 for details.</para></listitem>
352 <term><command>is-active [NAME...]</command></term>
354 <listitem><para>Check whether any of
355 the specified units is active
356 (i.e. running). Returns an exit code
357 0 if at least one is active, non-zero
359 <option>--quiet</option> is specified
360 this will also print the current unit
361 state to STDOUT.</para></listitem>
364 <term><command>status [NAME...|PID...]</command></term>
366 <listitem><para>Show terse runtime
367 status information about one or more
368 units. This function is intended to
369 generate human-readable output. If you
370 are looking for computer-parsable
371 output, use <command>show</command>
372 instead. If a PID is passed
373 information about the unit the process
374 of the PID belongs to is
375 shown.</para></listitem>
378 <term><command>show [NAME...|JOB...]</command></term>
380 <listitem><para>Show properties of one
381 or more units, jobs or the manager
382 itself. If no argument is specified
383 properties of the manager will be
384 shown. If a unit name is specified
385 properties of the unit is shown, and
386 if a job id is specified properties of
387 the job is shown. By default, empty
388 properties are suppressed. Use
389 <option>--all</option> to show those
390 too. To select specific properties to
392 <option>--property=</option>. This
393 command is intended to be used
394 whenever computer-parsable output is
396 <command>status</command> if you are
397 looking for formatted human-readable
398 output.</para></listitem>
402 <term><command>reset-failed [NAME...]</command></term>
404 <listitem><para>Reset the
405 '<literal>failed</literal>' state of the
406 specified units, or if no unit name is
407 passed of all units. When a unit fails
408 in some way (i.e. process exiting with
409 non-zero error code, terminating
410 abnormally or timing out) it will
411 automatically enter the
412 '<literal>failed</literal>' state and
413 its exit code and status is recorded
414 for introspection by the administrator
415 until the service is restarted or
417 command.</para></listitem>
421 <term><command>enable [NAME...]</command></term>
423 <listitem><para>Enable one or more
424 unit files, as specified on the
425 command line. This will create a
426 number of symlinks as encoded in the
427 <literal>[Install]</literal> sections
428 of the unit files. After the symlinks
429 have been created the systemd
430 configuration is reloaded (in a way
431 that is equivalent to
432 <command>daemon-reload</command>) to
433 ensure the changes are taken into
434 account immediately. Note that this
435 does not have the effect that any of
436 the units enabled are also started at
437 the same time. If this is desired a
438 seperate <command>start</command>
439 command must be invoked for the
442 <para>This command will
443 print the actions executed. This
444 output may be suppressed by passing
445 <option>--quiet</option>.</para>
447 <para>Note that this operation creates
448 only the suggested symlinks for the
449 units. While this command is the
450 recommended way to manipulate the unit
451 configuration directory, the
452 administrator is free to make
453 additional changes manually, by
454 placing or removing symlinks in the
455 directory. This is particular useful
456 to create configurations that deviate
457 from the suggested default
458 installation. In this case the
459 administrator must make sure to invoke
460 <command>daemon-reload</command>
461 manually as necessary, to ensure his
462 changes are taken into account.</para>
464 <para>Enabling units should not be
465 confused with starting (activating)
466 units, as done by the
467 <command>start</command>
468 command. Enabling and starting units
469 is orthogonal: units may be enabled
470 without being started and started
471 without being enabled. Enabling simply
472 hooks the unit into various suggested
473 places (for example, so that the unit
474 is automatically started on boot or
475 when a particular kind of hardware is
476 plugged in). Starting actually spawns
477 the daemon process (in case of service
478 units), or binds the socket (in case
479 of socket units), and so
482 <para>Depending on whether
483 <option>--system</option>,
484 <option>--session</option> or
485 <option>--global</option> is specified
486 this enables the unit for the system,
487 for sessions of the calling user only
488 or for all future session of all
489 users. Note that in the latter case no
490 systemd daemon configuration is
496 <term><command>disable [NAME...]</command></term>
498 <listitem><para>Disables one or more
499 units. This removes all symlinks to
500 the specified unit files from the unit
501 configuration directory, and hence
502 undoes the changes made by
503 <command>enable</command>. Note
504 however that this by default removes
505 all symlinks to the unit files
506 (i.e. including manual additions), not
507 just those actually created by
508 <command>enable</command>. If only the
509 symlinks that are suggested by default
510 shall be removed, pass
511 <option>--defaults</option>. This
512 implicitly reloads the systemd daemon
513 configuration after completing the
514 disabling of the units. Note that this
515 command does not implicitly stop the
516 units that is being disabled. If this
517 is desired an additional
518 <command>stop</command>command should
519 be executed afterwards.</para>
521 <para>This command will print the
522 actions executed. This output may be
523 suppressed by passing
524 <option>--quiet</option>.</para>
527 <para>This command honours
528 <option>--system</option>,
529 <option>--session</option>,
530 <option>--global</option> in a similar
532 <command>enable</command>.</para>
536 <term><command>is-enabled [NAME...]</command></term>
538 <listitem><para>Checks whether any of
539 the specified unit files is enabled
541 <command>enable</command>). Returns an
542 exit code of 0 if at least one is
544 otherwise.</para></listitem>
548 <term><command>load [NAME...]</command></term>
550 <listitem><para>Load one or more units
551 specified on the command line. This
552 will simply load their configuration
553 from disk, but not start them. To
554 start them you need to use the
555 <command>start</command> command which
556 will implicitly load a unit that has
557 not been loaded yet. Note that systemd
558 garbage collects loaded units that are
559 not active or referenced by an active
560 unit. This means that units loaded
561 this way will usually not stay loaded
562 for long. Also note that this command
563 cannot be used to reload unit
564 configuration. Use the
565 <command>daemon-reload</command>
566 command for that. All in all, this
567 command is of little use except for
569 <para>This command should not be
571 <command>daemon-reload</command> or
572 <command>reload</command>
573 commands.</para></listitem>
576 <term><command>list-jobs</command></term>
578 <listitem><para>List jobs that are in progress.</para></listitem>
581 <term><command>cancel [JOB...]</command></term>
583 <listitem><para>Cancel one or more
584 jobs specified on the command line by
586 IDs. If not job id is specified cancels all jobs that are pending.</para></listitem>
589 <term><command>monitor</command></term>
591 <listitem><para>Monitor unit/job
592 changes. This is mostly useful for
593 debugging purposes and prints a line
594 each time systemd loads or unloads a
595 unit configuration file, or a unit
596 property changes.</para></listitem>
599 <term><command>dump</command></term>
601 <listitem><para>Dump server
602 status. This will output a (usually
603 very long) human readable manager
604 status dump. Its format is subject to
605 change without notice and should not
607 applications.</para></listitem>
610 <term><command>dot</command></term>
612 <listitem><para>Generate textual
613 dependency graph description in dot
614 format for further processing with the
616 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
617 tool. Use a command line like
618 <command>systemctl dot | dot -Tsvg >
619 systemd.svg</command> to generate a
620 graphical dependency tree. Unless
621 <option>--order</option> or
622 <option>--require</option> is passed
623 the generated graph will show both
624 ordering and requirement
625 dependencies.</para></listitem>
628 <term><command>snapshot [NAME]</command></term>
630 <listitem><para>Create a snapshot. If
631 a snapshot name is specified, the new
632 snapshot will be named after it. If
633 none is specified an automatic
634 snapshot name is generated. In either
635 case, the snapshot name used is
636 printed to STDOUT, unless
637 <option>--quiet</option> is
640 <para>A snapshot refers to a saved
641 state of the systemd manager. It is
642 implemented itself as unit that is
643 generated dynamically with this
644 command and has dependencies on all
645 units active at the time. At a later
646 time the user may return to this state
648 <command>isolate</command> command on
649 the snapshot unit.</para></listitem>
651 <para>Snapshots are only useful for
652 saving and restoring which units are
653 running or are stopped, they do not
654 save/restore any other
655 state. Snapshots are dynamic and lost
659 <term><command>delete [NAME...]</command></term>
661 <listitem><para>Remove a snapshot
662 previously created with
663 <command>snapshot</command>.</para></listitem>
666 <term><command>daemon-reload</command></term>
668 <listitem><para>Reload systemd manager
669 configuration. This will reload all
670 unit files and recreate the entire
671 dependency tree. While the daemon is
672 reloaded, all sockets systemd listens
673 on on behalf of user configuration will
674 stay accessible.</para> <para>This
675 command should not be confused with
676 the <command>load</command> or
677 <command>reload</command>
678 commands.</para></listitem>
681 <term><command>daemon-reexec</command></term>
683 <listitem><para>Reexecute the systemd
684 manager. This will serialize the
685 manager state, reexecute the process
686 and deserialize the state again. This
687 command is of little use except for
688 debugging and package
689 upgrades. Sometimes it might be
690 helpful as a heavy-weight
691 <command>daemon-reload</command>. While
692 the daemon is reexecuted all sockets
693 systemd listens on on behalf of user
694 configuration will stay
695 accessible.</para></listitem>
698 <term><command>daemon-exit</command></term>
700 <listitem><para>Ask the systemd
701 manager to quit. This is only
702 supported for session managers
703 (i.e. in conjunction with the
704 <option>--session</option> option) and
705 will fail otherwise.</para></listitem>
708 <term><command>show-environment</command></term>
710 <listitem><para>Dump the systemd
711 manager environment block. The
712 environment block will be dumped in
713 straight-forward form suitable for
714 sourcing into a shell script. This
715 environment block will be passed to
716 all processes the manager
717 spawns.</para></listitem>
720 <term><command>set-environment [NAME=VALUE...]</command></term>
722 <listitem><para>Set one or more
723 systemd manager environment variables,
724 as specified on the command
725 line.</para></listitem>
728 <term><command>unset-environment [NAME...]</command></term>
730 <listitem><para>Unset one or more
731 systemd manager environment
732 variables. If only a variable name is
733 specified it will be removed
734 regardless of its value. If a variable
735 and a value are specified the variable
736 is only removed if it has the
737 specified value.</para></listitem>
741 <term><command>halt</command></term>
743 <listitem><para>Shut down and halt the
744 system. This is mostly equivalent to
745 <command>start halt.target</command>
746 but also prints a wall message to all
747 users.</para></listitem>
750 <term><command>poweroff</command></term>
752 <listitem><para>Shut down and
753 power-off the system. This is mostly
754 equivalent to <command>start
755 poweroff.target</command> but also
756 prints a wall message to all
757 users.</para></listitem>
760 <term><command>reboot</command></term>
762 <listitem><para>Shut down and
763 reboot the system. This is mostly
764 equivalent to <command>start
765 reboot.target</command> but also
766 prints a wall message to all
767 users.</para></listitem>
770 <term><command>default</command></term>
772 <listitem><para>Enter default
773 mode. This is mostly equivalent to
775 default.target</command>.</para></listitem>
778 <term><command>rescue</command></term>
780 <listitem><para>Enter rescue
781 mode. This is mostly equivalent to
783 rescue.target</command> but also
784 prints a wall message to all
785 users.</para></listitem>
788 <term><command>emergency</command></term>
790 <listitem><para>Enter emergency
791 mode. This is mostly equivalent to
793 emergency.target</command> but also
794 prints a wall message to all
795 users.</para></listitem>
802 <title>Exit status</title>
804 <para>On success 0 is returned, a non-zero failure
805 code otherwise.</para>
809 <title>See Also</title>
811 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
812 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
813 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
814 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
815 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>