chiark / gitweb /
unit: trim cgroups when going down
[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                                 <term><option>-t</option></term>
82
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>
91                         </varlistentry>
92
93                         <varlistentry>
94                                 <term><option>--property=</option></term>
95                                 <term><option>-p</option></term>
96
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>
104                         </varlistentry>
105
106                         <varlistentry>
107                                 <term><option>--all</option></term>
108                                 <term><option>-a</option></term>
109
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>
116                         </varlistentry>
117
118                         <varlistentry>
119                                 <term><option>--replace</option></term>
120
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>
128                         </varlistentry>
129
130                         <varlistentry>
131                                 <term><option>--system</option></term>
132
133                                 <listitem><para>Talk to the systemd
134                                 system manager. (Default)</para></listitem>
135                         </varlistentry>
136
137                         <varlistentry>
138                                 <term><option>--session</option></term>
139
140                                 <listitem><para>Talk to the systemd
141                                 session manager of the calling user.</para></listitem>
142                         </varlistentry>
143
144                         <varlistentry>
145                                 <term><option>--no-block</option></term>
146
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>
154
155                         <varlistentry>
156                                 <term><option>--quiet</option></term>
157                                 <term><option>-q</option></term>
158
159                                 <listitem><para>Suppress output to
160                                 STDOUT for <command>snapshot</command>
161                                 and
162                                 <command>check</command>.</para></listitem>
163                         </varlistentry>
164
165                         <varlistentry>
166                                 <term><option>--no-wall</option></term>
167
168                                 <listitem><para>Don't send wall
169                                 message before
170                                 halt, power-off, reboot.</para></listitem>
171                         </varlistentry>
172                 </variablelist>
173
174                 <para>The following commands are understood:</para>
175
176                 <variablelist>
177                         <varlistentry>
178                                 <term><command>list-units</command></term>
179
180                                 <listitem><para>List known units.</para></listitem>
181                         </varlistentry>
182                         <varlistentry>
183                                 <term><command>start [NAME...]</command></term>
184
185                                 <listitem><para>Start one or more
186                                 units specified on the command
187                                 line.</para></listitem>
188                         </varlistentry>
189                         <varlistentry>
190                                 <term><command>stop [NAME...]</command></term>
191
192                                 <listitem><para>Stop one or more units
193                                 specified on the command
194                                 line.</para></listitem>
195                         </varlistentry>
196                         <varlistentry>
197                                 <term><command>restart [NAME...]</command></term>
198
199                                 <listitem><para>Restart one or more
200                                 units specified on the command
201                                 line.</para></listitem>
202                         </varlistentry>
203                         <varlistentry>
204                                 <term><command>reload [NAME...]</command></term>
205
206                                 <listitem><para>Asks all services
207                                 whose units are listed on the command
208                                 line to reload their
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
214                                 unit use the
215                                 <command>daemon-reload</command>
216                                 command. In other words: for the
217                                 example case of Apache, this will
218                                 reload Apache's
219                                 <filename>httpd.conf</filename> in the
220                                 web server, not 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>
227
228                         </varlistentry>
229                         <varlistentry>
230                                 <term><command>isolate [NAME]</command></term>
231
232                                 <listitem><para>Start the unit
233                                 specified on the command line and its
234                                 dependencies and stop all
235                                 others.</para></listitem>
236                         </varlistentry>
237                         <varlistentry>
238                                 <term><command>check [NAME...]</command></term>
239
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
244                                 otherwise. Unless
245                                 <option>--quiet</option> is specified
246                                 this will also print the current unit
247                                 state to STDOUT.</para></listitem>
248                         </varlistentry>
249                         <varlistentry>
250                                 <term><command>status [NAME...]</command></term>
251
252                                 <listitem><para>Show short status
253                                 information about one or more
254                                 units. This shows terse runtime
255                                 information about
256                                 units.</para></listitem>
257                         </varlistentry>
258                         <varlistentry>
259                                 <term><command>show [NAME...|JOB...]</command></term>
260
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>
270                         </varlistentry>
271                         <varlistentry>
272                                 <term><command>load [NAME...]</command></term>
273
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
292                                 debugging.</para>
293                                 <para>This command should not be
294                                 confused with the
295                                 <command>daemon-reload</command> or
296                                 <command>reload</command>
297                                 commands.</para></listitem>
298                         </varlistentry>
299                         <varlistentry>
300                                 <term><command>list-jobs</command></term>
301
302                                 <listitem><para>List jobs that are in progress.</para></listitem>
303                         </varlistentry>
304                         <varlistentry>
305                                 <term><command>cancel [JOB...]</command></term>
306
307                                 <listitem><para>Cancel one or more
308                                 jobs specified on the command line by
309                                 their numeric job
310                                 IDs.</para></listitem>
311                         </varlistentry>
312                         <varlistentry>
313                                 <term><command>clear-jobs</command></term>
314
315                                 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
316                         </varlistentry>
317                         <varlistentry>
318                                 <term><command>monitor</command></term>
319
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>
326                         </varlistentry>
327                         <varlistentry>
328                                 <term><command>dump</command></term>
329
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
335                                 be parsed by
336                                 applications.</para></listitem>
337                         </varlistentry>
338                         <varlistentry>
339                                 <term><command>snapshot [NAME]</command></term>
340
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
349                                 specified.</para>
350
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
358                                 by using the
359                                 <command>isolate</command> command on
360                                 the snapshot unit.</para></listitem>
361
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
367                                 on reboot.</para>
368                         </varlistentry>
369                         <varlistentry>
370                                 <term><command>delete [NAME...]</command></term>
371
372                                 <listitem><para>Remove a snapshot
373                                 previously created with
374                                 <command>snapshot</command>.</para></listitem>
375                         </varlistentry>
376                         <varlistentry>
377                                 <term><command>daemon-reload</command></term>
378
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>
390                         </varlistentry>
391                         <varlistentry>
392                                 <term><command>daemon-reexec</command></term>
393
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>
407                         </varlistentry>
408                         <varlistentry>
409                                 <term><command>daemon-exit</command></term>
410
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>
417                         </varlistentry>
418                         <varlistentry>
419                                 <term><command>show-environment</command></term>
420
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>
429                         </varlistentry>
430                         <varlistentry>
431                                 <term><command>set-environment [NAME=VALUE...]</command></term>
432
433                                 <listitem><para>Set one or more
434                                 systemd manager environment variables,
435                                 as specified on the command
436                                 line.</para></listitem>
437                         </varlistentry>
438                         <varlistentry>
439                                 <term><command>unset-environment [NAME...]</command></term>
440
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>
449                         </varlistentry>
450
451                         <varlistentry>
452                                 <term><command>halt</command></term>
453
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>
459                         </varlistentry>
460                         <varlistentry>
461                                 <term><command>poweroff</command></term>
462
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>
469                         </varlistentry>
470                         <varlistentry>
471                                 <term><command>reboot</command></term>
472
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>
479                         </varlistentry>
480                         <varlistentry>
481                                 <term><command>default</command></term>
482
483                                 <listitem><para>Enter default
484                                 mode. This is mostly equivalent to
485                                 <command>start
486                                 default.target</command>.</para></listitem>
487                         </varlistentry>
488                         <varlistentry>
489                                 <term><command>rescue</command></term>
490
491                                 <listitem><para>Enter rescue
492                                 mode. This is mostly equivalent to
493                                 <command>isolate
494                                 rescue.target</command> but also
495                                 prints a wall message to all
496                                 users.</para></listitem>
497                         </varlistentry>
498                         <varlistentry>
499                                 <term><command>emergency</command></term>
500
501                                 <listitem><para>Enter emergency
502                                 mode. This is mostly equivalent to
503                                 <command>isolate
504                                 emergency.service</command> but also
505                                 prints a wall message to all
506                                 users.</para></listitem>
507                         </varlistentry>
508                 </variablelist>
509
510         </refsect1>
511
512         <refsect1>
513                 <title>Exit status</title>
514
515                 <para>On success 0 is returned, a non-zero failure
516                 code otherwise.</para>
517         </refsect1>
518
519         <refsect1>
520                 <title>See Also</title>
521                 <para>
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>
527                 </para>
528         </refsect1>
529
530 </refentry>