chiark / gitweb /
man: finish systemd.unit.5
[elogind.git] / man / systemctl.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd-install">
25
26         <refentryinfo>
27                 <title>systemctl</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>systemctl</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemctl</refname>
47                 <refpurpose>Control the systemd system and session manager</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>systemctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
53                 </cmdsynopsis>
54         </refsynopsisdiv>
55
56         <refsect1>
57                 <title>Description</title>
58
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>
63         </refsect1>
64
65         <refsect1>
66                 <title>Options</title>
67
68                 <para>The following options are understood:</para>
69
70                 <variablelist>
71                         <varlistentry>
72                                 <term><option>--help</option></term>
73                                 <term><option>--h</option></term>
74
75                                 <listitem><para>Prints a short help
76                                 text and exits.</para></listitem>
77                         </varlistentry>
78
79                         <varlistentry>
80                                 <term><option>--type=</option></term>
81
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>
90                         </varlistentry>
91
92                         <varlistentry>
93                                 <term><option>--all</option></term>
94
95                                 <listitem><para>When listing units,
96                                 show all units, regardless of their
97                                 state, including inactive
98                                 units.</para></listitem>
99                         </varlistentry>
100
101                         <varlistentry>
102                                 <term><option>--replace</option></term>
103
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>
111                         </varlistentry>
112
113                         <varlistentry>
114                                 <term><option>--system</option></term>
115
116                                 <listitem><para>Talk to the systemd
117                                 system manager. (Default)</para></listitem>
118                         </varlistentry>
119
120                         <varlistentry>
121                                 <term><option>--session</option></term>
122
123                                 <listitem><para>Talk to the systemd
124                                 session manager of the calling user.</para></listitem>
125                         </varlistentry>
126
127                         <varlistentry>
128                                 <term><option>--block</option></term>
129
130                                 <listitem><para>Synchronously wait for
131                                 the requested operation to
132                                 finish.</para></listitem>
133                         </varlistentry>
134
135                         <varlistentry>
136                                 <term><option>--no-wall</option></term>
137
138                                 <listitem><para>Don't send wall
139                                 message before
140                                 halt, power-off, reboot.</para></listitem>
141                         </varlistentry>
142                 </variablelist>
143
144                 <para>The following commands are understood:</para>
145
146                 <variablelist>
147                         <varlistentry>
148                                 <term><command>list-units</command></term>
149
150                                 <listitem><para>List known units.</para></listitem>
151                         </varlistentry>
152                         <varlistentry>
153                                 <term><command>list-jobs</command></term>
154
155                                 <listitem><para>List jobs that are in progress.</para></listitem>
156                         </varlistentry>
157                         <varlistentry>
158                                 <term><command>clear-jobs</command></term>
159
160                                 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
161                         </varlistentry>
162                         <varlistentry>
163                                 <term><command>load [NAME...]</command></term>
164
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
183                                 debugging.</para>
184                                 <para>This command should not be
185                                 confused with the
186                                 <command>daemon-reload</command> or
187                                 <command>reload</command>
188                                 commands.</para></listitem>
189                         </varlistentry>
190
191                         <varlistentry>
192                                 <term><command>cancel [JOB...]</command></term>
193
194                                 <listitem><para>Cancel one or more
195                                 jobs specified on the command line by
196                                 their numeric job
197                                 IDs.</para></listitem>
198                         </varlistentry>
199                         <varlistentry>
200                                 <term><command>start [NAME...]</command></term>
201
202                                 <listitem><para>Start one or more
203                                 units specified on the command
204                                 line.</para></listitem>
205                         </varlistentry>
206                         <varlistentry>
207                                 <term><command>stop [NAME...]</command></term>
208
209                                 <listitem><para>Stop one or more units
210                                 specified on the command
211                                 line.</para></listitem>
212                         </varlistentry>
213                         <varlistentry>
214                                 <term><command>restart [NAME...]</command></term>
215
216                                 <listitem><para>Restart one or more
217                                 units specified on the command
218                                 line.</para></listitem>
219                         </varlistentry>
220                         <varlistentry>
221                                 <term><command>reload [NAME...]</command></term>
222
223                                 <listitem><para>Asks all services
224                                 whose units are listed on the command
225                                 line to reload their
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
231                                 unit use the
232                                 <command>daemon-reload</command>
233                                 command. In other words: for the
234                                 example case of Apache, this will
235                                 reload Apache's
236                                 <filename>httpd.conf</filename> in the
237                                 web server, not 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>
244
245                         </varlistentry>
246                         <varlistentry>
247                                 <term><command>isolate [NAME]</command></term>
248
249                                 <listitem><para>Start the unit
250                                 specified on the command line and its
251                                 dependencies and stop all
252                                 others.</para></listitem>
253                         </varlistentry>
254                         <varlistentry>
255                                 <term><command>monitor</command></term>
256
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>
263                         </varlistentry>
264                         <varlistentry>
265                                 <term><command>dump</command></term>
266
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
272                                 be parsed by
273                                 applications.</para></listitem>
274                         </varlistentry>
275                         <varlistentry>
276                                 <term><command>snapshot [NAME]</command></term>
277
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
284                                 to STDOUT.</para>
285
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
293                                 by using the
294                                 <command>isolate</command> command on
295                                 the snapshot unit.</para></listitem>
296
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
302                                 on reboot.</para>
303                         </varlistentry>
304                         <varlistentry>
305                                 <term><command>daemon-reload</command></term>
306
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>
318                         </varlistentry>
319                         <varlistentry>
320                                 <term><command>daemon-reexec</command></term>
321
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>
335                         </varlistentry>
336                         <varlistentry>
337                                 <term><command>daemon-exit</command></term>
338
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>
345                         </varlistentry>
346                         <varlistentry>
347                                 <term><command>show-environment</command></term>
348
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>
357                         </varlistentry>
358                         <varlistentry>
359                                 <term><command>set-environment [NAME=VALUE...]</command></term>
360
361                                 <listitem><para>Set one or more
362                                 systemd manager environment variables,
363                                 as specified on the command
364                                 line.</para></listitem>
365                         </varlistentry>
366                         <varlistentry>
367                                 <term><command>unset-environment [NAME...]</command></term>
368
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>
377                         </varlistentry>
378
379                         <varlistentry>
380                                 <term><command>halt</command></term>
381
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>
387                         </varlistentry>
388                         <varlistentry>
389                                 <term><command>poweroff</command></term>
390
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>
397                         </varlistentry>
398                         <varlistentry>
399                                 <term><command>reboot</command></term>
400
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>
407                         </varlistentry>
408                         <varlistentry>
409                                 <term><command>default</command></term>
410
411                                 <listitem><para>Enter default
412                                 mode. This is mostly equivalent to
413                                 <command>start
414                                 default.target</command>.</para></listitem>
415                         </varlistentry>
416                         <varlistentry>
417                                 <term><command>rescue</command></term>
418
419                                 <listitem><para>Enter rescue
420                                 mode. This is mostly equivalent to
421                                 <command>isolate
422                                 rescue.target</command> but also
423                                 prints a wall message to all
424                                 users.</para></listitem>
425                         </varlistentry>
426                         <varlistentry>
427                                 <term><command>emergency</command></term>
428
429                                 <listitem><para>Enter emergency
430                                 mode. This is mostly equivalent to
431                                 <command>isolate
432                                 emergency.service</command> but also
433                                 prints a wall message to all
434                                 users.</para></listitem>
435                         </varlistentry>
436                 </variablelist>
437
438         </refsect1>
439
440         <refsect1>
441                 <title>Exit status</title>
442
443                 <para>On success 0 is returned, a non-zero failure
444                 code otherwise.</para>
445         </refsect1>
446
447         <refsect1>
448                 <title>See Also</title>
449                 <para>
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>
455                 </para>
456         </refsect1>
457
458 </refentry>