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>show [NAME...|JOB...]</command></term>
252 <listitem><para>Show information about
253 one or more units, jobs or the manager
254 itself. If no argument is specified
255 information about the manager will be
256 shown. If a unit name is specified
257 information about the unit is shown,
258 and if a job id is specified
259 information about the job is
260 shown.</para></listitem>
263 <term><command>load [NAME...]</command></term>
265 <listitem><para>Load one or more units
266 specified on the command line. This
267 will simply load their configuration
268 from disk, but not start them. To
269 start them you need to use the
270 <command>start</command> command which
271 will implicitly load a unit that has
272 not been loaded yet. Note that systemd
273 garbage collects loaded units that are
274 not active or referenced by an active
275 unit. This means that units loaded
276 this way will usually not stay loaded
277 for long. Also note that this command
278 cannot be used to reload unit
279 configuration. Use the
280 <command>daemon-reload</command>
281 command for that. All in all, this
282 command is of little use except for
284 <para>This command should not be
286 <command>daemon-reload</command> or
287 <command>reload</command>
288 commands.</para></listitem>
291 <term><command>list-jobs</command></term>
293 <listitem><para>List jobs that are in progress.</para></listitem>
296 <term><command>cancel [JOB...]</command></term>
298 <listitem><para>Cancel one or more
299 jobs specified on the command line by
301 IDs.</para></listitem>
304 <term><command>clear-jobs</command></term>
306 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
309 <term><command>monitor</command></term>
311 <listitem><para>Monitor unit/job
312 changes. This is mostly useful for
313 debugging purposes and prints a line
314 each time systemd loads or unloads a
315 unit configuration file, or a unit
316 property changes.</para></listitem>
319 <term><command>dump</command></term>
321 <listitem><para>Dump server
322 status. This will output a (usually
323 very long) human readable manager
324 status dump. Its format is subject to
325 change without notice and should not
327 applications.</para></listitem>
330 <term><command>snapshot [NAME]</command></term>
332 <listitem><para>Create a snapshot. If
333 a snapshot name is specified, the new
334 snapshot will be named after it. If
335 none is specified an automatic
336 snapshot name is generated. In either
337 case, the snapshot name used is
338 printed to STDOUT, unless
339 <option>--quiet</option> is
342 <para>A snapshot refers to a saved
343 state of the systemd manager. It is
344 implemented itself as unit that is
345 generated dynamically with this
346 command and has dependencies on all
347 units active at the time. At a later
348 time the user may return to this state
350 <command>isolate</command> command on
351 the snapshot unit.</para></listitem>
353 <para>Snapshots are only useful for
354 saving and restoring which units are
355 running or are stopped, they do not
356 save/restore any other
357 state. Snapshots are dynamic and lost
361 <term><command>delete [NAME...]</command></term>
363 <listitem><para>Remove a snapshot
364 previously created with
365 <command>snapshot</command>.</para></listitem>
368 <term><command>daemon-reload</command></term>
370 <listitem><para>Reload systemd manager
371 configuration. This will reload all
372 unit files and recreate the entire
373 dependency tree. While the daemon is
374 reloaded, all sockets systemd listens
375 on on behalf of user configuration, will
376 stay accessible.</para> <para>This
377 command should not be confused with
378 the <command>load</command> or
379 <command>reload</command>
380 commands.</para></listitem>
383 <term><command>daemon-reexec</command></term>
385 <listitem><para>Reexecute the systemd
386 manager. This will serialize the
387 manager state, reexecute the process
388 and deserialize the state again. This
389 command is of little use except for
390 debugging and package
391 upgrades. Sometimes it might be
392 helpful as a heavy-weight
393 <command>daemon-reload</command>. While
394 the daemon is reexecuted all sockets
395 systemd listens on on behalf of user
396 configuration will stay
397 accessible.</para></listitem>
400 <term><command>daemon-exit</command></term>
402 <listitem><para>Ask the systemd
403 manager to quit. This is only
404 supported for session managers
405 (i.e. in conjunction with the
406 <option>--session</option> option) and
407 will fail otherwise.</para></listitem>
410 <term><command>show-environment</command></term>
412 <listitem><para>Dump the systemd
413 manager environment block. The
414 environment block will be dumped in
415 straight-forward form suitable for
416 sourcing into a shell script. This
417 environment block will be passed to
418 all processes the manager
419 spawns.</para></listitem>
422 <term><command>set-environment [NAME=VALUE...]</command></term>
424 <listitem><para>Set one or more
425 systemd manager environment variables,
426 as specified on the command
427 line.</para></listitem>
430 <term><command>unset-environment [NAME...]</command></term>
432 <listitem><para>Unset one or more
433 systemd manager environment
434 variables. If only a variable name is
435 specified it will be removed
436 regardless of its value. If a variable
437 and a value are specified the variable
438 is only removed if it has the
439 specified value.</para></listitem>
443 <term><command>halt</command></term>
445 <listitem><para>Shut down and halt the
446 system. This is mostly equivalent to
447 <command>start halt.target</command>
448 but also prints a wall message to all
449 users.</para></listitem>
452 <term><command>poweroff</command></term>
454 <listitem><para>Shut down and
455 power-off the system. This is mostly
456 equivalent to <command>start
457 poweroff.target</command> but also
458 prints a wall message to all
459 users.</para></listitem>
462 <term><command>reboot</command></term>
464 <listitem><para>Shut down and
465 reboot the system. This is mostly
466 equivalent to <command>start
467 reboot.target</command> but also
468 prints a wall message to all
469 users.</para></listitem>
472 <term><command>default</command></term>
474 <listitem><para>Enter default
475 mode. This is mostly equivalent to
477 default.target</command>.</para></listitem>
480 <term><command>rescue</command></term>
482 <listitem><para>Enter rescue
483 mode. This is mostly equivalent to
485 rescue.target</command> but also
486 prints a wall message to all
487 users.</para></listitem>
490 <term><command>emergency</command></term>
492 <listitem><para>Enter emergency
493 mode. This is mostly equivalent to
495 emergency.service</command> but also
496 prints a wall message to all
497 users.</para></listitem>
504 <title>Exit status</title>
506 <para>On success 0 is returned, a non-zero failure
507 code otherwise.</para>
511 <title>See Also</title>
513 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
514 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
515 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
516 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
517 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>