chiark / gitweb /
man: improve readability of "_TRANSPORT=" section in systemd.journal-fields(7)
[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 Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemctl">
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 service manager</refpurpose>
48   </refnamediv>
49
50   <refsynopsisdiv>
51     <cmdsynopsis>
52       <command>systemctl</command>
53       <arg choice="opt" rep="repeat">OPTIONS</arg>
54       <arg choice="plain">COMMAND</arg>
55       <arg choice="opt" rep="repeat">NAME</arg>
56     </cmdsynopsis>
57   </refsynopsisdiv>
58
59   <refsect1>
60     <title>Description</title>
61
62     <para><command>systemctl</command> may be used to
63     introspect and control the state of the
64     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
65     system and service manager.</para>
66   </refsect1>
67
68   <refsect1>
69     <title>Options</title>
70
71     <para>The following options are understood:</para>
72
73     <variablelist>
74       <varlistentry>
75         <term><option>-h</option></term>
76         <term><option>--help</option></term>
77
78         <listitem><para>Prints a short help
79         text and exits.</para></listitem>
80       </varlistentry>
81
82       <varlistentry>
83         <term><option>--version</option></term>
84
85         <listitem>
86           <para>Prints a short version string and exits.</para>
87         </listitem>
88       </varlistentry>
89
90       <varlistentry>
91         <term><option>-t</option></term>
92         <term><option>--type=</option></term>
93
94         <listitem>
95           <para>The argument should be a comma separated list of unit
96           types such as <option>service</option> and
97           <option>socket</option>, or unit load states such as
98           <option>loaded</option> and <option>masked</option>
99           (types and states can be mixed).</para>
100
101           <para>If one of the arguments is a unit type, when listing
102           units, limit display to certain unit types. Otherwise units
103           of all types will be shown.</para>
104
105           <para>If one of the arguments is a unit load state, when
106           listing units, limit display to certain unit
107           types. Otherwise units of in all load states will be
108           shown.</para>
109
110           <para>As a special case, if one of the arguments is
111           <option>help</option>, a list of allowed values will be
112           printed and the program will exit.</para>
113         </listitem>
114       </varlistentry>
115
116       <varlistentry>
117         <term><option>-p</option></term>
118         <term><option>--property=</option></term>
119
120         <listitem>
121           <para>When showing unit/job/manager properties with the
122           <command>show</command> command, limit display to certain
123           properties as specified as argument. If not specified all
124           set properties are shown. The argument should be a
125           comma-separated list of property names, such as
126           <literal>MainPID</literal>. If specified more than once all
127           properties with the specified names are shown.</para>
128         </listitem>
129       </varlistentry>
130
131       <varlistentry>
132         <term><option>-a</option></term>
133         <term><option>--all</option></term>
134
135         <listitem>
136           <para>When listing units, show all loaded units, regardless
137           of their state, including inactive units. When showing
138           unit/job/manager properties, show all properties regardless
139           whether they are set or not.</para>
140           <para>To list all units installed on the system, use the
141           <command>list-unit-files</command> command instead.</para>
142         </listitem>
143       </varlistentry>
144
145       <varlistentry>
146         <term><option>--reverse</option></term>
147
148         <listitem>
149           <para>Show reverse dependencies between units with
150           <command>list-dependencies</command>, i.e. units with
151           dependencies of type <varname>Wants=</varname> or
152           <varname>Requires=</varname> on the given unit.
153           </para>
154         </listitem>
155       </varlistentry>
156
157       <varlistentry>
158         <term><option>--after</option></term>
159         <term><option>--before</option></term>
160
161         <listitem>
162           <para>Show which units are started after, resp. before
163           with <command>list-dependencies</command>.
164           </para>
165         </listitem>
166       </varlistentry>
167
168       <varlistentry>
169         <term><option>--failed</option></term>
170
171         <listitem>
172           <para>When listing units, show only failed units. Do not
173           confuse with <option>--fail</option>.</para>
174         </listitem>
175       </varlistentry>
176
177       <varlistentry>
178         <term><option>--full</option></term>
179
180         <listitem>
181           <para>Do not ellipsize unit names, cgroup members, and
182           truncate unit descriptions in the output of
183           <command>list-units</command> and
184           <command>list-jobs</command>.</para>
185         </listitem>
186       </varlistentry>
187
188       <varlistentry>
189         <term><option>--fail</option></term>
190
191         <listitem>
192           <para>If the requested operation conflicts with a pending
193           unfinished job, fail the command. If this is not specified
194           the requested operation will replace the pending job, if
195           necessary. Do not confuse with
196           <option>--failed</option>.</para>
197         </listitem>
198       </varlistentry>
199
200       <varlistentry>
201         <term><option>--show-types</option></term>
202
203         <listitem>
204           <para>When showing sockets, show the type of the socket.</para>
205         </listitem>
206       </varlistentry>
207
208       <varlistentry>
209         <term><option>--irreversible</option></term>
210
211         <listitem>
212           <para>Mark this transaction's jobs as irreversible. This prevents
213           future conflicting transactions from replacing these jobs.
214           The jobs can still be cancelled using the <command>cancel</command>
215           command.</para>
216         </listitem>
217       </varlistentry>
218
219       <varlistentry>
220         <term><option>--ignore-dependencies</option></term>
221
222         <listitem>
223           <para>When enqueuing a new job ignore all its dependencies
224           and execute it immediately. If passed no required units of
225           the unit passed will be pulled in, and no ordering
226           dependencies will be honored. This is mostly a debugging and
227           rescue tool for the administrator and should not be used by
228           applications.</para>
229         </listitem>
230       </varlistentry>
231
232       <varlistentry>
233         <term><option>-i</option></term>
234         <term><option>--ignore-inhibitors</option></term>
235
236         <listitem>
237           <para>When system shutdown or a sleep state is requested,
238           ignore inhibitor locks. Applications can establish inhibitor
239           locks to avoid that certain important operations (such as CD
240           burning or suchlike) are interrupted by system shutdown or a
241           sleep state. Any user may take these locks and privileged
242           users may override these locks. If any locks are taken,
243           shutdown and sleep state requests will normally fail
244           (regardless if privileged or not) and a list of active locks
245           is printed. However if <option>--ignore-inhibitors</option>
246           is specified the locks are ignored and not printed, and the
247           operation attempted anyway, possibly requiring additional
248           privileges.</para>
249         </listitem>
250       </varlistentry>
251
252       <varlistentry>
253         <term><option>-q</option></term>
254         <term><option>--quiet</option></term>
255
256         <listitem>
257           <para>Suppress output to standard output in
258           <command>snapshot</command>,
259           <command>is-active</command>,
260           <command>is-failed</command>,
261           <command>enable</command> and
262         <command>disable</command>.</para>
263         </listitem>
264       </varlistentry>
265
266       <varlistentry>
267         <term><option>--no-block</option></term>
268
269         <listitem>
270           <para>Do not synchronously wait for the requested operation
271           to finish. If this is not specified the job will be
272           verified, enqueued and <command>systemctl</command> will
273           wait until it is completed. By passing this argument it is
274           only verified and enqueued.</para>
275         </listitem>
276       </varlistentry>
277
278       <varlistentry>
279         <term><option>--no-legend</option></term>
280
281         <listitem>
282           <para>Do not print a legend, i.e.  the column headers and
283           the footer with hints.</para>
284         </listitem>
285       </varlistentry>
286
287       <varlistentry>
288         <term><option>--no-pager</option></term>
289
290         <listitem>
291           <para>Do not pipe output into a pager.</para>
292         </listitem>
293       </varlistentry>
294
295       <varlistentry>
296         <term><option>--system</option></term>
297
298         <listitem>
299           <para>Talk to the systemd system manager. (Default)</para>
300         </listitem>
301       </varlistentry>
302
303       <varlistentry>
304         <term><option>--user</option></term>
305
306         <listitem>
307           <para>Talk to the systemd manager of the calling
308           user.</para>
309         </listitem>
310       </varlistentry>
311
312       <varlistentry>
313         <term><option>--no-wall</option></term>
314
315         <listitem>
316           <para>Don't send wall message before halt, power-off,
317           reboot.</para>
318         </listitem>
319       </varlistentry>
320
321       <varlistentry>
322         <term><option>--global</option></term>
323
324         <listitem>
325           <para>When used with <command>enable</command> and
326           <command>disable</command>, operate on the global user
327           configuration directory, thus enabling or disabling a unit
328           file globally for all future logins of all users.</para>
329         </listitem>
330       </varlistentry>
331
332       <varlistentry>
333         <term><option>--no-reload</option></term>
334
335         <listitem>
336           <para>When used with <command>enable</command> and
337           <command>disable</command>, do not implicitly reload daemon
338           configuration after executing the changes.</para>
339         </listitem>
340       </varlistentry>
341
342       <varlistentry>
343         <term><option>--no-ask-password</option></term>
344
345         <listitem>
346           <para>When used with <command>start</command> and related
347           commands, disables asking for passwords. Background services
348           may require input of a password or passphrase string, for
349           example to unlock system hard disks or cryptographic
350           certificates. Unless this option is specified and the
351           command is invoked from a terminal
352           <command>systemctl</command> will query the user on the
353           terminal for the necessary secrets. Use this option to
354           switch this behavior off. In this case the password must be
355           supplied by some other means (for example graphical password
356           agents) or the service might fail. This also disables
357           querying the user for authentication for privileged
358           operations.</para>
359         </listitem>
360
361       </varlistentry>
362
363       <varlistentry>
364         <term><option>--kill-who=</option></term>
365
366         <listitem>
367           <para>When used with <command>kill</command>, choose which
368           processes to kill. Must be one of <option>main</option>,
369           <option>control</option> or <option>all</option> to select
370           whether to kill only the main process of the unit, the
371           control process or all processes of the unit. If omitted
372           defaults to <option>all</option>.</para>
373         </listitem>
374
375       </varlistentry>
376
377       <varlistentry>
378         <term><option>-s</option></term>
379         <term><option>--signal=</option></term>
380
381         <listitem>
382           <para>When used with <command>kill</command>, choose which
383           signal to send to selected processes. Must be one of the
384           well known signal specifiers such as SIGTERM, SIGINT or
385           SIGSTOP. If omitted defaults to
386           <option>SIGTERM</option>.</para>
387         </listitem>
388       </varlistentry>
389
390       <varlistentry>
391         <term><option>-f</option></term>
392         <term><option>--force</option></term>
393
394         <listitem>
395           <para>When used with <command>enable</command>, overwrite
396           any existing conflicting symlinks.</para>
397
398           <para>When used with <command>halt</command>,
399           <command>poweroff</command>, <command>reboot</command> or
400           <command>kexec</command> execute the selected operation
401           without shutting down all units. However, all processes will
402           be killed forcibly and all file systems are unmounted or
403           remounted read-only. This is hence a drastic but relatively
404           safe option to request an immediate reboot. If
405           <option>--force</option> is specified twice for these
406           operations, they will be executed immediately without
407           terminating any processes or umounting any file
408           systems. Warning: specifying <option>--force</option> twice
409           with any of these operations might result in data
410           loss.</para>
411         </listitem>
412       </varlistentry>
413
414       <varlistentry>
415         <term><option>--root=</option></term>
416
417         <listitem>
418           <para>When used with
419           <command>enable</command>/<command>disable</command>/<command>is-enabled</command>
420           (and related commands), use alternative root path when
421           looking for unit files.</para>
422         </listitem>
423
424       </varlistentry>
425
426       <varlistentry>
427         <term><option>--runtime</option></term>
428
429         <listitem>
430           <para>When used with <command>enable</command>,
431           <command>disable</command>, <command>is-enabled</command>
432           (and related commands), make changes only temporarily, so
433           that they are lost on the next reboot. This will have the
434           effect that changes are not made in subdirectories of
435           <filename>/etc</filename> but in <filename>/run</filename>,
436           with identical immediate effects, however, since the latter
437           is lost on reboot, the changes are lost too.</para>
438
439           <para>Similar, when used with
440           <command>set-cgroup-attr</command>,
441           <command>unset-cgroup-attr</command>,
442           <command>set-cgroup</command> and
443           <command>unset-cgroup</command>, make changes only
444           temporarily, so that they are lost on the next
445           reboot.</para>
446         </listitem>
447       </varlistentry>
448
449       <varlistentry>
450         <term><option>-H</option></term>
451         <term><option>--host</option></term>
452
453         <listitem>
454           <para>Execute operation remotely. Specify a hostname, or
455           username and hostname separated by @, to connect to. This
456           will use SSH to talk to the remote systemd
457           instance.</para>
458         </listitem>
459       </varlistentry>
460
461       <varlistentry>
462         <term><option>-P</option></term>
463         <term><option>--privileged</option></term>
464
465         <listitem>
466           <para>Acquire privileges via PolicyKit before executing the
467           operation.</para>
468         </listitem>
469       </varlistentry>
470
471       <varlistentry>
472         <term><option>-n</option></term>
473         <term><option>--lines=</option></term>
474
475         <listitem>
476           <para>When used with <command>status</command> controls the
477           number of journal lines to show, counting from the most
478           recent ones. Takes a positive integer argument. Defaults to
479           10.</para>
480         </listitem>
481       </varlistentry>
482
483       <varlistentry>
484         <term><option>-o</option></term>
485         <term><option>--output=</option></term>
486
487         <listitem>
488           <para>When used with <command>status</command> controls the
489           formatting of the journal entries that are shown. For the
490           available choices see
491           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
492           Defaults to <literal>short</literal>.</para>
493         </listitem>
494       </varlistentry>
495
496       <varlistentry>
497         <term><option>--plain</option></term>
498
499         <listitem>
500           <para>When used with <command>list-dependencies</command>
501           the output is printed as a list instead of a tree.</para>
502         </listitem>
503       </varlistentry>
504
505     </variablelist>
506   </refsect1>
507
508   <refsect1>
509     <title>Commands</title>
510
511     <para>The following commands are understood:</para>
512
513     <variablelist>
514       <varlistentry>
515         <term><command>list-units</command></term>
516
517         <listitem>
518           <para>List known units (subject to limitations specified
519           with <option>-t</option>).</para>
520
521           <para>This is the default command.</para>
522         </listitem>
523       </varlistentry>
524
525       <varlistentry>
526         <term><command>list-sockets</command></term>
527
528         <listitem>
529           <para>List socket units ordered by the listening address. Produces output
530           similar to
531           <programlisting>
532 LISTEN           UNIT                        ACTIVATES
533 /dev/initctl     systemd-initctl.socket      systemd-initctl.service
534 ...
535 [::]:22          sshd.socket                 sshd.service
536 kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
537
538 5 sockets listed.
539           </programlisting>
540           Note: because the addresses might contains spaces, this output
541           is not suitable for programatic consumption.
542           </para>
543
544           <para>See also the options <option>--show-types</option>,
545           <option>--all</option>, and <option>--failed</option>.</para>
546         </listitem>
547       </varlistentry>
548
549        <varlistentry>
550          <term><command>set-log-level <replaceable>LEVEL</replaceable></command></term>
551
552          <listitem>
553            <para>Change current log level of the
554            <command>systemd</command> daemon to
555            <replaceable>LEVEL</replaceable> (accepts the same values
556            as <option>--log-level=</option> described in
557            <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
558            </para>
559          </listitem>
560       </varlistentry>
561
562       <varlistentry>
563         <term><command>start <replaceable>NAME</replaceable>...</command></term>
564
565         <listitem>
566           <para>Start (activate) one or more units specified on the
567           command line.</para>
568         </listitem>
569       </varlistentry>
570       <varlistentry>
571         <term><command>stop <replaceable>NAME</replaceable>...</command></term>
572
573         <listitem>
574           <para>Stop (deactivate) one or more units specified on the
575           command line.</para>
576         </listitem>
577       </varlistentry>
578       <varlistentry>
579         <term><command>reload <replaceable>NAME</replaceable>...</command></term>
580
581         <listitem>
582           <para>Asks all units listed on the command line to reload
583           their configuration. Note that this will reload the
584           service-specific configuration, not the unit configuration
585           file of systemd. If you want systemd to reload the
586           configuration file of a unit use the
587           <command>daemon-reload</command> command. In other words:
588           for the example case of Apache, this will reload Apache's
589           <filename>httpd.conf</filename> in the web server, not the
590           <filename>apache.service</filename> systemd unit
591           file. </para>
592
593           <para>This command should not be confused with the
594           <command>daemon-reload</command> or <command>load</command>
595           commands.</para>
596         </listitem>
597
598       </varlistentry>
599       <varlistentry>
600         <term><command>restart <replaceable>NAME</replaceable>...</command></term>
601
602         <listitem>
603           <para>Restart one or more units specified on the command
604           line. If the units are not running yet they will be
605           started.</para>
606         </listitem>
607       </varlistentry>
608       <varlistentry>
609         <term><command>try-restart <replaceable>NAME</replaceable>...</command></term>
610
611         <listitem>
612           <para>Restart one or more units specified on the command
613           line if the units are running. Do nothing if units are not
614           running.  Note that for compatibility with Red Hat init
615           scripts <command>condrestart</command> is equivalent to this
616           command.</para>
617         </listitem>
618       </varlistentry>
619       <varlistentry>
620         <term><command>reload-or-restart <replaceable>NAME</replaceable>...</command></term>
621
622         <listitem>
623           <para>Reload one or more units if they support it. If not,
624           restart them instead. If the units are not running yet they
625           will be started.</para>
626         </listitem>
627       </varlistentry>
628       <varlistentry>
629         <term><command>reload-or-try-restart <replaceable>NAME</replaceable>...</command></term>
630
631         <listitem>
632           <para>Reload one or more units if they support it. If not,
633           restart them instead. Do nothing if the units are not
634           running. Note that for compatibility with SysV init scripts
635           <command>force-reload</command> is equivalent to this
636           command.</para>
637         </listitem>
638       </varlistentry>
639       <varlistentry>
640         <term><command>isolate <replaceable>NAME</replaceable></command></term>
641
642         <listitem>
643           <para>Start the unit specified on the command line and its
644           dependencies and stop all others.</para>
645
646           <para>This is similar to changing the runlevel in a
647           traditional init system. The <command>isolate</command>
648           command will immediately stop processes that are not enabled
649           in the new unit, possibly including the graphical
650           environment or terminal you are currently using.</para>
651
652           <para>Note that this is allowed only on units where
653           <option>AllowIsolate=</option> is enabled. See
654           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
655           for details.</para>
656         </listitem>
657       </varlistentry>
658       <varlistentry>
659         <term><command>kill <replaceable>NAME</replaceable>...</command></term>
660
661         <listitem>
662           <para>Send a signal to one or more processes of the
663           unit. Use <option>--kill-who=</option> to select which
664           process to kill. Use <option>--kill-mode=</option> to select
665           the kill mode and <option>--signal=</option> to select the
666           signal to send.</para>
667         </listitem>
668       </varlistentry>
669       <varlistentry>
670         <term><command>is-active <replaceable>NAME</replaceable>...</command></term>
671
672         <listitem>
673           <para>Check whether any of the specified units are active
674           (i.e. running). Returns an exit code 0 if at least one is
675           active, non-zero otherwise. Unless <option>--quiet</option>
676           is specified this will also print the current unit state to
677           STDOUT.</para>
678         </listitem>
679       </varlistentry>
680       <varlistentry>
681         <term><command>is-failed <replaceable>NAME</replaceable>...</command></term>
682
683         <listitem>
684           <para>Check whether any of the specified units are failed.
685           Returns an exit code 0 if at least one is failed, non-zero
686           otherwise. Unless <option>--quiet</option> is specified this
687           will also print the current unit state to
688           STDOUT.</para>
689         </listitem>
690       </varlistentry>
691       <varlistentry>
692         <term><command>status [<replaceable>NAME</replaceable>...|<replaceable>PID</replaceable>...]</command></term>
693
694         <listitem>
695           <para>Show terse runtime status information about one or
696           more units, followed by most recent log data from the
697           journal. If no units are specified, show all units (subject
698           to limitations specified with <option>-t</option>). If a PID
699           is passed show information about the unit the process
700           belongs to.</para>
701
702           <para>This function is intended to generate human-readable
703           output. If you are looking for computer-parsable output, use
704           <command>show</command> instead.</para>
705         </listitem>
706       </varlistentry>
707       <varlistentry>
708         <term><command>show [<replaceable>NAME</replaceable>...|<replaceable>JOB</replaceable>...]</command></term>
709
710         <listitem>
711           <para>Show properties of one or more units, jobs, or the
712           manager itself. If no argument is specified properties of
713           the manager will be shown. If a unit name is specified
714           properties of the unit is shown, and if a job id is
715           specified properties of the job is shown. By default, empty
716           properties are suppressed. Use <option>--all</option> to
717           show those too. To select specific properties to show use
718           <option>--property=</option>. This command is intended to be
719           used whenever computer-parsable output is required. Use
720           <command>status</command> if you are looking for formatted
721           human-readable output.</para>
722         </listitem>
723       </varlistentry>
724
725       <varlistentry>
726         <term><command>get-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
727
728         <listitem>
729           <para>Retrieve the specified control group attributes of the
730           specified unit. Takes a unit name and one or more attribute
731           names such as <literal>cpu.shares</literal>. This will
732           output the current values of the specified attributes,
733           separated by new-lines. For attributes that take list of
734           items the output will be new-line separated, too. This
735           operation will always try to retrieve the data in question
736           from the kernel first, and if that is not available use the
737           configured values instead. Instead of low-level control
738           group attribute names high-level pretty names may be used,
739           as used for unit execution environment configuration, see
740           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
741           for details. For example, passing
742           <literal>memory.limit_in_bytes</literal> and
743           <literal>MemoryLimit</literal> is equivalent.</para>
744         </listitem>
745       </varlistentry>
746
747       <varlistentry>
748         <term><command>set-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable> <replaceable>VALUE</replaceable>...</command></term>
749
750         <listitem>
751           <para>Set the specified control group attribute of the
752           specified unit to the specified value. Takes a unit
753           name and an attribute name such as
754           <literal>cpu.shares</literal>, plus one or more values
755           (multiple values may only be used for attributes that take
756           multiple values). This operation will immediately update the
757           kernel attribute for this unit and persistently store this
758           setting for later reboots (unless <option>--runtime</option>
759           is passed, in which case the setting is not saved
760           persistently and only valid until the next reboot.) Instead
761           of low-level control group attribute names high-level pretty
762           names may be used, as used for unit execution environment
763           configuration, see
764           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
765           for details. For example, passing
766           <literal>memory.limit_in_bytes</literal> and
767           <literal>MemoryLimit</literal> is equivalent. This operation
768           will implicitly create a control group for the unit in the
769           controller the attribute belongs to, if needed. For
770           attributes that take multiple values, this operation will
771           append the specified values to the previously set values
772           list (use <command>unset-cgroup-attr</command> to reset the
773           list explicitly). For attributes that take a single value
774           only the list will be reset implicitly.</para>
775         </listitem>
776       </varlistentry>
777
778       <varlistentry>
779         <term><command>unset-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
780
781         <listitem><para>Unset the specified control group attributes
782         of the specified unit. Takes a unit name and one or more
783         attribut names such as <literal>cpu.shares</literal>. This
784         operation might or might not have an immediate effect on the
785         current kernel attribute value. This will remove any
786         persistently stored configuration values for this attribute
787         (as set with <command>set-cgroup-attr</command> before),
788         unless <option>--runtime</option> is passed, in which case the
789         configuration is reset only until the next reboot. Again,
790         high-level control group attributes may be used instead of the
791         low-level kernel ones. For attributes which take multiple
792         values, all currently set values are reset.</para>
793         </listitem>
794       </varlistentry>
795
796       <varlistentry>
797         <term><command>set-cgroup <replaceable>NAME</replaceable> <replaceable>CGROUP</replaceable>...</command></term>
798         <term><command>unset-cgroup <replaceable>NAME</replaceable> <replaceable>CGROUP</replaceable>...</command></term>
799
800         <listitem><para>Add or remove a unit to/from a specific
801         control group hierarchy and/or control group path. Takes a
802         unit name, plus a control group specification in the syntax
803         <replaceable>CONTROLLER</replaceable>:<replaceable>PATH</replaceable>
804         or <replaceable>CONTROLLER</replaceable>. In the latter syntax
805         (where the path is omitted) the default unit control group
806         path is implied. Examples: <literal>cpu</literal> or
807         <literal>cpu:/foo/bar</literal>. If a unit is removed from a
808         control group hierarchy all its processes will be moved to the
809         root group of the hierarchy and all control group attributes
810         will be reset. These operations are immediately reflected in
811         the kernel hierarchy, and stored persistently to disk (unless
812         <option>--runtime</option> is passed).</para>
813         </listitem>
814       </varlistentry>
815
816       <varlistentry>
817         <term><command>help <replaceable>NAME</replaceable>...|<replaceable>PID</replaceable>...</command></term>
818
819         <listitem>
820           <para>Show manual pages for one or more units, if
821           available. If a PID is passed the manual pages for the unit
822           the process of the PID belongs to is
823           shown.</para>
824         </listitem>
825       </varlistentry>
826
827       <varlistentry>
828         <term><command>reset-failed [<replaceable>NAME</replaceable>...]</command></term>
829
830         <listitem>
831           <para>Reset the <literal>failed</literal> state of the
832           specified units, or if no unit name is passed of all
833           units. When a unit fails in some way (i.e. process exiting
834           with non-zero error code, terminating abnormally or timing
835           out) it will automatically enter the
836           <literal>failed</literal> state and its exit code and status
837           is recorded for introspection by the administrator until the
838           service is restarted or reset with this command.</para>
839         </listitem>
840       </varlistentry>
841
842       <varlistentry>
843         <term><command>list-unit-files</command></term>
844
845         <listitem>
846           <para>List installed unit files.</para>
847         </listitem>
848       </varlistentry>
849
850       <varlistentry>
851         <term><command>enable <replaceable>NAME</replaceable>...</command></term>
852
853         <listitem>
854           <para>Enable one or more unit files or unit file instances,
855           as specified on the command line. This will create a number
856           of symlinks as encoded in the <literal>[Install]</literal>
857           sections of the unit files. After the symlinks have been
858           created the systemd configuration is reloaded (in a way that
859           is equivalent to <command>daemon-reload</command>) to ensure
860           the changes are taken into account immediately. Note that
861           this does not have the effect that any of the units enabled
862           are also started at the same time. If this is desired a
863           separate <command>start</command> command must be invoked
864           for the unit. Also note that in case of instance enablement,
865           symlinks named same as instances are created in install
866           location, however they all point to the same template unit
867           file.</para>
868
869           <para>This command will print the actions executed. This
870           output may be suppressed by passing <option>--quiet</option>.
871           </para>
872
873           <para>Note that this operation creates only the suggested
874           symlinks for the units. While this command is the
875           recommended way to manipulate the unit configuration
876           directory, the administrator is free to make additional
877           changes manually, by placing or removing symlinks in the
878           directory. This is particularly useful to create
879           configurations that deviate from the suggested default
880           installation. In this case the administrator must make sure
881           to invoke <command>daemon-reload</command> manually as
882           necessary, to ensure his changes are taken into account.
883           </para>
884
885           <para>Enabling units should not be confused with starting
886           (activating) units, as done by the <command>start</command>
887           command. Enabling and starting units is orthogonal: units
888           may be enabled without being started and started without
889           being enabled. Enabling simply hooks the unit into various
890           suggested places (for example, so that the unit is
891           automatically started on boot or when a particular kind of
892           hardware is plugged in). Starting actually spawns the daemon
893           process (in case of service units), or binds the socket (in
894           case of socket units), and so on.</para>
895
896           <para>Depending on whether <option>--system</option>,
897           <option>--user</option> or <option>--global</option> is
898           specified this enables the unit for the system, for the
899           calling user only or for all future logins of all
900           users. Note that in the last case no systemd daemon
901           configuration is reloaded.</para>
902         </listitem>
903       </varlistentry>
904
905       <varlistentry>
906         <term><command>disable <replaceable>NAME</replaceable>...</command></term>
907
908         <listitem>
909           <para>Disables one or more units. This removes all symlinks
910           to the specified unit files from the unit configuration
911           directory, and hence undoes the changes made by
912           <command>enable</command>. Note however that this removes
913           all symlinks to the unit files (i.e. including manual
914           additions), not just those actually created by
915           <command>enable</command>. This call implicitly reloads the
916           systemd daemon configuration after completing the disabling
917           of the units. Note that this command does not implicitly
918           stop the units that are being disabled. If this is desired
919           an additional <command>stop</command> command should be
920           executed afterwards.</para>
921
922           <para>This command will print the actions executed. This
923           output may be suppressed by passing <option>--quiet</option>.
924           </para>
925
926           <para>This command honors <option>--system</option>,
927           <option>--user</option>, <option>--global</option> in a
928           similar way as <command>enable</command>.</para>
929         </listitem>
930       </varlistentry>
931
932       <varlistentry>
933         <term><command>is-enabled <replaceable>NAME</replaceable>...</command></term>
934
935         <listitem>
936           <para>Checks whether any of the specified unit files are
937           enabled (as with <command>enable</command>). Returns an exit
938           code of 0 if at least one is enabled, non-zero
939           otherwise. Prints the current enable status. To suppress
940           this output use <option>--quiet</option>.</para>
941         </listitem>
942       </varlistentry>
943
944       <varlistentry>
945         <term><command>reenable <replaceable>NAME</replaceable>...</command></term>
946
947         <listitem>
948           <para>Reenable one or more unit files, as specified on the
949           command line. This is a combination of
950           <command>disable</command> and <command>enable</command> and
951           is useful to reset the symlinks a unit is enabled with to
952           the defaults configured in the <literal>[Install]</literal>
953           section of the unit file.</para>
954         </listitem>
955       </varlistentry>
956
957       <varlistentry>
958         <term><command>preset <replaceable>NAME</replaceable>...</command></term>
959
960         <listitem>
961           <para>Reset one or more unit files, as specified on the
962           command line, to the defaults configured in the preset
963           policy files. This has the same effect as
964           <command>disable</command> or <command>enable</command>,
965           depending how the unit is listed in the preset files. For
966           more information on preset policy format see
967           <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
968           For more information on the concept of presets please
969           consult the
970           <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
971           document.</para>
972         </listitem>
973       </varlistentry>
974
975       <varlistentry>
976         <term><command>mask <replaceable>NAME</replaceable>...</command></term>
977
978         <listitem>
979           <para>Mask one or more unit files, as specified on the
980           command line. This will link these units to
981           <filename>/dev/null</filename>, making it impossible to
982           start them. This is a stronger version of
983           <command>disable</command>, since it prohibits all kinds of
984           activation of the unit, including manual activation. Use
985           this option with care.</para>
986         </listitem>
987       </varlistentry>
988
989       <varlistentry>
990         <term><command>unmask <replaceable>NAME</replaceable>...</command></term>
991
992         <listitem>
993           <para>Unmask one or more unit files, as specified on the
994           command line. This will undo the effect of
995           <command>mask</command>.</para>
996         </listitem>
997       </varlistentry>
998
999       <varlistentry>
1000         <term><command>link <replaceable>FILENAME</replaceable>...</command></term>
1001
1002         <listitem>
1003           <para>Link a unit file that is not in the unit file search
1004           paths into the unit file search path. This requires an
1005           absolute path to a unit file. The effect of this can be
1006           undone with <command>disable</command>. The effect of this
1007           command is that a unit file is available for
1008           <command>start</command> and other commands although it
1009           isn't installed directly in the unit search path.</para>
1010         </listitem>
1011       </varlistentry>
1012
1013       <varlistentry>
1014         <term><command>get-default</command></term>
1015
1016         <listitem>
1017           <para>Get the default target specified
1018           via <filename>default.target</filename> link.</para>
1019         </listitem>
1020       </varlistentry>
1021
1022       <varlistentry>
1023         <term><command>set-default <replaceable>NAME</replaceable></command></term>
1024
1025         <listitem>
1026           <para>Set the default target to boot into. Command links
1027           <filename>default.target</filename> to the given unit.</para>
1028         </listitem>
1029       </varlistentry>
1030
1031       <varlistentry>
1032         <term><command>load <replaceable>NAME</replaceable>...</command></term>
1033
1034         <listitem>
1035           <para>Load one or more units specified on the command
1036           line. This will simply load their configuration from disk,
1037           but not start them. To start them you need to use the
1038           <command>start</command> command which will implicitly load
1039           a unit that has not been loaded yet. Note that systemd
1040           garbage collects loaded units that are not active or
1041           referenced by an active unit. This means that units loaded
1042           this way will usually not stay loaded for long. Also note
1043           that this command cannot be used to reload unit
1044           configuration. Use the <command>daemon-reload</command>
1045           command for that. All in all, this command is of little use
1046           except for debugging.</para>
1047
1048           <para>This command should not be confused with the
1049           <command>daemon-reload</command> or
1050           <command>reload</command>.</para>
1051         </listitem>
1052       </varlistentry>
1053       <varlistentry>
1054         <term><command>list-jobs</command></term>
1055
1056         <listitem>
1057           <para>List jobs that are in progress.</para>
1058         </listitem>
1059       </varlistentry>
1060       <varlistentry>
1061         <term><command>cancel <replaceable>JOB</replaceable>...</command></term>
1062
1063         <listitem>
1064           <para>Cancel one or more jobs specified on the command line
1065           by their numeric job IDs. If no job id is specified, cancel
1066           all pending jobs.</para>
1067         </listitem>
1068       </varlistentry>
1069       <varlistentry>
1070         <term><command>dump</command></term>
1071
1072         <listitem>
1073           <para>Dump server status. This will output a (usually very
1074           long) human readable manager status dump. Its format is
1075           subject to change without notice and should not be parsed by
1076           applications.</para>
1077         </listitem>
1078       </varlistentry>
1079       <varlistentry>
1080         <term><command>list-dependencies <replaceable>NAME</replaceable></command></term>
1081
1082         <listitem>
1083           <para>Shows required and wanted units of the specified
1084           unit. If no unit is specified
1085           <filename>default.target</filename> is implied. Target units
1086           are recursively expanded.  When <option>--all</option> is
1087           passed all other units are recursively expanded as
1088           well.</para>
1089         </listitem>
1090       </varlistentry>
1091       <varlistentry>
1092         <term><command>snapshot [<replaceable>NAME</replaceable>]</command></term>
1093
1094         <listitem>
1095           <para>Create a snapshot. If a snapshot name is specified,
1096           the new snapshot will be named after it. If none is
1097           specified an automatic snapshot name is generated. In either
1098           case, the snapshot name used is printed to STDOUT, unless
1099           <option>--quiet</option> is specified.</para>
1100
1101           <para>A snapshot refers to a saved state of the systemd
1102           manager. It is implemented itself as a unit that is
1103           generated dynamically with this command and has dependencies
1104           on all units active at the time. At a later time the user
1105           may return to this state by using the
1106           <command>isolate</command> command on the snapshot unit.
1107           </para>
1108
1109           <para>Snapshots are only useful for saving and restoring
1110           which units are running or are stopped, they do not
1111           save/restore any other state. Snapshots are dynamic and lost
1112           on reboot.</para>
1113         </listitem>
1114       </varlistentry>
1115       <varlistentry>
1116         <term><command>delete <replaceable>NAME</replaceable>...</command></term>
1117
1118         <listitem>
1119           <para>Remove a snapshot previously created with
1120           <command>snapshot</command>.</para>
1121         </listitem>
1122       </varlistentry>
1123       <varlistentry>
1124         <term><command>daemon-reload</command></term>
1125
1126         <listitem>
1127           <para>Reload systemd manager configuration. This will reload
1128           all unit files and recreate the entire dependency
1129           tree. While the daemon is reloaded, all sockets systemd
1130           listens on on behalf of user configuration will stay
1131           accessible.</para> <para>This command should not be confused
1132           with the <command>load</command> or
1133           <command>reload</command> commands.</para>
1134         </listitem>
1135       </varlistentry>
1136       <varlistentry>
1137         <term><command>daemon-reexec</command></term>
1138
1139         <listitem>
1140           <para>Reexecute the systemd manager. This will serialize the
1141           manager state, reexecute the process and deserialize the
1142           state again. This command is of little use except for
1143           debugging and package upgrades. Sometimes it might be
1144           helpful as a heavy-weight <command>daemon-reload</command>.
1145           While the daemon is reexecuted all sockets systemd listens
1146           on on behalf of user configuration will stay accessible.
1147           </para>
1148         </listitem>
1149       </varlistentry>
1150       <varlistentry>
1151         <term><command>show-environment</command></term>
1152
1153         <listitem>
1154           <para>Dump the systemd manager environment block. The
1155           environment block will be dumped in straight-forward form
1156           suitable for sourcing into a shell script. This environment
1157           block will be passed to all processes the manager
1158           spawns.</para>
1159         </listitem>
1160       </varlistentry>
1161       <varlistentry>
1162         <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>...</command></term>
1163
1164         <listitem>
1165           <para>Set one or more systemd manager environment variables,
1166           as specified on the command line.</para>
1167         </listitem>
1168       </varlistentry>
1169       <varlistentry>
1170         <term><command>unset-environment <replaceable>VARIABLE</replaceable>...</command></term>
1171
1172         <listitem>
1173           <para>Unset one or more systemd manager environment
1174           variables. If only a variable name is specified it will be
1175           removed regardless of its value. If a variable and a value
1176           are specified the variable is only removed if it has the
1177           specified value.</para>
1178         </listitem>
1179       </varlistentry>
1180       <varlistentry>
1181         <term><command>default</command></term>
1182
1183         <listitem>
1184           <para>Enter default mode. This is mostly equivalent to
1185           <command>isolate default.target</command>.</para>
1186         </listitem>
1187       </varlistentry>
1188       <varlistentry>
1189         <term><command>rescue</command></term>
1190
1191         <listitem>
1192           <para>Enter rescue mode. This is mostly equivalent to
1193           <command>isolate rescue.target</command> but also prints a
1194           wall message to all users.</para>
1195         </listitem>
1196       </varlistentry>
1197       <varlistentry>
1198         <term><command>emergency</command></term>
1199
1200         <listitem>
1201           <para>Enter emergency mode. This is mostly equivalent to
1202           <command>isolate emergency.target</command> but also prints
1203           a wall message to all users.</para>
1204         </listitem>
1205       </varlistentry>
1206       <varlistentry>
1207         <term><command>halt</command></term>
1208
1209         <listitem>
1210           <para>Shut down and halt the system. This is mostly equivalent to
1211           <command>start halt.target --irreversible</command> but also
1212           prints a wall message to all users.  If combined with
1213           <option>--force</option> shutdown of all running services is
1214           skipped, however all processes are killed and all file
1215           systems are unmounted or mounted read-only, immediately
1216           followed by the system halt.  If <option>--force</option> is
1217           specified twice the operation is immediately executed
1218           without terminating any processes or unmounting any file
1219           systems. This may result in data loss.</para>
1220         </listitem>
1221       </varlistentry>
1222       <varlistentry>
1223         <term><command>poweroff</command></term>
1224
1225         <listitem>
1226           <para>Shut down and power-off the system. This is mostly
1227           equivalent to <command>start poweroff.target --irreversible</command>
1228           but also prints a wall message to all users. If combined with
1229           <option>--force</option> shutdown of all running services is
1230           skipped, however all processes are killed and all file
1231           systems are unmounted or mounted read-only, immediately
1232           followed by the powering off. If <option>--force</option> is
1233           specified twice the operation is immediately executed
1234           without terminating any processes or unmounting any file
1235           systems. This may result in data loss.</para>
1236         </listitem>
1237       </varlistentry>
1238       <varlistentry>
1239         <term><command>reboot</command></term>
1240
1241         <listitem>
1242           <para>Shut down and reboot the system. This is mostly
1243           equivalent to <command>start reboot.target --irreversible</command>
1244           but also prints a wall message to all users. If combined with
1245           <option>--force</option> shutdown of all running services is
1246           skipped, however all processes are killed and all file
1247           systems are unmounted or mounted read-only, immediately
1248           followed by the reboot. If <option>--force</option> is
1249           specified twice the operation is immediately executed
1250           without terminating any processes or unmounting any file
1251           systems. This may result in data loss.</para>
1252         </listitem>
1253       </varlistentry>
1254       <varlistentry>
1255         <term><command>kexec</command></term>
1256
1257         <listitem>
1258           <para>Shut down and reboot the system via kexec. This is
1259           mostly equivalent to <command>start kexec.target --irreversible</command>
1260           but also prints a wall message to all users. If combined
1261           with <option>--force</option> shutdown of all running
1262           services is skipped, however all processes are killed and
1263           all file systems are unmounted or mounted read-only,
1264           immediately followed by the reboot.</para>
1265         </listitem>
1266       </varlistentry>
1267       <varlistentry>
1268         <term><command>exit</command></term>
1269
1270         <listitem>
1271           <para>Ask the systemd manager to quit. This is only
1272           supported for user service managers (i.e. in conjunction
1273           with the <option>--user</option> option) and will fail
1274           otherwise.</para>
1275         </listitem>
1276
1277       </varlistentry>
1278       <varlistentry>
1279         <term><command>suspend</command></term>
1280
1281         <listitem>
1282           <para>Suspend the system. This will trigger activation of
1283           the special <filename>suspend.target</filename> target.
1284           </para>
1285         </listitem>
1286       </varlistentry>
1287       <varlistentry>
1288         <term><command>hibernate</command></term>
1289
1290         <listitem>
1291           <para>Hibernate the system. This will trigger activation of
1292           the special <filename>hibernate.target</filename> target.
1293           </para>
1294         </listitem>
1295       </varlistentry>
1296       <varlistentry>
1297         <term><command>hybrid-sleep</command></term>
1298
1299         <listitem>
1300           <para>Hibernate and suspend the system. This will trigger
1301           activation of the special
1302           <filename>hybrid-sleep.target</filename> target.</para>
1303         </listitem>
1304       </varlistentry>
1305       <varlistentry>
1306         <term><command>switch-root <replaceable>ROOT</replaceable> [<replaceable>INIT</replaceable>]</command></term>
1307
1308         <listitem>
1309           <para>Switches to a different root directory and executes a
1310           new system manager process below it. This is intended for
1311           usage in initial RAM disks ("initrd"), and will transition
1312           from the initrd's system manager process (a.k.a "init"
1313           process) to the main system manager process. Takes two
1314           arguments: the directory to make the new root directory, and
1315           the path to the new system manager binary below it to
1316           execute as PID 1. If the latter is omitted or the empty
1317           string, a systemd binary will automatically be searched for
1318           and used as init. If the system manager path is omitted or
1319           equal to the empty string the state of the initrd's system
1320           manager process is passed to the main system manager, which
1321           allows later introspection of the state of the services
1322           involved in the initrd boot.</para>
1323         </listitem>
1324       </varlistentry>
1325     </variablelist>
1326
1327   </refsect1>
1328
1329   <refsect1>
1330     <title>Exit status</title>
1331
1332     <para>On success 0 is returned, a non-zero failure
1333     code otherwise.</para>
1334   </refsect1>
1335
1336   <refsect1>
1337     <title>Environment</title>
1338
1339     <variablelist class='environment-variables'>
1340       <varlistentry>
1341         <term><varname>$SYSTEMD_PAGER</varname></term>
1342
1343         <listitem>
1344           <para>Pager to use when <option>--no-pager</option> is not
1345           given; overrides <varname>$PAGER</varname>.  Setting this to
1346           an empty string or the value <literal>cat</literal> is
1347           equivalent to passing
1348           <option>--no-pager</option>.</para>
1349         </listitem>
1350       </varlistentry>
1351     </variablelist>
1352   </refsect1>
1353
1354   <refsect1>
1355     <title>See Also</title>
1356     <para>
1357       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1358       <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1359       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1360       <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1361       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1362       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1363       <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1364       <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1365     </para>
1366   </refsect1>
1367
1368 </refentry>