man: update documentation of systemctl cgroup commands

3 files changed, 21 insertions, 89 deletions

diff --git a/TODO b/TODO
index 0b11599b8a..33308ef18a 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,6 @@ CGroup Rework Completion:
 * introduce high-level settings for RT budget, swappiness
 
 * wiki: document new bus APIs of PID 1 (transient units, Reloading signal)
-* review: systemctl commands
 
 * Send SIGHUP and SIGTERM in session scopes
 
diff --git a/man/systemctl.xml b/man/systemctl.xml
index 982051778e..4bfce95ffa 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -433,10 +433,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
           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
+          <command>set-property</command> make changes only
           temporarily, so that they are lost on the next
           reboot.</para>
         </listitem>
@@ -719,93 +716,28 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
       </varlistentry>
 
       <varlistentry>
-        <term><command>get-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
+        <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</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 a list of
-          items, the output will be newline-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>
+          <para>Set the specified unit properties at runtime where
+          this is supported. This allows changing configuration
+          parameter properties such as resource management controls at
+          runtime. Not all properties may be changed at runtime, but
+          many resource management settings (primarily those in
+          <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+          may. The changes are applied instantly, and stored on disk
+          for future boots, unless <option>--runtime</option> is
+          passed in which case the settings only apply until the next
+          reboot. The syntax of the property assignment follows
+          closely the syntax of assignments in unit files.</para>
 
-        <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>
+          <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para>
 
-        <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>
+          <para>Note that this command allows changing multiple
+          properties at the same time, which is preferable over
+          setting them individually. Like unit file configuration
+          settings assigning the empty list to list parameters will
+          reset the list.</para>
         </listitem>
       </varlistentry>
 
@@ -1354,6 +1286,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.cgroupq</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c
index c9f9981f9c..9f47b2cf7c 100644
--- a/src/systemctl/systemctl.c
+++ b/src/systemctl/systemctl.c
@@ -4788,7 +4788,7 @@ static int systemctl_help(void) {
                "  list-jobs                       List jobs\n"
                "  cancel [JOB...]                 Cancel all, one, or more jobs\n\n"
                "Status Commands:\n"
-               "  dump                            Dump server status\n"
+               "  dump                            Dump server status\n\n"
                "Snapshot Commands:\n"
                "  snapshot [NAME]                 Create a snapshot\n"
                "  delete [NAME...]                Remove one or more snapshots\n\n"