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="systemd-install">
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 property names. If
100 not specified all set properties are
101 shown. The argument should be a
102 property name, such as
103 <literal>MainPID</literal>. If
104 specified more than once all
105 properties with the specified names
106 are shown.</para></listitem>
110 <term><option>--all</option></term>
111 <term><option>-a</option></term>
113 <listitem><para>When listing units,
114 show all units, regardless of their
115 state, including inactive units. When
116 showing unit/job/manager information,
117 show all properties regardless whether
118 they are set or not.</para></listitem>
122 <term><option>--full</option></term>
124 <listitem><para>Do not ellipsize unit
125 names in the output of
126 <command>list-units</command> and
127 <command>list-jobs</command>.</para></listitem>
131 <term><option>--fail</option></term>
133 <listitem><para>If the requested
134 operation conflicts with an existing
135 unfinished operation, fail the
136 command. If this is not specified the
137 requested operation will replace the
139 necessary.</para></listitem>
143 <term><option>--order</option></term>
144 <term><option>--require</option></term>
146 <listitem><para>When used in
148 <command>dot</command> command (see
149 below), selects which dependencies are
150 shown in the dependency graph. If
151 <option>--order</option> is passed
152 only dependencies of type
153 <varname>After=</varname> or
154 <varname>Before=</varname> are
155 shown. If <option>--require</option>
156 is passed only dependencies of type
157 <varname>Requires=</varname>,
158 <varname>RequiresOverridable=</varname>,
159 <varname>Requisite=</varname>,
160 <varname>RequisiteOverridable=</varname>,
161 <varname>Wants=</varname> and
162 <varname>Conflicts=</varname> are
163 shown. If neither is passed, shows
164 dependencies of all these
165 types.</para></listitem>
169 <term><option>--system</option></term>
171 <listitem><para>Talk to the systemd
172 system manager. (Default)</para></listitem>
176 <term><option>--session</option></term>
178 <listitem><para>Talk to the systemd
179 session manager of the calling user.</para></listitem>
183 <term><option>--no-block</option></term>
185 <listitem><para>Do not synchronously wait for
186 the requested operation to finish. If this is
187 not specified the job will be verified,
188 enqueued and <command>systemctl</command> will
189 wait until it is completed. By passing this
190 argument it is only verified and
191 enqueued.</para></listitem> </varlistentry>
194 <term><option>--quiet</option></term>
195 <term><option>-q</option></term>
197 <listitem><para>Suppress output to
198 STDOUT for <command>snapshot</command>
200 <command>check</command>.</para></listitem>
204 <term><option>--no-wall</option></term>
206 <listitem><para>Don't send wall
208 halt, power-off, reboot.</para></listitem>
212 <para>The following commands are understood:</para>
216 <term><command>list-units</command></term>
218 <listitem><para>List known units.</para></listitem>
221 <term><command>start [NAME...]</command></term>
223 <listitem><para>Start one or more
224 units specified on the command
225 line.</para></listitem>
228 <term><command>stop [NAME...]</command></term>
230 <listitem><para>Stop one or more units
231 specified on the command
232 line.</para></listitem>
235 <term><command>reload [NAME...]</command></term>
237 <listitem><para>Asks all services
238 whose units are listed on the command
240 configuration. Note that this will
241 reload the daemon configuration
242 itself, not the unit configuration
243 file of systemd. If you want systemd
244 to reload the configuration file of a
246 <command>daemon-reload</command>
247 command. In other words: for the
248 example case of Apache, this will
250 <filename>httpd.conf</filename> in the
252 <filename>apache.service</filename>
253 systemd unit file. </para> <para>This
254 command should not be confused with
255 the <command>daemon-reload</command>
256 or <command>load</command>
257 commands.</para></listitem>
261 <term><command>restart [NAME...]</command></term>
263 <listitem><para>Restart one or more
264 units specified on the command
265 line. If the units are not running yet
267 started.</para></listitem>
270 <term><command>try-restart [NAME...]</command></term>
272 <listitem><para>Restart one or more
273 units specified on the command
274 line. If the units are not running yet
276 fail.</para></listitem>
279 <term><command>reload-or-restart [NAME...]</command></term>
280 <term><command>reload-or-try-restart [NAME...]</command></term>
282 <listitem><para>Reload one or more
283 units if they support it. If not
285 instead.</para></listitem>
288 <term><command>isolate [NAME]</command></term>
290 <listitem><para>Start the unit
291 specified on the command line and its
292 dependencies and stop all
293 others.</para></listitem>
296 <term><command>check [NAME...]</command></term>
298 <listitem><para>Check whether any of
299 the specified units is active
300 (i.e. running). Returns 0 if at least
301 one is active, non-zero
303 <option>--quiet</option> is specified
304 this will also print the current unit
305 state to STDOUT.</para></listitem>
308 <term><command>status [NAME...]</command></term>
310 <listitem><para>Show short status
311 information about one or more
312 units. This shows terse runtime
314 units.</para></listitem>
317 <term><command>show [NAME...|JOB...]</command></term>
319 <listitem><para>Show properties of
320 one or more units, jobs or the manager
321 itself. If no argument is specified
322 properties of the manager will be
323 shown. If a unit name is specified
324 properties of the unit is shown,
325 and if a job id is specified
326 properties of the job is
327 shown.</para></listitem>
331 <term><command>reset-maintenance [NAME...]</command></term>
333 <listitem><para>Reset maintenance
334 state of the specified units, or if no
335 unit name is passed of all units. When
336 a unit fails in some way (i.e. process
337 exiting with non-zero error code,
338 terminating abnormally or timing out)
339 it will automatically enter
340 maintenance state and its exit codes
341 and status is recorded for
342 introspection by the administrator
343 until the service is restarted or
345 command.</para></listitem>
349 <term><command>load [NAME...]</command></term>
351 <listitem><para>Load one or more units
352 specified on the command line. This
353 will simply load their configuration
354 from disk, but not start them. To
355 start them you need to use the
356 <command>start</command> command which
357 will implicitly load a unit that has
358 not been loaded yet. Note that systemd
359 garbage collects loaded units that are
360 not active or referenced by an active
361 unit. This means that units loaded
362 this way will usually not stay loaded
363 for long. Also note that this command
364 cannot be used to reload unit
365 configuration. Use the
366 <command>daemon-reload</command>
367 command for that. All in all, this
368 command is of little use except for
370 <para>This command should not be
372 <command>daemon-reload</command> or
373 <command>reload</command>
374 commands.</para></listitem>
377 <term><command>list-jobs</command></term>
379 <listitem><para>List jobs that are in progress.</para></listitem>
382 <term><command>cancel [JOB...]</command></term>
384 <listitem><para>Cancel one or more
385 jobs specified on the command line by
387 IDs.</para></listitem>
390 <term><command>clear-jobs</command></term>
392 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
395 <term><command>monitor</command></term>
397 <listitem><para>Monitor unit/job
398 changes. This is mostly useful for
399 debugging purposes and prints a line
400 each time systemd loads or unloads a
401 unit configuration file, or a unit
402 property changes.</para></listitem>
405 <term><command>dump</command></term>
407 <listitem><para>Dump server
408 status. This will output a (usually
409 very long) human readable manager
410 status dump. Its format is subject to
411 change without notice and should not
413 applications.</para></listitem>
416 <term><command>dot</command></term>
418 <listitem><para>Generate textual
419 dependency graph description in dot
420 format for further processing with the
422 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
423 tool. Use a command line like
424 <command>systemctl dot | dot -Tsvg >
425 systemd.svg</command> to generate a
426 graphical dependency tree. Unless
427 <option>--order</option> or
428 <option>--require</option> is passed
429 the generated graph will show both
430 ordering and requirement
431 dependencies.</para></listitem>
434 <term><command>snapshot [NAME]</command></term>
436 <listitem><para>Create a snapshot. If
437 a snapshot name is specified, the new
438 snapshot will be named after it. If
439 none is specified an automatic
440 snapshot name is generated. In either
441 case, the snapshot name used is
442 printed to STDOUT, unless
443 <option>--quiet</option> is
446 <para>A snapshot refers to a saved
447 state of the systemd manager. It is
448 implemented itself as unit that is
449 generated dynamically with this
450 command and has dependencies on all
451 units active at the time. At a later
452 time the user may return to this state
454 <command>isolate</command> command on
455 the snapshot unit.</para></listitem>
457 <para>Snapshots are only useful for
458 saving and restoring which units are
459 running or are stopped, they do not
460 save/restore any other
461 state. Snapshots are dynamic and lost
465 <term><command>delete [NAME...]</command></term>
467 <listitem><para>Remove a snapshot
468 previously created with
469 <command>snapshot</command>.</para></listitem>
472 <term><command>daemon-reload</command></term>
474 <listitem><para>Reload systemd manager
475 configuration. This will reload all
476 unit files and recreate the entire
477 dependency tree. While the daemon is
478 reloaded, all sockets systemd listens
479 on on behalf of user configuration will
480 stay accessible.</para> <para>This
481 command should not be confused with
482 the <command>load</command> or
483 <command>reload</command>
484 commands.</para></listitem>
487 <term><command>daemon-reexec</command></term>
489 <listitem><para>Reexecute the systemd
490 manager. This will serialize the
491 manager state, reexecute the process
492 and deserialize the state again. This
493 command is of little use except for
494 debugging and package
495 upgrades. Sometimes it might be
496 helpful as a heavy-weight
497 <command>daemon-reload</command>. While
498 the daemon is reexecuted all sockets
499 systemd listens on on behalf of user
500 configuration will stay
501 accessible.</para></listitem>
504 <term><command>daemon-exit</command></term>
506 <listitem><para>Ask the systemd
507 manager to quit. This is only
508 supported for session managers
509 (i.e. in conjunction with the
510 <option>--session</option> option) and
511 will fail otherwise.</para></listitem>
514 <term><command>show-environment</command></term>
516 <listitem><para>Dump the systemd
517 manager environment block. The
518 environment block will be dumped in
519 straight-forward form suitable for
520 sourcing into a shell script. This
521 environment block will be passed to
522 all processes the manager
523 spawns.</para></listitem>
526 <term><command>set-environment [NAME=VALUE...]</command></term>
528 <listitem><para>Set one or more
529 systemd manager environment variables,
530 as specified on the command
531 line.</para></listitem>
534 <term><command>unset-environment [NAME...]</command></term>
536 <listitem><para>Unset one or more
537 systemd manager environment
538 variables. If only a variable name is
539 specified it will be removed
540 regardless of its value. If a variable
541 and a value are specified the variable
542 is only removed if it has the
543 specified value.</para></listitem>
547 <term><command>halt</command></term>
549 <listitem><para>Shut down and halt the
550 system. This is mostly equivalent to
551 <command>start halt.target</command>
552 but also prints a wall message to all
553 users.</para></listitem>
556 <term><command>poweroff</command></term>
558 <listitem><para>Shut down and
559 power-off the system. This is mostly
560 equivalent to <command>start
561 poweroff.target</command> but also
562 prints a wall message to all
563 users.</para></listitem>
566 <term><command>reboot</command></term>
568 <listitem><para>Shut down and
569 reboot the system. This is mostly
570 equivalent to <command>start
571 reboot.target</command> but also
572 prints a wall message to all
573 users.</para></listitem>
576 <term><command>default</command></term>
578 <listitem><para>Enter default
579 mode. This is mostly equivalent to
581 default.target</command>.</para></listitem>
584 <term><command>rescue</command></term>
586 <listitem><para>Enter rescue
587 mode. This is mostly equivalent to
589 rescue.target</command> but also
590 prints a wall message to all
591 users.</para></listitem>
594 <term><command>emergency</command></term>
596 <listitem><para>Enter emergency
597 mode. This is mostly equivalent to
599 emergency.target</command> but also
600 prints a wall message to all
601 users.</para></listitem>
608 <title>Exit status</title>
610 <para>On success 0 is returned, a non-zero failure
611 code otherwise.</para>
615 <title>See Also</title>
617 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
618 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
619 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
620 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
621 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>