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 no synchronously
133 wait for the requested operation to
134 finish. If this is not specified the
135 job will be verified, enqueued and
136 wait until it is complete. By passing
137 this argument it is only verified and
138 enqueued.</para></listitem>
142 <term><option>--quiet</option></term>
143 <term><option>-q</option></term>
145 <listitem><para>Suppress output to
146 STDOUT for <command>snapshot</command>
148 <command>check</command>.</para></listitem>
152 <term><option>--no-wall</option></term>
154 <listitem><para>Don't send wall
156 halt, power-off, reboot.</para></listitem>
160 <para>The following commands are understood:</para>
164 <term><command>list-units</command></term>
166 <listitem><para>List known units.</para></listitem>
169 <term><command>list-jobs</command></term>
171 <listitem><para>List jobs that are in progress.</para></listitem>
174 <term><command>clear-jobs</command></term>
176 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
179 <term><command>load [NAME...]</command></term>
181 <listitem><para>Load one or more units
182 specified on the command line. This
183 will simply load their configuration
184 from disk, but not start them. To
185 start them you need to use the
186 <command>start</command> command which
187 will implicitly load a unit that has
188 not been loaded yet. Note that systemd
189 garbage collects loaded units that are
190 not active or referenced by an active
191 unit. This means that units loaded
192 this way will usually not stay loaded
193 for long. Also note that this command
194 cannot be used to reload unit
195 configuration. Use the
196 <command>daemon-reload</command>
197 command for that. All in all, this
198 command is of little use except for
200 <para>This command should not be
202 <command>daemon-reload</command> or
203 <command>reload</command>
204 commands.</para></listitem>
208 <term><command>cancel [JOB...]</command></term>
210 <listitem><para>Cancel one or more
211 jobs specified on the command line by
213 IDs.</para></listitem>
216 <term><command>start [NAME...]</command></term>
218 <listitem><para>Start one or more
219 units specified on the command
220 line.</para></listitem>
223 <term><command>stop [NAME...]</command></term>
225 <listitem><para>Stop one or more units
226 specified on the command
227 line.</para></listitem>
230 <term><command>restart [NAME...]</command></term>
232 <listitem><para>Restart one or more
233 units specified on the command
234 line.</para></listitem>
237 <term><command>reload [NAME...]</command></term>
239 <listitem><para>Asks all services
240 whose units are listed on the command
242 configuration. Note that this will
243 reload the daemon configuration
244 itself, not the unit configuration
245 file of systemd. If you want systemd
246 to reload the configuration file of a
248 <command>daemon-reload</command>
249 command. In other words: for the
250 example case of Apache, this will
252 <filename>httpd.conf</filename> in the
254 <filename>apache.service</filename>
255 systemd unit file. </para> <para>This
256 command should not be confused with
257 the <command>daemon-reload</command>
258 or <command>load</command>
259 commands.</para></listitem>
263 <term><command>isolate [NAME]</command></term>
265 <listitem><para>Start the unit
266 specified on the command line and its
267 dependencies and stop all
268 others.</para></listitem>
271 <term><command>check [NAME...]</command></term>
273 <listitem><para>Check whether any of
274 the specified units is active
275 (i.e. running). Returns 0 if at least
276 one is active, non-zero
278 <option>--quiet</option> is specified
279 this will also print the current unit
280 state to STDOUT.</para></listitem>
283 <term><command>monitor</command></term>
285 <listitem><para>Monitor unit/job
286 changes. This is mostly useful for
287 debugging purposes and prints a line
288 each time systemd loads or unloads a
289 unit configuration file, or a unit
290 property changes.</para></listitem>
293 <term><command>dump</command></term>
295 <listitem><para>Dump server
296 status. This will output a (usually
297 very long) human readable manager
298 status dump. Its format is subject to
299 change without notice and should not
301 applications.</para></listitem>
304 <term><command>snapshot [NAME]</command></term>
306 <listitem><para>Create a snapshot. If
307 a snapshot name is specified, the new
308 snapshot will be named after it. If
309 none is specified an automatic
310 snapshot name is generated. In either
311 case, the snapshot name used is
312 printed to STDOUT, unless
313 <option>--quiet</option> is
316 <para>A snapshot refers to a saved
317 state of the systemd manager. It is
318 implemented itself as unit that is
319 generated dynamically with this
320 command and has dependencies on all
321 units active at the time. At a later
322 time the user may return to this state
324 <command>isolate</command> command on
325 the snapshot unit.</para></listitem>
327 <para>Snapshots are only useful for
328 saving and restoring which units are
329 running or are stopped, they do not
330 save/restore any other
331 state. Snapshots are dynamic and lost
335 <term><command>daemon-reload</command></term>
337 <listitem><para>Reload systemd manager
338 configuration. This will reload all
339 unit files and recreate the entire
340 dependency tree. While the daemon is
341 reloaded, all sockets systemd listens
342 on on behalf of user configuration, will
343 stay accessible.</para> <para>This
344 command should not be confused with
345 the <command>load</command> or
346 <command>reload</command>
347 commands.</para></listitem>
350 <term><command>daemon-reexec</command></term>
352 <listitem><para>Reexecute the systemd
353 manager. This will serialize the
354 manager state, reexecute the process
355 and deserialize the state again. This
356 command is of little use except for
357 debugging and package
358 upgrades. Sometimes it might be
359 helpful as a heavy-weight
360 <command>daemon-reload</command>. While
361 the daemon is reexecuted all sockets
362 systemd listens on on behalf of user
363 configuration will stay
364 accessible.</para></listitem>
367 <term><command>daemon-exit</command></term>
369 <listitem><para>Ask the systemd
370 manager to quit. This is only
371 supported for session managers
372 (i.e. in conjunction with the
373 <option>--session</option> option) and
374 will fail otherwise.</para></listitem>
377 <term><command>show-environment</command></term>
379 <listitem><para>Dump the systemd
380 manager environment block. The
381 environment block will be dumped in
382 straight-forward form suitable for
383 sourcing into a shell script. This
384 environment block will be passed to
385 all processes the manager
386 spawns.</para></listitem>
389 <term><command>set-environment [NAME=VALUE...]</command></term>
391 <listitem><para>Set one or more
392 systemd manager environment variables,
393 as specified on the command
394 line.</para></listitem>
397 <term><command>unset-environment [NAME...]</command></term>
399 <listitem><para>Unset one or more
400 systemd manager environment
401 variables. If only a variable name is
402 specified it will be removed
403 regardless of its value. If a variable
404 and a value are specified the variable
405 is only removed if it has the
406 specified value.</para></listitem>
410 <term><command>halt</command></term>
412 <listitem><para>Shut down and halt the
413 system. This is mostly equivalent to
414 <command>start halt.target</command>
415 but also prints a wall message to all
416 users.</para></listitem>
419 <term><command>poweroff</command></term>
421 <listitem><para>Shut down and
422 power-off the system. This is mostly
423 equivalent to <command>start
424 poweroff.target</command> but also
425 prints a wall message to all
426 users.</para></listitem>
429 <term><command>reboot</command></term>
431 <listitem><para>Shut down and
432 reboot the system. This is mostly
433 equivalent to <command>start
434 reboot.target</command> but also
435 prints a wall message to all
436 users.</para></listitem>
439 <term><command>default</command></term>
441 <listitem><para>Enter default
442 mode. This is mostly equivalent to
444 default.target</command>.</para></listitem>
447 <term><command>rescue</command></term>
449 <listitem><para>Enter rescue
450 mode. This is mostly equivalent to
452 rescue.target</command> but also
453 prints a wall message to all
454 users.</para></listitem>
457 <term><command>emergency</command></term>
459 <listitem><para>Enter emergency
460 mode. This is mostly equivalent to
462 emergency.service</command> but also
463 prints a wall message to all
464 users.</para></listitem>
471 <title>Exit status</title>
473 <para>On success 0 is returned, a non-zero failure
474 code otherwise.</para>
478 <title>See Also</title>
480 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
481 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
482 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
483 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
484 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>