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>--all</option></term>
95 <term><option>-a</option></term>
97 <listitem><para>When listing units,
98 show all units, regardless of their
99 state, including inactive
100 units.</para></listitem>
104 <term><option>--replace</option></term>
106 <listitem><para>If the requested
107 operation conflicts with an existing
108 unfinished operation, replace the
109 existing operation by the requested
110 operation. If this is not specified
111 the requested operation will
112 fail.</para></listitem>
116 <term><option>--system</option></term>
118 <listitem><para>Talk to the systemd
119 system manager. (Default)</para></listitem>
123 <term><option>--session</option></term>
125 <listitem><para>Talk to the systemd
126 session manager of the calling user.</para></listitem>
130 <term><option>--no-block</option></term>
132 <listitem><para>Do not synchronously wait for
133 the requested operation to finish. If this is
134 not specified the job will be verified,
135 enqueued and <command>systemctl</command> will
136 wait until it is completed. By passing this
137 argument it is only verified and
138 enqueued.</para></listitem> </varlistentry>
141 <term><option>--quiet</option></term>
142 <term><option>-q</option></term>
144 <listitem><para>Suppress output to
145 STDOUT for <command>snapshot</command>
147 <command>check</command>.</para></listitem>
151 <term><option>--no-wall</option></term>
153 <listitem><para>Don't send wall
155 halt, power-off, reboot.</para></listitem>
159 <para>The following commands are understood:</para>
163 <term><command>list-units</command></term>
165 <listitem><para>List known units.</para></listitem>
168 <term><command>list-jobs</command></term>
170 <listitem><para>List jobs that are in progress.</para></listitem>
173 <term><command>clear-jobs</command></term>
175 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
178 <term><command>load [NAME...]</command></term>
180 <listitem><para>Load one or more units
181 specified on the command line. This
182 will simply load their configuration
183 from disk, but not start them. To
184 start them you need to use the
185 <command>start</command> command which
186 will implicitly load a unit that has
187 not been loaded yet. Note that systemd
188 garbage collects loaded units that are
189 not active or referenced by an active
190 unit. This means that units loaded
191 this way will usually not stay loaded
192 for long. Also note that this command
193 cannot be used to reload unit
194 configuration. Use the
195 <command>daemon-reload</command>
196 command for that. All in all, this
197 command is of little use except for
199 <para>This command should not be
201 <command>daemon-reload</command> or
202 <command>reload</command>
203 commands.</para></listitem>
207 <term><command>cancel [JOB...]</command></term>
209 <listitem><para>Cancel one or more
210 jobs specified on the command line by
212 IDs.</para></listitem>
215 <term><command>start [NAME...]</command></term>
217 <listitem><para>Start one or more
218 units specified on the command
219 line.</para></listitem>
222 <term><command>stop [NAME...]</command></term>
224 <listitem><para>Stop one or more units
225 specified on the command
226 line.</para></listitem>
229 <term><command>restart [NAME...]</command></term>
231 <listitem><para>Restart one or more
232 units specified on the command
233 line.</para></listitem>
236 <term><command>reload [NAME...]</command></term>
238 <listitem><para>Asks all services
239 whose units are listed on the command
241 configuration. Note that this will
242 reload the daemon configuration
243 itself, not the unit configuration
244 file of systemd. If you want systemd
245 to reload the configuration file of a
247 <command>daemon-reload</command>
248 command. In other words: for the
249 example case of Apache, this will
251 <filename>httpd.conf</filename> in the
253 <filename>apache.service</filename>
254 systemd unit file. </para> <para>This
255 command should not be confused with
256 the <command>daemon-reload</command>
257 or <command>load</command>
258 commands.</para></listitem>
262 <term><command>isolate [NAME]</command></term>
264 <listitem><para>Start the unit
265 specified on the command line and its
266 dependencies and stop all
267 others.</para></listitem>
270 <term><command>check [NAME...]</command></term>
272 <listitem><para>Check whether any of
273 the specified units is active
274 (i.e. running). Returns 0 if at least
275 one is active, non-zero
277 <option>--quiet</option> is specified
278 this will also print the current unit
279 state to STDOUT.</para></listitem>
282 <term><command>monitor</command></term>
284 <listitem><para>Monitor unit/job
285 changes. This is mostly useful for
286 debugging purposes and prints a line
287 each time systemd loads or unloads a
288 unit configuration file, or a unit
289 property changes.</para></listitem>
292 <term><command>dump</command></term>
294 <listitem><para>Dump server
295 status. This will output a (usually
296 very long) human readable manager
297 status dump. Its format is subject to
298 change without notice and should not
300 applications.</para></listitem>
303 <term><command>snapshot [NAME]</command></term>
305 <listitem><para>Create a snapshot. If
306 a snapshot name is specified, the new
307 snapshot will be named after it. If
308 none is specified an automatic
309 snapshot name is generated. In either
310 case, the snapshot name used is
311 printed to STDOUT, unless
312 <option>--quiet</option> is
315 <para>A snapshot refers to a saved
316 state of the systemd manager. It is
317 implemented itself as unit that is
318 generated dynamically with this
319 command and has dependencies on all
320 units active at the time. At a later
321 time the user may return to this state
323 <command>isolate</command> command on
324 the snapshot unit.</para></listitem>
326 <para>Snapshots are only useful for
327 saving and restoring which units are
328 running or are stopped, they do not
329 save/restore any other
330 state. Snapshots are dynamic and lost
334 <term><command>delete [NAME...]</command></term>
336 <listitem><para>Remove a snapshot
337 previously created with
338 <command>snapshot</command>.</para></listitem>
341 <term><command>daemon-reload</command></term>
343 <listitem><para>Reload systemd manager
344 configuration. This will reload all
345 unit files and recreate the entire
346 dependency tree. While the daemon is
347 reloaded, all sockets systemd listens
348 on on behalf of user configuration, will
349 stay accessible.</para> <para>This
350 command should not be confused with
351 the <command>load</command> or
352 <command>reload</command>
353 commands.</para></listitem>
356 <term><command>daemon-reexec</command></term>
358 <listitem><para>Reexecute the systemd
359 manager. This will serialize the
360 manager state, reexecute the process
361 and deserialize the state again. This
362 command is of little use except for
363 debugging and package
364 upgrades. Sometimes it might be
365 helpful as a heavy-weight
366 <command>daemon-reload</command>. While
367 the daemon is reexecuted all sockets
368 systemd listens on on behalf of user
369 configuration will stay
370 accessible.</para></listitem>
373 <term><command>daemon-exit</command></term>
375 <listitem><para>Ask the systemd
376 manager to quit. This is only
377 supported for session managers
378 (i.e. in conjunction with the
379 <option>--session</option> option) and
380 will fail otherwise.</para></listitem>
383 <term><command>show-environment</command></term>
385 <listitem><para>Dump the systemd
386 manager environment block. The
387 environment block will be dumped in
388 straight-forward form suitable for
389 sourcing into a shell script. This
390 environment block will be passed to
391 all processes the manager
392 spawns.</para></listitem>
395 <term><command>set-environment [NAME=VALUE...]</command></term>
397 <listitem><para>Set one or more
398 systemd manager environment variables,
399 as specified on the command
400 line.</para></listitem>
403 <term><command>unset-environment [NAME...]</command></term>
405 <listitem><para>Unset one or more
406 systemd manager environment
407 variables. If only a variable name is
408 specified it will be removed
409 regardless of its value. If a variable
410 and a value are specified the variable
411 is only removed if it has the
412 specified value.</para></listitem>
416 <term><command>halt</command></term>
418 <listitem><para>Shut down and halt the
419 system. This is mostly equivalent to
420 <command>start halt.target</command>
421 but also prints a wall message to all
422 users.</para></listitem>
425 <term><command>poweroff</command></term>
427 <listitem><para>Shut down and
428 power-off the system. This is mostly
429 equivalent to <command>start
430 poweroff.target</command> but also
431 prints a wall message to all
432 users.</para></listitem>
435 <term><command>reboot</command></term>
437 <listitem><para>Shut down and
438 reboot the system. This is mostly
439 equivalent to <command>start
440 reboot.target</command> but also
441 prints a wall message to all
442 users.</para></listitem>
445 <term><command>default</command></term>
447 <listitem><para>Enter default
448 mode. This is mostly equivalent to
450 default.target</command>.</para></listitem>
453 <term><command>rescue</command></term>
455 <listitem><para>Enter rescue
456 mode. This is mostly equivalent to
458 rescue.target</command> but also
459 prints a wall message to all
460 users.</para></listitem>
463 <term><command>emergency</command></term>
465 <listitem><para>Enter emergency
466 mode. This is mostly equivalent to
468 emergency.service</command> but also
469 prints a wall message to all
470 users.</para></listitem>
477 <title>Exit status</title>
479 <para>On success 0 is returned, a non-zero failure
480 code otherwise.</para>
484 <title>See Also</title>
486 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
487 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
488 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
489 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
490 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>