systemctl: add commands set-default and get-default

[elogind.git] / man / systemctl.xml

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 1a55522b12d1d88c8344251f76984637900586c2..430e16c327b77d83fa522c57ea26129f737328ce 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -92,21 +92,22 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <term><option>--type=</option></term>
 
         <listitem>
         <term><option>--type=</option></term>
 
         <listitem>

-          <para>The argument should be a unit type name such as
-          <option>service</option> and <option>socket</option>, or a
-          unit load state such as <option>loaded</option> and
-          <option>masked</option>.
-          </para>
-
-          <para>If the argument is a unit type, when listing units,
-          limit display to certain unit types. If not specified units
+          <para>The argument should be a comma separated list of unit
+          types such as <option>service</option> and
+          <option>socket</option>, or unit load states such as
+          <option>loaded</option> and <option>masked</option>
+          (types and states can be mixed).</para>
+
+          <para>If one of the arguments is a unit type, when listing
+          units, limit display to certain unit types. Otherwise units

           of all types will be shown.</para>
 
           of all types will be shown.</para>
 

-          <para>If the argument is a unit load state, when listing
-          units, limit display to certain unit types. If not specified
-          units of in all load states will be shown.</para>
+          <para>If one of the arguments is a unit load state, when
+          listing units, limit display to certain unit
+          types. Otherwise units of in all load states will be
+          shown.</para>

 
 

-          <para>As a special case, if the argument is
+          <para>As a special case, if one of the arguments is

           <option>help</option>, a list of allowed values will be
           printed and the program will exit.</para>
         </listitem>
           <option>help</option>, a list of allowed values will be
           printed and the program will exit.</para>
         </listitem>


@@ -117,13 +118,13 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <term><option>--property=</option></term>
 
         <listitem>
         <term><option>--property=</option></term>
 
         <listitem>

-          <para>When showing unit/job/manager properties, limit
-          display to certain properties as specified as argument. If
-          not specified all set properties are shown. The argument
-          should be a property name, such as
+          <para>When showing unit/job/manager properties with the
+          <command>show</command> command, limit display to certain
+          properties as specified as argument. If not specified all
+          set properties are shown. The argument should be a
+          comma-separated list of property names, such as

           <literal>MainPID</literal>. If specified more than once all
           <literal>MainPID</literal>. If specified more than once all

-          properties with the specified names are
-          shown.</para>
+          properties with the specified names are shown.</para>

         </listitem>
       </varlistentry>
 
         </listitem>
       </varlistentry>
 


@@ -132,10 +133,35 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <term><option>--all</option></term>
 
         <listitem>
         <term><option>--all</option></term>
 
         <listitem>

-          <para>When listing units, show all units, regardless of
-          their state, including inactive units. When showing
+          <para>When listing units, show all loaded units, regardless
+          of their state, including inactive units. When showing

           unit/job/manager properties, show all properties regardless
           whether they are set or not.</para>
           unit/job/manager properties, show all properties regardless
           whether they are set or not.</para>

+          <para>To list all units installed on the system, use the
+          <command>list-unit-files</command> command instead.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--reverse</option></term>
+
+        <listitem>
+          <para>Show reverse dependencies between units with
+          <command>list-dependencies</command>, i.e. units with
+          dependencies of type <varname>Wants=</varname> or
+          <varname>Requires=</varname> on the given unit.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--after</option></term>
+        <term><option>--before</option></term>
+
+        <listitem>
+          <para>Show which units are started after, resp. before
+          with <command>list-dependencies</command>.
+          </para>

         </listitem>
       </varlistentry>
 
         </listitem>
       </varlistentry>
 


@@ -171,6 +197,25 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         </listitem>
       </varlistentry>
 
         </listitem>
       </varlistentry>
 

+      <varlistentry>
+        <term><option>--show-types</option></term>
+
+        <listitem>
+          <para>When showing sockets, show the type of the socket.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--irreversible</option></term>
+
+        <listitem>
+          <para>Mark this transaction's jobs as irreversible. This prevents
+          future conflicting transactions from replacing these jobs.
+          The jobs can still be cancelled using the <command>cancel</command>
+          command.</para>
+        </listitem>
+      </varlistentry>
+

       <varlistentry>
         <term><option>--ignore-dependencies</option></term>
 
       <varlistentry>
         <term><option>--ignore-dependencies</option></term>
 


@@ -196,7 +241,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
           sleep state. Any user may take these locks and privileged
           users may override these locks. If any locks are taken,
           shutdown and sleep state requests will normally fail
           sleep state. Any user may take these locks and privileged
           users may override these locks. If any locks are taken,
           shutdown and sleep state requests will normally fail

-          (regardless if privileged or not) and list of active locks
+          (regardless if privileged or not) and a list of active locks

           is printed. However if <option>--ignore-inhibitors</option>
           is specified the locks are ignored and not printed, and the
           operation attempted anyway, possibly requiring additional
           is printed. However if <option>--ignore-inhibitors</option>
           is specified the locks are ignored and not printed, and the
           operation attempted anyway, possibly requiring additional


@@ -382,14 +427,22 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <term><option>--runtime</option></term>
 
         <listitem>
         <term><option>--runtime</option></term>
 
         <listitem>

-          <para>When used with
-          <command>enable</command>/<command>disable</command>/<command>is-enabled</command>
+          <para>When used with <command>enable</command>,
+          <command>disable</command>, <command>is-enabled</command>

           (and related commands), make changes only temporarily, so
           (and related commands), make changes only temporarily, so

-          that they are dropped on the next reboot. This will have the
+          that they are lost on the next reboot. This will have the

           effect that changes are not made in subdirectories of
           <filename>/etc</filename> but in <filename>/run</filename>,
           with identical immediate effects, however, since the latter
           is lost on reboot, the changes are lost too.</para>
           effect that changes are not made in subdirectories of
           <filename>/etc</filename> but in <filename>/run</filename>,
           with identical immediate effects, however, since the latter
           is lost on reboot, the changes are lost too.</para>

+
+          <para>Similar, when used with
+          <command>set-cgroup-attr</command>,
+          <command>unset-cgroup-attr</command>,
+          <command>set-cgroup</command> and
+          <command>unset-cgroup</command>, make changes only
+          temporarily, so that they are lost on the next
+          reboot.</para>

         </listitem>
       </varlistentry>
 
         </listitem>
       </varlistentry>
 


@@ -440,6 +493,15 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         </listitem>
       </varlistentry>
 
         </listitem>
       </varlistentry>
 

+      <varlistentry>
+        <term><option>--plain</option></term>
+
+        <listitem>
+          <para>When used with <command>list-dependencies</command>
+          the output is printed as a list instead of a tree.</para>
+        </listitem>
+      </varlistentry>
+

     </variablelist>
   </refsect1>
 
     </variablelist>
   </refsect1>
 


@@ -459,6 +521,31 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
           <para>This is the default command.</para>
         </listitem>
       </varlistentry>
           <para>This is the default command.</para>
         </listitem>
       </varlistentry>

+
+      <varlistentry>
+        <term><command>list-sockets</command></term>
+
+        <listitem>
+          <para>List socket units ordered by the listening address. Produces output
+          similar to
+          <programlisting>
+LISTEN           UNIT                        ACTIVATES
+/dev/initctl     systemd-initctl.socket      systemd-initctl.service
+...
+[::]:22          sshd.socket                 sshd.service
+kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
+
+5 sockets listed.
+          </programlisting>
+          Note: because the addresses might contains spaces, this output
+          is not suitable for programatic consumption.
+          </para>
+
+          <para>See also the options <option>--show-types</option>,
+          <option>--all</option>, and <option>--failed</option>.</para>
+        </listitem>
+      </varlistentry>
+

       <varlistentry>
         <term><command>start <replaceable>NAME</replaceable>...</command></term>
 
       <varlistentry>
         <term><command>start <replaceable>NAME</replaceable>...</command></term>
 


@@ -621,6 +708,98 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
           human-readable output.</para>
         </listitem>
       </varlistentry>
           human-readable output.</para>
         </listitem>
       </varlistentry>

+
+      <varlistentry>
+        <term><command>get-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
+
+        <listitem>
+          <para>Retrieve the specified control group attributes of the
+          specified unit. Takes a unit name and one or more attribute
+          names such as <literal>cpu.shares</literal>. This will
+          output the current values of the specified attributes,
+          separated by new-lines. For attributes that take list of
+          items the output will be new-line separated, too. This
+          operation will always try to retrieve the data in question
+          from the kernel first, and if that is not available use the
+          configured values instead. Instead of low-level control
+          group attribute names high-level pretty names may be used,
+          as used for unit execution environment configuration, see
+          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          for details. For example, passing
+          <literal>memory.limit_in_bytes</literal> and
+          <literal>MemoryLimit</literal> is equivalent.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><command>set-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable> <replaceable>VALUE</replaceable>...</command></term>
+
+        <listitem>
+          <para>Set the specified control group attribute of the
+          specified unit to the specified value. Takes a unit
+          name and an attribute name such as
+          <literal>cpu.shares</literal>, plus one or more values
+          (multiple values may only be used for attributes that take
+          multiple values). This operation will immediately update the
+          kernel attribute for this unit and persistently store this
+          setting for later reboots (unless <option>--runtime</option>
+          is passed, in which case the setting is not saved
+          persistently and only valid until the next reboot.) Instead
+          of low-level control group attribute names high-level pretty
+          names may be used, as used for unit execution environment
+          configuration, see
+          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          for details. For example, passing
+          <literal>memory.limit_in_bytes</literal> and
+          <literal>MemoryLimit</literal> is equivalent. This operation
+          will implicitly create a control group for the unit in the
+          controller the attribute belongs to, if needed. For
+          attributes that take multiple values, this operation will
+          append the specified values to the previously set values
+          list (use <command>unset-cgroup-attr</command> to reset the
+          list explicitly). For attributes that take a single value
+          only the list will be reset implicitly.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><command>unset-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
+
+        <listitem><para>Unset the specified control group attributes
+        of the specified unit. Takes a unit name and one or more
+        attribut names such as <literal>cpu.shares</literal>. This
+        operation might or might not have an immediate effect on the
+        current kernel attribute value. This will remove any
+        persistently stored configuration values for this attribute
+        (as set with <command>set-cgroup-attr</command> before),
+        unless <option>--runtime</option> is passed, in which case the
+        configuration is reset only until the next reboot. Again,
+        high-level control group attributes may be used instead of the
+        low-level kernel ones. For attributes which take multiple
+        values, all currently set values are reset.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><command>set-cgroup <replaceable>NAME</replaceable> <replaceable>CGROUP</replaceable>...</command></term>
+        <term><command>unset-cgroup <replaceable>NAME</replaceable> <replaceable>CGROUP</replaceable>...</command></term>
+
+        <listitem><para>Add or remove a unit to/from a specific
+        control group hierarchy and/or control group path. Takes a
+        unit name, plus a control group specification in the syntax
+        <replaceable>CONTROLLER</replaceable>:<replaceable>PATH</replaceable>
+        or <replaceable>CONTROLLER</replaceable>. In the latter syntax
+        (where the path is omitted) the default unit control group
+        path is implied. Examples: <literal>cpu</literal> or
+        <literal>cpu:/foo/bar</literal>. If a unit is removed from a
+        control group hierarchy all its processes will be moved to the
+        root group of the hierarchy and all control group attributes
+        will be reset. These operations are immediately reflected in
+        the kernel hierarchy, and stored persistently to disk (unless
+        <option>--runtime</option> is passed).</para>
+        </listitem>
+      </varlistentry>
+

       <varlistentry>
         <term><command>help <replaceable>NAME</replaceable>...|<replaceable>PID</replaceable>...</command></term>
 
       <varlistentry>
         <term><command>help <replaceable>NAME</replaceable>...|<replaceable>PID</replaceable>...</command></term>
 


@@ -631,6 +810,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
           shown.</para>
         </listitem>
       </varlistentry>
           shown.</para>
         </listitem>
       </varlistentry>

+

       <varlistentry>
         <term><command>reset-failed [<replaceable>NAME</replaceable>...]</command></term>
 
       <varlistentry>
         <term><command>reset-failed [<replaceable>NAME</replaceable>...]</command></term>
 


@@ -817,6 +997,24 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         </listitem>
       </varlistentry>
 
         </listitem>
       </varlistentry>
 

+      <varlistentry>
+        <term><command>get-default</command></term>
+
+        <listitem>
+          <para>Get the default target specified
+          via <filename>default.target</filename> link.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><command>set-default <replaceable>NAME</replaceable></command></term>
+
+        <listitem>
+          <para>Set the default target to boot into. Command links
+          <filename>default.target</filename> to the given unit.</para>
+        </listitem>
+      </varlistentry>
+

       <varlistentry>
         <term><command>load <replaceable>NAME</replaceable>...</command></term>
 
       <varlistentry>
         <term><command>load <replaceable>NAME</replaceable>...</command></term>
 


@@ -971,7 +1169,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
         <listitem>
           <para>Enter default mode. This is mostly equivalent to
 
         <listitem>
           <para>Enter default mode. This is mostly equivalent to

-          <command>start default.target</command>.</para>
+          <command>isolate default.target</command>.</para>

         </listitem>
       </varlistentry>
       <varlistentry>
         </listitem>
       </varlistentry>
       <varlistentry>


@@ -996,8 +1194,8 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         <term><command>halt</command></term>
 
         <listitem>
         <term><command>halt</command></term>
 
         <listitem>

-          <para>Shut down and halt the system. This is mostly
-          equivalent to <command>start halt.target</command> but also
+          <para>Shut down and halt the system. This is mostly equivalent to
+          <command>start halt.target --irreversible</command> but also

           prints a wall message to all users.  If combined with
           <option>--force</option> shutdown of all running services is
           skipped, however all processes are killed and all file
           prints a wall message to all users.  If combined with
           <option>--force</option> shutdown of all running services is
           skipped, however all processes are killed and all file


@@ -1013,8 +1211,8 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
         <listitem>
           <para>Shut down and power-off the system. This is mostly
 
         <listitem>
           <para>Shut down and power-off the system. This is mostly

-          equivalent to <command>start poweroff.target</command> but
-          also prints a wall message to all users. If combined with
+          equivalent to <command>start poweroff.target --irreversible</command>
+          but also prints a wall message to all users. If combined with

           <option>--force</option> shutdown of all running services is
           skipped, however all processes are killed and all file
           systems are unmounted or mounted read-only, immediately
           <option>--force</option> shutdown of all running services is
           skipped, however all processes are killed and all file
           systems are unmounted or mounted read-only, immediately


@@ -1029,8 +1227,8 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
         <listitem>
           <para>Shut down and reboot the system. This is mostly
 
         <listitem>
           <para>Shut down and reboot the system. This is mostly

-          equivalent to <command>start reboot.target</command> but
-          also prints a wall message to all users. If combined with
+          equivalent to <command>start reboot.target --irreversible</command>
+          but also prints a wall message to all users. If combined with

           <option>--force</option> shutdown of all running services is
           skipped, however all processes are killed and all file
           systems are unmounted or mounted read-only, immediately
           <option>--force</option> shutdown of all running services is
           skipped, however all processes are killed and all file
           systems are unmounted or mounted read-only, immediately


@@ -1045,7 +1243,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
         <listitem>
           <para>Shut down and reboot the system via kexec. This is
 
         <listitem>
           <para>Shut down and reboot the system via kexec. This is

-          mostly equivalent to <command>start kexec.target</command>
+          mostly equivalent to <command>start kexec.target --irreversible</command>

           but also prints a wall message to all users. If combined
           with <option>--force</option> shutdown of all running
           services is skipped, however all processes are killed and
           but also prints a wall message to all users. If combined
           with <option>--force</option> shutdown of all running
           services is skipped, however all processes are killed and