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>--replace</option></term>
121 <listitem><para>If the requested
122 operation conflicts with an existing
123 unfinished operation, replace the
124 existing operation by the requested
125 operation. If this is not specified
126 the requested operation will
127 fail.</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>restart [NAME...]</command></term>
199 <listitem><para>Restart one or more
200 units specified on the command
201 line.</para></listitem>
204 <term><command>reload [NAME...]</command></term>
206 <listitem><para>Asks all services
207 whose units are listed on the command
209 configuration. Note that this will
210 reload the daemon configuration
211 itself, not the unit configuration
212 file of systemd. If you want systemd
213 to reload the configuration file of a
215 <command>daemon-reload</command>
216 command. In other words: for the
217 example case of Apache, this will
219 <filename>httpd.conf</filename> in the
221 <filename>apache.service</filename>
222 systemd unit file. </para> <para>This
223 command should not be confused with
224 the <command>daemon-reload</command>
225 or <command>load</command>
226 commands.</para></listitem>
230 <term><command>isolate [NAME]</command></term>
232 <listitem><para>Start the unit
233 specified on the command line and its
234 dependencies and stop all
235 others.</para></listitem>
238 <term><command>check [NAME...]</command></term>
240 <listitem><para>Check whether any of
241 the specified units is active
242 (i.e. running). Returns 0 if at least
243 one is active, non-zero
245 <option>--quiet</option> is specified
246 this will also print the current unit
247 state to STDOUT.</para></listitem>
250 <term><command>status [NAME...]</command></term>
252 <listitem><para>Show short status
253 information about one or more
254 units. This shows terse runtime
256 units.</para></listitem>
259 <term><command>show [NAME...|JOB...]</command></term>
261 <listitem><para>Show properties of
262 one or more units, jobs or the manager
263 itself. If no argument is specified
264 properties of the manager will be
265 shown. If a unit name is specified
266 properties of the unit is shown,
267 and if a job id is specified
268 properties of the job is
269 shown.</para></listitem>
272 <term><command>load [NAME...]</command></term>
274 <listitem><para>Load one or more units
275 specified on the command line. This
276 will simply load their configuration
277 from disk, but not start them. To
278 start them you need to use the
279 <command>start</command> command which
280 will implicitly load a unit that has
281 not been loaded yet. Note that systemd
282 garbage collects loaded units that are
283 not active or referenced by an active
284 unit. This means that units loaded
285 this way will usually not stay loaded
286 for long. Also note that this command
287 cannot be used to reload unit
288 configuration. Use the
289 <command>daemon-reload</command>
290 command for that. All in all, this
291 command is of little use except for
293 <para>This command should not be
295 <command>daemon-reload</command> or
296 <command>reload</command>
297 commands.</para></listitem>
300 <term><command>list-jobs</command></term>
302 <listitem><para>List jobs that are in progress.</para></listitem>
305 <term><command>cancel [JOB...]</command></term>
307 <listitem><para>Cancel one or more
308 jobs specified on the command line by
310 IDs.</para></listitem>
313 <term><command>clear-jobs</command></term>
315 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
318 <term><command>monitor</command></term>
320 <listitem><para>Monitor unit/job
321 changes. This is mostly useful for
322 debugging purposes and prints a line
323 each time systemd loads or unloads a
324 unit configuration file, or a unit
325 property changes.</para></listitem>
328 <term><command>dump</command></term>
330 <listitem><para>Dump server
331 status. This will output a (usually
332 very long) human readable manager
333 status dump. Its format is subject to
334 change without notice and should not
336 applications.</para></listitem>
339 <term><command>snapshot [NAME]</command></term>
341 <listitem><para>Create a snapshot. If
342 a snapshot name is specified, the new
343 snapshot will be named after it. If
344 none is specified an automatic
345 snapshot name is generated. In either
346 case, the snapshot name used is
347 printed to STDOUT, unless
348 <option>--quiet</option> is
351 <para>A snapshot refers to a saved
352 state of the systemd manager. It is
353 implemented itself as unit that is
354 generated dynamically with this
355 command and has dependencies on all
356 units active at the time. At a later
357 time the user may return to this state
359 <command>isolate</command> command on
360 the snapshot unit.</para></listitem>
362 <para>Snapshots are only useful for
363 saving and restoring which units are
364 running or are stopped, they do not
365 save/restore any other
366 state. Snapshots are dynamic and lost
370 <term><command>delete [NAME...]</command></term>
372 <listitem><para>Remove a snapshot
373 previously created with
374 <command>snapshot</command>.</para></listitem>
377 <term><command>daemon-reload</command></term>
379 <listitem><para>Reload systemd manager
380 configuration. This will reload all
381 unit files and recreate the entire
382 dependency tree. While the daemon is
383 reloaded, all sockets systemd listens
384 on on behalf of user configuration will
385 stay accessible.</para> <para>This
386 command should not be confused with
387 the <command>load</command> or
388 <command>reload</command>
389 commands.</para></listitem>
392 <term><command>daemon-reexec</command></term>
394 <listitem><para>Reexecute the systemd
395 manager. This will serialize the
396 manager state, reexecute the process
397 and deserialize the state again. This
398 command is of little use except for
399 debugging and package
400 upgrades. Sometimes it might be
401 helpful as a heavy-weight
402 <command>daemon-reload</command>. While
403 the daemon is reexecuted all sockets
404 systemd listens on on behalf of user
405 configuration will stay
406 accessible.</para></listitem>
409 <term><command>daemon-exit</command></term>
411 <listitem><para>Ask the systemd
412 manager to quit. This is only
413 supported for session managers
414 (i.e. in conjunction with the
415 <option>--session</option> option) and
416 will fail otherwise.</para></listitem>
419 <term><command>show-environment</command></term>
421 <listitem><para>Dump the systemd
422 manager environment block. The
423 environment block will be dumped in
424 straight-forward form suitable for
425 sourcing into a shell script. This
426 environment block will be passed to
427 all processes the manager
428 spawns.</para></listitem>
431 <term><command>set-environment [NAME=VALUE...]</command></term>
433 <listitem><para>Set one or more
434 systemd manager environment variables,
435 as specified on the command
436 line.</para></listitem>
439 <term><command>unset-environment [NAME...]</command></term>
441 <listitem><para>Unset one or more
442 systemd manager environment
443 variables. If only a variable name is
444 specified it will be removed
445 regardless of its value. If a variable
446 and a value are specified the variable
447 is only removed if it has the
448 specified value.</para></listitem>
452 <term><command>halt</command></term>
454 <listitem><para>Shut down and halt the
455 system. This is mostly equivalent to
456 <command>start halt.target</command>
457 but also prints a wall message to all
458 users.</para></listitem>
461 <term><command>poweroff</command></term>
463 <listitem><para>Shut down and
464 power-off the system. This is mostly
465 equivalent to <command>start
466 poweroff.target</command> but also
467 prints a wall message to all
468 users.</para></listitem>
471 <term><command>reboot</command></term>
473 <listitem><para>Shut down and
474 reboot the system. This is mostly
475 equivalent to <command>start
476 reboot.target</command> but also
477 prints a wall message to all
478 users.</para></listitem>
481 <term><command>default</command></term>
483 <listitem><para>Enter default
484 mode. This is mostly equivalent to
486 default.target</command>.</para></listitem>
489 <term><command>rescue</command></term>
491 <listitem><para>Enter rescue
492 mode. This is mostly equivalent to
494 rescue.target</command> but also
495 prints a wall message to all
496 users.</para></listitem>
499 <term><command>emergency</command></term>
501 <listitem><para>Enter emergency
502 mode. This is mostly equivalent to
504 emergency.service</command> but also
505 prints a wall message to all
506 users.</para></listitem>
513 <title>Exit status</title>
515 <para>On success 0 is returned, a non-zero failure
516 code otherwise.</para>
520 <title>See Also</title>
522 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
523 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
524 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
525 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
526 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>