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>--fail
</option></term>
121 <listitem><para>If the requested
122 operation conflicts with an existing
123 unfinished operation, fail the
124 command. If this is not specified the
125 requested operation will replace the
127 necessary.
</para></listitem>
131 <term><option>--order
</option></term>
132 <term><option>--require
</option></term>
134 <listitem><para>When used in
136 <command>dot
</command> command (see
137 below), selects which dependencies are
138 shown in the dependency graph. If
139 <option>--order
</option> is passed
140 only dependencies of type
141 <varname>After=
</varname> or
142 <varname>Before=
</varname> are
143 shown. If
<option>--require
</option>
144 is passed only dependencies of type
145 <varname>Requires=
</varname>,
146 <varname>RequiresOverridable=
</varname>,
147 <varname>Requisite=
</varname>,
148 <varname>RequisiteOverridable=
</varname>,
149 <varname>Wants=
</varname> and
150 <varname>Conflicts=
</varname> are
151 shown. If neither is passed, shows
152 dependencies of all these
153 types.
</para></listitem>
157 <term><option>--system
</option></term>
159 <listitem><para>Talk to the systemd
160 system manager. (Default)
</para></listitem>
164 <term><option>--session
</option></term>
166 <listitem><para>Talk to the systemd
167 session manager of the calling user.
</para></listitem>
171 <term><option>--no-block
</option></term>
173 <listitem><para>Do not synchronously wait for
174 the requested operation to finish. If this is
175 not specified the job will be verified,
176 enqueued and
<command>systemctl
</command> will
177 wait until it is completed. By passing this
178 argument it is only verified and
179 enqueued.
</para></listitem> </varlistentry>
182 <term><option>--quiet
</option></term>
183 <term><option>-q
</option></term>
185 <listitem><para>Suppress output to
186 STDOUT for
<command>snapshot
</command>
188 <command>check
</command>.
</para></listitem>
192 <term><option>--no-wall
</option></term>
194 <listitem><para>Don't send wall
196 halt, power-off, reboot.
</para></listitem>
200 <para>The following commands are understood:
</para>
204 <term><command>list-units
</command></term>
206 <listitem><para>List known units.
</para></listitem>
209 <term><command>start [NAME...]
</command></term>
211 <listitem><para>Start one or more
212 units specified on the command
213 line.
</para></listitem>
216 <term><command>stop [NAME...]
</command></term>
218 <listitem><para>Stop one or more units
219 specified on the command
220 line.
</para></listitem>
223 <term><command>reload [NAME...]
</command></term>
225 <listitem><para>Asks all services
226 whose units are listed on the command
228 configuration. Note that this will
229 reload the daemon configuration
230 itself, not the unit configuration
231 file of systemd. If you want systemd
232 to reload the configuration file of a
234 <command>daemon-reload
</command>
235 command. In other words: for the
236 example case of Apache, this will
238 <filename>httpd.conf
</filename> in the
240 <filename>apache.service
</filename>
241 systemd unit file.
</para> <para>This
242 command should not be confused with
243 the
<command>daemon-reload
</command>
244 or
<command>load
</command>
245 commands.
</para></listitem>
249 <term><command>restart [NAME...]
</command></term>
251 <listitem><para>Restart one or more
252 units specified on the command
253 line. If the units are not running yet
255 started.
</para></listitem>
258 <term><command>try-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 fail.
</para></listitem>
267 <term><command>reload-or-restart [NAME...]
</command></term>
268 <term><command>reload-or-try-restart [NAME...]
</command></term>
270 <listitem><para>Reload one or more
271 units if they support it. If not
273 instead.
</para></listitem>
276 <term><command>isolate [NAME]
</command></term>
278 <listitem><para>Start the unit
279 specified on the command line and its
280 dependencies and stop all
281 others.
</para></listitem>
284 <term><command>check [NAME...]
</command></term>
286 <listitem><para>Check whether any of
287 the specified units is active
288 (i.e. running). Returns
0 if at least
289 one is active, non-zero
291 <option>--quiet
</option> is specified
292 this will also print the current unit
293 state to STDOUT.
</para></listitem>
296 <term><command>status [NAME...]
</command></term>
298 <listitem><para>Show short status
299 information about one or more
300 units. This shows terse runtime
302 units.
</para></listitem>
305 <term><command>show [NAME...|JOB...]
</command></term>
307 <listitem><para>Show properties of
308 one or more units, jobs or the manager
309 itself. If no argument is specified
310 properties of the manager will be
311 shown. If a unit name is specified
312 properties of the unit is shown,
313 and if a job id is specified
314 properties of the job is
315 shown.
</para></listitem>
318 <term><command>load [NAME...]
</command></term>
320 <listitem><para>Load one or more units
321 specified on the command line. This
322 will simply load their configuration
323 from disk, but not start them. To
324 start them you need to use the
325 <command>start
</command> command which
326 will implicitly load a unit that has
327 not been loaded yet. Note that systemd
328 garbage collects loaded units that are
329 not active or referenced by an active
330 unit. This means that units loaded
331 this way will usually not stay loaded
332 for long. Also note that this command
333 cannot be used to reload unit
334 configuration. Use the
335 <command>daemon-reload
</command>
336 command for that. All in all, this
337 command is of little use except for
339 <para>This command should not be
341 <command>daemon-reload
</command> or
342 <command>reload
</command>
343 commands.
</para></listitem>
346 <term><command>list-jobs
</command></term>
348 <listitem><para>List jobs that are in progress.
</para></listitem>
351 <term><command>cancel [JOB...]
</command></term>
353 <listitem><para>Cancel one or more
354 jobs specified on the command line by
356 IDs.
</para></listitem>
359 <term><command>clear-jobs
</command></term>
361 <listitem><para>Cancel all jobs that are in progress.
</para></listitem>
364 <term><command>monitor
</command></term>
366 <listitem><para>Monitor unit/job
367 changes. This is mostly useful for
368 debugging purposes and prints a line
369 each time systemd loads or unloads a
370 unit configuration file, or a unit
371 property changes.
</para></listitem>
374 <term><command>dump
</command></term>
376 <listitem><para>Dump server
377 status. This will output a (usually
378 very long) human readable manager
379 status dump. Its format is subject to
380 change without notice and should not
382 applications.
</para></listitem>
385 <term><command>dot
</command></term>
387 <listitem><para>Generate textual
388 dependency graph description in dot
389 format for further processing with the
391 <citerefentry><refentrytitle>dot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
392 tool. Use a command line like
393 <command>systemctl dot | dot -Tsvg
>
394 systemd.svg
</command> to generate a
395 graphical dependency tree. Unless
396 <option>--order
</option> or
397 <option>--require
</option> is passed
398 the generated graph will show both
399 ordering and requirement
400 dependencies.
</para></listitem>
403 <term><command>snapshot [NAME]
</command></term>
405 <listitem><para>Create a snapshot. If
406 a snapshot name is specified, the new
407 snapshot will be named after it. If
408 none is specified an automatic
409 snapshot name is generated. In either
410 case, the snapshot name used is
411 printed to STDOUT, unless
412 <option>--quiet
</option> is
415 <para>A snapshot refers to a saved
416 state of the systemd manager. It is
417 implemented itself as unit that is
418 generated dynamically with this
419 command and has dependencies on all
420 units active at the time. At a later
421 time the user may return to this state
423 <command>isolate
</command> command on
424 the snapshot unit.
</para></listitem>
426 <para>Snapshots are only useful for
427 saving and restoring which units are
428 running or are stopped, they do not
429 save/restore any other
430 state. Snapshots are dynamic and lost
434 <term><command>delete [NAME...]
</command></term>
436 <listitem><para>Remove a snapshot
437 previously created with
438 <command>snapshot
</command>.
</para></listitem>
441 <term><command>daemon-reload
</command></term>
443 <listitem><para>Reload systemd manager
444 configuration. This will reload all
445 unit files and recreate the entire
446 dependency tree. While the daemon is
447 reloaded, all sockets systemd listens
448 on on behalf of user configuration will
449 stay accessible.
</para> <para>This
450 command should not be confused with
451 the
<command>load
</command> or
452 <command>reload
</command>
453 commands.
</para></listitem>
456 <term><command>daemon-reexec
</command></term>
458 <listitem><para>Reexecute the systemd
459 manager. This will serialize the
460 manager state, reexecute the process
461 and deserialize the state again. This
462 command is of little use except for
463 debugging and package
464 upgrades. Sometimes it might be
465 helpful as a heavy-weight
466 <command>daemon-reload
</command>. While
467 the daemon is reexecuted all sockets
468 systemd listens on on behalf of user
469 configuration will stay
470 accessible.
</para></listitem>
473 <term><command>daemon-exit
</command></term>
475 <listitem><para>Ask the systemd
476 manager to quit. This is only
477 supported for session managers
478 (i.e. in conjunction with the
479 <option>--session
</option> option) and
480 will fail otherwise.
</para></listitem>
483 <term><command>show-environment
</command></term>
485 <listitem><para>Dump the systemd
486 manager environment block. The
487 environment block will be dumped in
488 straight-forward form suitable for
489 sourcing into a shell script. This
490 environment block will be passed to
491 all processes the manager
492 spawns.
</para></listitem>
495 <term><command>set-environment [NAME=VALUE...]
</command></term>
497 <listitem><para>Set one or more
498 systemd manager environment variables,
499 as specified on the command
500 line.
</para></listitem>
503 <term><command>unset-environment [NAME...]
</command></term>
505 <listitem><para>Unset one or more
506 systemd manager environment
507 variables. If only a variable name is
508 specified it will be removed
509 regardless of its value. If a variable
510 and a value are specified the variable
511 is only removed if it has the
512 specified value.
</para></listitem>
516 <term><command>halt
</command></term>
518 <listitem><para>Shut down and halt the
519 system. This is mostly equivalent to
520 <command>start halt.target
</command>
521 but also prints a wall message to all
522 users.
</para></listitem>
525 <term><command>poweroff
</command></term>
527 <listitem><para>Shut down and
528 power-off the system. This is mostly
529 equivalent to
<command>start
530 poweroff.target
</command> but also
531 prints a wall message to all
532 users.
</para></listitem>
535 <term><command>reboot
</command></term>
537 <listitem><para>Shut down and
538 reboot the system. This is mostly
539 equivalent to
<command>start
540 reboot.target
</command> but also
541 prints a wall message to all
542 users.
</para></listitem>
545 <term><command>default
</command></term>
547 <listitem><para>Enter default
548 mode. This is mostly equivalent to
550 default.target
</command>.
</para></listitem>
553 <term><command>rescue
</command></term>
555 <listitem><para>Enter rescue
556 mode. This is mostly equivalent to
558 rescue.target
</command> but also
559 prints a wall message to all
560 users.
</para></listitem>
563 <term><command>emergency
</command></term>
565 <listitem><para>Enter emergency
566 mode. This is mostly equivalent to
568 emergency.target
</command> but also
569 prints a wall message to all
570 users.
</para></listitem>
577 <title>Exit status
</title>
579 <para>On success
0 is returned, a non-zero failure
580 code otherwise.
</para>
584 <title>See Also
</title>
586 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
587 <citerefentry><refentrytitle>systemadm
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
588 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
589 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
590 <citerefentry><refentrytitle>wall
</refentrytitle><manvolnum>1</manvolnum></citerefentry>