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>--system</option></term>
133 <listitem><para>Talk to the systemd
134 system manager. (Default)</para></listitem>
138 <term><option>--session</option></term>
140 <listitem><para>Talk to the systemd
141 session manager of the calling user.</para></listitem>
145 <term><option>--no-block</option></term>
147 <listitem><para>Do not synchronously wait for
148 the requested operation to finish. If this is
149 not specified the job will be verified,
150 enqueued and <command>systemctl</command> will
151 wait until it is completed. By passing this
152 argument it is only verified and
153 enqueued.</para></listitem> </varlistentry>
156 <term><option>--quiet</option></term>
157 <term><option>-q</option></term>
159 <listitem><para>Suppress output to
160 STDOUT for <command>snapshot</command>
162 <command>check</command>.</para></listitem>
166 <term><option>--no-wall</option></term>
168 <listitem><para>Don't send wall
170 halt, power-off, reboot.</para></listitem>
174 <para>The following commands are understood:</para>
178 <term><command>list-units</command></term>
180 <listitem><para>List known units.</para></listitem>
183 <term><command>start [NAME...]</command></term>
185 <listitem><para>Start one or more
186 units specified on the command
187 line.</para></listitem>
190 <term><command>stop [NAME...]</command></term>
192 <listitem><para>Stop one or more units
193 specified on the command
194 line.</para></listitem>
197 <term><command>reload [NAME...]</command></term>
199 <listitem><para>Asks all services
200 whose units are listed on the command
202 configuration. Note that this will
203 reload the daemon configuration
204 itself, not the unit configuration
205 file of systemd. If you want systemd
206 to reload the configuration file of a
208 <command>daemon-reload</command>
209 command. In other words: for the
210 example case of Apache, this will
212 <filename>httpd.conf</filename> in the
214 <filename>apache.service</filename>
215 systemd unit file. </para> <para>This
216 command should not be confused with
217 the <command>daemon-reload</command>
218 or <command>load</command>
219 commands.</para></listitem>
223 <term><command>restart [NAME...]</command></term>
225 <listitem><para>Restart one or more
226 units specified on the command
227 line. If the units are not running yet
229 started.</para></listitem>
232 <term><command>try-restart [NAME...]</command></term>
234 <listitem><para>Restart one or more
235 units specified on the command
236 line. If the units are not running yet
238 fail.</para></listitem>
241 <term><command>reload-or-restart [NAME...]</command></term>
242 <term><command>reload-or-try-restart [NAME...]</command></term>
244 <listitem><para>Reload one or more
245 units if they support it. If not
247 instead.</para></listitem>
250 <term><command>isolate [NAME]</command></term>
252 <listitem><para>Start the unit
253 specified on the command line and its
254 dependencies and stop all
255 others.</para></listitem>
258 <term><command>check [NAME...]</command></term>
260 <listitem><para>Check whether any of
261 the specified units is active
262 (i.e. running). Returns 0 if at least
263 one is active, non-zero
265 <option>--quiet</option> is specified
266 this will also print the current unit
267 state to STDOUT.</para></listitem>
270 <term><command>status [NAME...]</command></term>
272 <listitem><para>Show short status
273 information about one or more
274 units. This shows terse runtime
276 units.</para></listitem>
279 <term><command>show [NAME...|JOB...]</command></term>
281 <listitem><para>Show properties of
282 one or more units, jobs or the manager
283 itself. If no argument is specified
284 properties of the manager will be
285 shown. If a unit name is specified
286 properties of the unit is shown,
287 and if a job id is specified
288 properties of the job is
289 shown.</para></listitem>
292 <term><command>load [NAME...]</command></term>
294 <listitem><para>Load one or more units
295 specified on the command line. This
296 will simply load their configuration
297 from disk, but not start them. To
298 start them you need to use the
299 <command>start</command> command which
300 will implicitly load a unit that has
301 not been loaded yet. Note that systemd
302 garbage collects loaded units that are
303 not active or referenced by an active
304 unit. This means that units loaded
305 this way will usually not stay loaded
306 for long. Also note that this command
307 cannot be used to reload unit
308 configuration. Use the
309 <command>daemon-reload</command>
310 command for that. All in all, this
311 command is of little use except for
313 <para>This command should not be
315 <command>daemon-reload</command> or
316 <command>reload</command>
317 commands.</para></listitem>
320 <term><command>list-jobs</command></term>
322 <listitem><para>List jobs that are in progress.</para></listitem>
325 <term><command>cancel [JOB...]</command></term>
327 <listitem><para>Cancel one or more
328 jobs specified on the command line by
330 IDs.</para></listitem>
333 <term><command>clear-jobs</command></term>
335 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
338 <term><command>monitor</command></term>
340 <listitem><para>Monitor unit/job
341 changes. This is mostly useful for
342 debugging purposes and prints a line
343 each time systemd loads or unloads a
344 unit configuration file, or a unit
345 property changes.</para></listitem>
348 <term><command>dump</command></term>
350 <listitem><para>Dump server
351 status. This will output a (usually
352 very long) human readable manager
353 status dump. Its format is subject to
354 change without notice and should not
356 applications.</para></listitem>
359 <term><command>snapshot [NAME]</command></term>
361 <listitem><para>Create a snapshot. If
362 a snapshot name is specified, the new
363 snapshot will be named after it. If
364 none is specified an automatic
365 snapshot name is generated. In either
366 case, the snapshot name used is
367 printed to STDOUT, unless
368 <option>--quiet</option> is
371 <para>A snapshot refers to a saved
372 state of the systemd manager. It is
373 implemented itself as unit that is
374 generated dynamically with this
375 command and has dependencies on all
376 units active at the time. At a later
377 time the user may return to this state
379 <command>isolate</command> command on
380 the snapshot unit.</para></listitem>
382 <para>Snapshots are only useful for
383 saving and restoring which units are
384 running or are stopped, they do not
385 save/restore any other
386 state. Snapshots are dynamic and lost
390 <term><command>delete [NAME...]</command></term>
392 <listitem><para>Remove a snapshot
393 previously created with
394 <command>snapshot</command>.</para></listitem>
397 <term><command>daemon-reload</command></term>
399 <listitem><para>Reload systemd manager
400 configuration. This will reload all
401 unit files and recreate the entire
402 dependency tree. While the daemon is
403 reloaded, all sockets systemd listens
404 on on behalf of user configuration will
405 stay accessible.</para> <para>This
406 command should not be confused with
407 the <command>load</command> or
408 <command>reload</command>
409 commands.</para></listitem>
412 <term><command>daemon-reexec</command></term>
414 <listitem><para>Reexecute the systemd
415 manager. This will serialize the
416 manager state, reexecute the process
417 and deserialize the state again. This
418 command is of little use except for
419 debugging and package
420 upgrades. Sometimes it might be
421 helpful as a heavy-weight
422 <command>daemon-reload</command>. While
423 the daemon is reexecuted all sockets
424 systemd listens on on behalf of user
425 configuration will stay
426 accessible.</para></listitem>
429 <term><command>daemon-exit</command></term>
431 <listitem><para>Ask the systemd
432 manager to quit. This is only
433 supported for session managers
434 (i.e. in conjunction with the
435 <option>--session</option> option) and
436 will fail otherwise.</para></listitem>
439 <term><command>show-environment</command></term>
441 <listitem><para>Dump the systemd
442 manager environment block. The
443 environment block will be dumped in
444 straight-forward form suitable for
445 sourcing into a shell script. This
446 environment block will be passed to
447 all processes the manager
448 spawns.</para></listitem>
451 <term><command>set-environment [NAME=VALUE...]</command></term>
453 <listitem><para>Set one or more
454 systemd manager environment variables,
455 as specified on the command
456 line.</para></listitem>
459 <term><command>unset-environment [NAME...]</command></term>
461 <listitem><para>Unset one or more
462 systemd manager environment
463 variables. If only a variable name is
464 specified it will be removed
465 regardless of its value. If a variable
466 and a value are specified the variable
467 is only removed if it has the
468 specified value.</para></listitem>
472 <term><command>halt</command></term>
474 <listitem><para>Shut down and halt the
475 system. This is mostly equivalent to
476 <command>start halt.target</command>
477 but also prints a wall message to all
478 users.</para></listitem>
481 <term><command>poweroff</command></term>
483 <listitem><para>Shut down and
484 power-off the system. This is mostly
485 equivalent to <command>start
486 poweroff.target</command> but also
487 prints a wall message to all
488 users.</para></listitem>
491 <term><command>reboot</command></term>
493 <listitem><para>Shut down and
494 reboot the system. This is mostly
495 equivalent to <command>start
496 reboot.target</command> but also
497 prints a wall message to all
498 users.</para></listitem>
501 <term><command>default</command></term>
503 <listitem><para>Enter default
504 mode. This is mostly equivalent to
506 default.target</command>.</para></listitem>
509 <term><command>rescue</command></term>
511 <listitem><para>Enter rescue
512 mode. This is mostly equivalent to
514 rescue.target</command> but also
515 prints a wall message to all
516 users.</para></listitem>
519 <term><command>emergency</command></term>
521 <listitem><para>Enter emergency
522 mode. This is mostly equivalent to
524 emergency.target</command> but also
525 prints a wall message to all
526 users.</para></listitem>
533 <title>Exit status</title>
535 <para>On success 0 is returned, a non-zero failure
536 code otherwise.</para>
540 <title>See Also</title>
542 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
543 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
544 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
545 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
546 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>