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>.</para></listitem>
107 <term><option>--all</option></term>
108 <term><option>-a</option></term>
110 <listitem><para>When listing units,
111 show all units, regardless of their
112 state, including inactive units. When
113 showing unit/job/manager information,
114 show all properties regardless whether
115 they are set or not.</para></listitem>
119 <term><option>--full</option></term>
121 <listitem><para>Do not ellipsize unit
122 names in the output of
123 <command>list-units</command> and
124 <command>list-jobs</command>.</para></listitem>
128 <term><option>--fail</option></term>
130 <listitem><para>If the requested
131 operation conflicts with an existing
132 unfinished operation, fail the
133 command. If this is not specified the
134 requested operation will replace the
136 necessary.</para></listitem>
140 <term><option>--order</option></term>
141 <term><option>--require</option></term>
143 <listitem><para>When used in
145 <command>dot</command> command (see
146 below), selects which dependencies are
147 shown in the dependency graph. If
148 <option>--order</option> is passed
149 only dependencies of type
150 <varname>After=</varname> or
151 <varname>Before=</varname> are
152 shown. If <option>--require</option>
153 is passed only dependencies of type
154 <varname>Requires=</varname>,
155 <varname>RequiresOverridable=</varname>,
156 <varname>Requisite=</varname>,
157 <varname>RequisiteOverridable=</varname>,
158 <varname>Wants=</varname> and
159 <varname>Conflicts=</varname> are
160 shown. If neither is passed, shows
161 dependencies of all these
162 types.</para></listitem>
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>--no-block</option></term>
182 <listitem><para>Do not synchronously wait for
183 the requested operation to finish. If this is
184 not specified the job will be verified,
185 enqueued and <command>systemctl</command> will
186 wait until it is completed. By passing this
187 argument it is only verified and
188 enqueued.</para></listitem> </varlistentry>
191 <term><option>--quiet</option></term>
192 <term><option>-q</option></term>
194 <listitem><para>Suppress output to
195 STDOUT for <command>snapshot</command>
197 <command>check</command>.</para></listitem>
201 <term><option>--no-wall</option></term>
203 <listitem><para>Don't send wall
205 halt, power-off, reboot.</para></listitem>
209 <para>The following commands are understood:</para>
213 <term><command>list-units</command></term>
215 <listitem><para>List known units.</para></listitem>
218 <term><command>start [NAME...]</command></term>
220 <listitem><para>Start one or more
221 units specified on the command
222 line.</para></listitem>
225 <term><command>stop [NAME...]</command></term>
227 <listitem><para>Stop one or more units
228 specified on the command
229 line.</para></listitem>
232 <term><command>reload [NAME...]</command></term>
234 <listitem><para>Asks all services
235 whose units are listed on the command
237 configuration. Note that this will
238 reload the daemon configuration
239 itself, not the unit configuration
240 file of systemd. If you want systemd
241 to reload the configuration file of a
243 <command>daemon-reload</command>
244 command. In other words: for the
245 example case of Apache, this will
247 <filename>httpd.conf</filename> in the
249 <filename>apache.service</filename>
250 systemd unit file. </para> <para>This
251 command should not be confused with
252 the <command>daemon-reload</command>
253 or <command>load</command>
254 commands.</para></listitem>
258 <term><command>restart [NAME...]</command></term>
260 <listitem><para>Restart one or more
261 units specified on the command
262 line. If the units are not running yet
264 started.</para></listitem>
267 <term><command>try-restart [NAME...]</command></term>
269 <listitem><para>Restart one or more
270 units specified on the command
271 line. If the units are not running yet
273 fail.</para></listitem>
276 <term><command>reload-or-restart [NAME...]</command></term>
277 <term><command>reload-or-try-restart [NAME...]</command></term>
279 <listitem><para>Reload one or more
280 units if they support it. If not
282 instead.</para></listitem>
285 <term><command>isolate [NAME]</command></term>
287 <listitem><para>Start the unit
288 specified on the command line and its
289 dependencies and stop all
290 others.</para></listitem>
293 <term><command>check [NAME...]</command></term>
295 <listitem><para>Check whether any of
296 the specified units is active
297 (i.e. running). Returns 0 if at least
298 one is active, non-zero
300 <option>--quiet</option> is specified
301 this will also print the current unit
302 state to STDOUT.</para></listitem>
305 <term><command>status [NAME...]</command></term>
307 <listitem><para>Show short status
308 information about one or more
309 units. This shows terse runtime
311 units.</para></listitem>
314 <term><command>show [NAME...|JOB...]</command></term>
316 <listitem><para>Show properties of
317 one or more units, jobs or the manager
318 itself. If no argument is specified
319 properties of the manager will be
320 shown. If a unit name is specified
321 properties of the unit is shown,
322 and if a job id is specified
323 properties of the job is
324 shown.</para></listitem>
328 <term><command>reset-maintenance [NAME...]</command></term>
330 <listitem><para>Reset maintenance
331 state of the specified units, or if no
332 unit name is passed of all units. When
333 a unit fails in some way (i.e. process
334 exiting with non-zero error code,
335 terminating abnormally or timing out)
336 it will automatically enter
337 maintenance state and its exit codes
338 and status is recorded for
339 introspection by the administrator
340 until the service is restarted or
342 command.</para></listitem>
346 <term><command>load [NAME...]</command></term>
348 <listitem><para>Load one or more units
349 specified on the command line. This
350 will simply load their configuration
351 from disk, but not start them. To
352 start them you need to use the
353 <command>start</command> command which
354 will implicitly load a unit that has
355 not been loaded yet. Note that systemd
356 garbage collects loaded units that are
357 not active or referenced by an active
358 unit. This means that units loaded
359 this way will usually not stay loaded
360 for long. Also note that this command
361 cannot be used to reload unit
362 configuration. Use the
363 <command>daemon-reload</command>
364 command for that. All in all, this
365 command is of little use except for
367 <para>This command should not be
369 <command>daemon-reload</command> or
370 <command>reload</command>
371 commands.</para></listitem>
374 <term><command>list-jobs</command></term>
376 <listitem><para>List jobs that are in progress.</para></listitem>
379 <term><command>cancel [JOB...]</command></term>
381 <listitem><para>Cancel one or more
382 jobs specified on the command line by
384 IDs.</para></listitem>
387 <term><command>clear-jobs</command></term>
389 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
392 <term><command>monitor</command></term>
394 <listitem><para>Monitor unit/job
395 changes. This is mostly useful for
396 debugging purposes and prints a line
397 each time systemd loads or unloads a
398 unit configuration file, or a unit
399 property changes.</para></listitem>
402 <term><command>dump</command></term>
404 <listitem><para>Dump server
405 status. This will output a (usually
406 very long) human readable manager
407 status dump. Its format is subject to
408 change without notice and should not
410 applications.</para></listitem>
413 <term><command>dot</command></term>
415 <listitem><para>Generate textual
416 dependency graph description in dot
417 format for further processing with the
419 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
420 tool. Use a command line like
421 <command>systemctl dot | dot -Tsvg >
422 systemd.svg</command> to generate a
423 graphical dependency tree. Unless
424 <option>--order</option> or
425 <option>--require</option> is passed
426 the generated graph will show both
427 ordering and requirement
428 dependencies.</para></listitem>
431 <term><command>snapshot [NAME]</command></term>
433 <listitem><para>Create a snapshot. If
434 a snapshot name is specified, the new
435 snapshot will be named after it. If
436 none is specified an automatic
437 snapshot name is generated. In either
438 case, the snapshot name used is
439 printed to STDOUT, unless
440 <option>--quiet</option> is
443 <para>A snapshot refers to a saved
444 state of the systemd manager. It is
445 implemented itself as unit that is
446 generated dynamically with this
447 command and has dependencies on all
448 units active at the time. At a later
449 time the user may return to this state
451 <command>isolate</command> command on
452 the snapshot unit.</para></listitem>
454 <para>Snapshots are only useful for
455 saving and restoring which units are
456 running or are stopped, they do not
457 save/restore any other
458 state. Snapshots are dynamic and lost
462 <term><command>delete [NAME...]</command></term>
464 <listitem><para>Remove a snapshot
465 previously created with
466 <command>snapshot</command>.</para></listitem>
469 <term><command>daemon-reload</command></term>
471 <listitem><para>Reload systemd manager
472 configuration. This will reload all
473 unit files and recreate the entire
474 dependency tree. While the daemon is
475 reloaded, all sockets systemd listens
476 on on behalf of user configuration will
477 stay accessible.</para> <para>This
478 command should not be confused with
479 the <command>load</command> or
480 <command>reload</command>
481 commands.</para></listitem>
484 <term><command>daemon-reexec</command></term>
486 <listitem><para>Reexecute the systemd
487 manager. This will serialize the
488 manager state, reexecute the process
489 and deserialize the state again. This
490 command is of little use except for
491 debugging and package
492 upgrades. Sometimes it might be
493 helpful as a heavy-weight
494 <command>daemon-reload</command>. While
495 the daemon is reexecuted all sockets
496 systemd listens on on behalf of user
497 configuration will stay
498 accessible.</para></listitem>
501 <term><command>daemon-exit</command></term>
503 <listitem><para>Ask the systemd
504 manager to quit. This is only
505 supported for session managers
506 (i.e. in conjunction with the
507 <option>--session</option> option) and
508 will fail otherwise.</para></listitem>
511 <term><command>show-environment</command></term>
513 <listitem><para>Dump the systemd
514 manager environment block. The
515 environment block will be dumped in
516 straight-forward form suitable for
517 sourcing into a shell script. This
518 environment block will be passed to
519 all processes the manager
520 spawns.</para></listitem>
523 <term><command>set-environment [NAME=VALUE...]</command></term>
525 <listitem><para>Set one or more
526 systemd manager environment variables,
527 as specified on the command
528 line.</para></listitem>
531 <term><command>unset-environment [NAME...]</command></term>
533 <listitem><para>Unset one or more
534 systemd manager environment
535 variables. If only a variable name is
536 specified it will be removed
537 regardless of its value. If a variable
538 and a value are specified the variable
539 is only removed if it has the
540 specified value.</para></listitem>
544 <term><command>halt</command></term>
546 <listitem><para>Shut down and halt the
547 system. This is mostly equivalent to
548 <command>start halt.target</command>
549 but also prints a wall message to all
550 users.</para></listitem>
553 <term><command>poweroff</command></term>
555 <listitem><para>Shut down and
556 power-off the system. This is mostly
557 equivalent to <command>start
558 poweroff.target</command> but also
559 prints a wall message to all
560 users.</para></listitem>
563 <term><command>reboot</command></term>
565 <listitem><para>Shut down and
566 reboot the system. This is mostly
567 equivalent to <command>start
568 reboot.target</command> but also
569 prints a wall message to all
570 users.</para></listitem>
573 <term><command>default</command></term>
575 <listitem><para>Enter default
576 mode. This is mostly equivalent to
578 default.target</command>.</para></listitem>
581 <term><command>rescue</command></term>
583 <listitem><para>Enter rescue
584 mode. This is mostly equivalent to
586 rescue.target</command> but also
587 prints a wall message to all
588 users.</para></listitem>
591 <term><command>emergency</command></term>
593 <listitem><para>Enter emergency
594 mode. This is mostly equivalent to
596 emergency.target</command> but also
597 prints a wall message to all
598 users.</para></listitem>
605 <title>Exit status</title>
607 <para>On success 0 is returned, a non-zero failure
608 code otherwise.</para>
612 <title>See Also</title>
614 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
615 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
616 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
617 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
618 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>