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>
82 <listitem><para>When listing units,
83 limit display to certain unit
84 types. If not specified units of all
85 types will be shown. The argument
86 should be a unit type name such as
87 <option>service</option>,
88 <option>socket</option> and
89 similar.</para></listitem>
93 <term><option>--all</option></term>
95 <listitem><para>When listing units,
96 show all units, regardless of their
97 state, including inactive
98 units.</para></listitem>
102 <term><option>--replace</option></term>
104 <listitem><para>If the requested
105 operation conflicts with an existing
106 unfinished operation, replace the
107 existing operation by the requested
108 operation. If this is not specified
109 the requested operation will
110 fail.</para></listitem>
114 <term><option>--system</option></term>
116 <listitem><para>Talk to the systemd
117 system manager. (Default)</para></listitem>
121 <term><option>--session</option></term>
123 <listitem><para>Talk to the systemd
124 session manager of the calling user.</para></listitem>
128 <term><option>--block</option></term>
130 <listitem><para>Synchronously wait for
131 the requested operation to
132 finish.</para></listitem>
136 <term><option>--no-wall</option></term>
138 <listitem><para>Don't send wall
140 halt, power-off, reboot.</para></listitem>
144 <para>The following commands are understood:</para>
148 <term><command>list-units</command></term>
150 <listitem><para>List known units.</para></listitem>
153 <term><command>list-jobs</command></term>
155 <listitem><para>List jobs that are in progress.</para></listitem>
158 <term><command>clear-jobs</command></term>
160 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
163 <term><command>load [NAME...]</command></term>
165 <listitem><para>Load one or more units
166 specified on the command line. This
167 will simply load their configuration
168 from disk, but not start them. To
169 start them you need to use the
170 <command>start</command> command which
171 will implicitly load a unit that has
172 not been loaded yet. Note that systemd
173 garbage collects loaded units that are
174 not active or referenced by an active
175 unit. This means that units loaded
176 this way will usually not stay loaded
177 for long. Also note that this command
178 cannot be used to reload unit
179 configuration. Use the
180 <command>daemon-reload</command>
181 command for that. All in all, this
182 command is of little use except for
184 <para>This command should not be
186 <command>daemon-reload</command> or
187 <command>reload</command>
188 commands.</para></listitem>
192 <term><command>cancel [JOB...]</command></term>
194 <listitem><para>Cancel one or more
195 jobs specified on the command line by
197 IDs.</para></listitem>
200 <term><command>start [NAME...]</command></term>
202 <listitem><para>Start one or more
203 units specified on the command
204 line.</para></listitem>
207 <term><command>stop [NAME...]</command></term>
209 <listitem><para>Stop one or more units
210 specified on the command
211 line.</para></listitem>
214 <term><command>restart [NAME...]</command></term>
216 <listitem><para>Restart one or more
217 units specified on the command
218 line.</para></listitem>
221 <term><command>reload [NAME...]</command></term>
223 <listitem><para>Asks all services
224 whose units are listed on the command
226 configuration. Note that this will
227 reload the daemon configuration
228 itself, not the unit configuration
229 file of systemd. If you want systemd
230 to reload the configuration file of a
232 <command>daemon-reload</command>
233 command. In other words: for the
234 example case of Apache, this will
236 <filename>httpd.conf</filename> in the
238 <filename>apache.service</filename>
239 systemd unit file. </para> <para>This
240 command should not be confused with
241 the <command>daemon-reload</command>
242 or <command>load</command>
243 commands.</para></listitem>
247 <term><command>isolate [NAME]</command></term>
249 <listitem><para>Start the unit
250 specified on the command line and its
251 dependencies and stop all
252 others.</para></listitem>
255 <term><command>monitor</command></term>
257 <listitem><para>Monitor unit/job
258 changes. This is mostly useful for
259 debugging purposes and prints a line
260 each time systemd loads or unloads a
261 unit configuration file, or a unit
262 property changes.</para></listitem>
265 <term><command>dump</command></term>
267 <listitem><para>Dump server
268 status. This will output a (usually
269 very long) human readable manager
270 status dump. Its format is subject to
271 change without notice and should not
273 applications.</para></listitem>
276 <term><command>snapshot [NAME]</command></term>
278 <listitem><para>Create a snapshot. If
279 a snapshot name is specified, the new
280 snapshot will be named after it. If
281 none is specified an automatic
282 snapshot name is generated. In either
283 case, the snapshot name used is printed
286 <para>A snapshot refers to a saved
287 state of the systemd manager. It is
288 implemented itself as unit that is
289 generated dynamically with this
290 command and has dependencies on all
291 units active at the time. At a later
292 time the user may return to this state
294 <command>isolate</command> command on
295 the snapshot unit.</para></listitem>
297 <para>Snapshots are only useful for
298 saving and restoring which units are
299 running or are stopped, they do not
300 save/restore any other
301 state. Snapshots are dynamic and lost
305 <term><command>daemon-reload</command></term>
307 <listitem><para>Reload systemd manager
308 configuration. This will reload all
309 unit files and recreate the entire
310 dependency tree. While the daemon is
311 reloaded, all sockets systemd listens
312 on on behalf of user configuration, will
313 stay accessible.</para> <para>This
314 command should not be confused with
315 the <command>load</command> or
316 <command>reload</command>
317 commands.</para></listitem>
320 <term><command>daemon-reexec</command></term>
322 <listitem><para>Reexecute the systemd
323 manager. This will serialize the
324 manager state, reexecute the process
325 and deserialize the state again. This
326 command is of little use except for
327 debugging and package
328 upgrades. Sometimes it might be
329 helpful as a heavy-weight
330 <command>daemon-reload</command>. While
331 the daemon is reexecuted all sockets
332 systemd listens on on behalf of user
333 configuration will stay
334 accessible.</para></listitem>
337 <term><command>daemon-exit</command></term>
339 <listitem><para>Ask the systemd
340 manager to quit. This is only
341 supported for session managers
342 (i.e. in conjunction with the
343 <option>--session</option> option) and
344 will fail otherwise.</para></listitem>
347 <term><command>show-environment</command></term>
349 <listitem><para>Dump the systemd
350 manager environment block. The
351 environment block will be dumped in
352 straight-forward form suitable for
353 sourcing into a shell script. This
354 environment block will be passed to
355 all processes the manager
356 spawns.</para></listitem>
359 <term><command>set-environment [NAME=VALUE...]</command></term>
361 <listitem><para>Set one or more
362 systemd manager environment variables,
363 as specified on the command
364 line.</para></listitem>
367 <term><command>unset-environment [NAME...]</command></term>
369 <listitem><para>Unset one or more
370 systemd manager environment
371 variables. If only a variable name is
372 specified it will be removed
373 regardless of its value. If a variable
374 and a value are specified the variable
375 is only removed if it has the
376 specified value.</para></listitem>
380 <term><command>halt</command></term>
382 <listitem><para>Shut down and halt the
383 system. This is mostly equivalent to
384 <command>start halt.target</command>
385 but also prints a wall message to all
386 users.</para></listitem>
389 <term><command>poweroff</command></term>
391 <listitem><para>Shut down and
392 power-off the system. This is mostly
393 equivalent to <command>start
394 poweroff.target</command> but also
395 prints a wall message to all
396 users.</para></listitem>
399 <term><command>reboot</command></term>
401 <listitem><para>Shut down and
402 reboot the system. This is mostly
403 equivalent to <command>start
404 reboot.target</command> but also
405 prints a wall message to all
406 users.</para></listitem>
409 <term><command>default</command></term>
411 <listitem><para>Enter default
412 mode. This is mostly equivalent to
414 default.target</command>.</para></listitem>
417 <term><command>rescue</command></term>
419 <listitem><para>Enter rescue
420 mode. This is mostly equivalent to
422 rescue.target</command> but also
423 prints a wall message to all
424 users.</para></listitem>
427 <term><command>emergency</command></term>
429 <listitem><para>Enter emergency
430 mode. This is mostly equivalent to
432 emergency.service</command> but also
433 prints a wall message to all
434 users.</para></listitem>
441 <title>Exit status</title>
443 <para>On success 0 is returned, a non-zero failure
444 code otherwise.</para>
448 <title>See Also</title>
450 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
451 <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
452 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
453 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
454 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>