man: document new "systemctl clean…" operation

4 files changed, 60 insertions, 10 deletions

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 5ebe1832bc..b2e3cbcb21 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -507,6 +507,21 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>--what=</option></term>
+
+        <listitem>
+          <para>Select what type of per-unit resources to remove when the <command>clean</command> command is
+          invoked, see below. Takes one of <constant>configuration</constant>, <constant>state</constant>,
+          <constant>cache</constant>, <constant>logs</constant>, <constant>runtime</constant> to select the
+          type of resource. This option may be specified more than once, in which case all specified resource
+          types are removed. Also accepts the special value <constant>all</constant> as a shortcut for
+          specifiying all five resource types. If this option is not specified defaults to the combination of
+          <constant>cache</constant> and <constant>runtime</constant>, i.e. the two kinds of resources that
+          are generally considered to be redundant and can be reconstructed on next invocation.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>-f</option></term>
         <term><option>--force</option></term>
 
@@ -905,6 +920,24 @@ Sun 2017-02-26 20:57:49 EST  2h 3min left  Sun 2017-02-26 11:56:36 EST  6h ago
           </listitem>
         </varlistentry>
         <varlistentry>
+          <term><command>clean <replaceable>PATTERN</replaceable>…</command></term>
+
+          <listitem>
+            <para>Remove the configuration, state, cache, logs or runtime data of the specified units. Use
+            <option>--what=</option> to select which kind of resource to remove. For service units this may
+            be used to remove the directories configured with <varname>ConfigurationDirectory=</varname>,
+            <varname>StateDirectory=</varname>, <varname>CacheDirectory=</varname>,
+            <varname>LogsDirectory=</varname> and <varname>RuntimeDirectory=</varname>, see
+            <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+            for details. For timer units this may be used to clear out the persistent timestamp data if
+            <varname>Persistent=</varname> is used and <option>--what=state</option> is selected, see
+            <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
+            command only applies to units that use either of these settings. If <option>--what=</option> is
+            not specified, both the cache and runtime data are removed (as these two types of data are
+            generally redundant and reproducible on the next invocation of the unit).</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
           <term><command>is-active <replaceable>PATTERN</replaceable>…</command></term>
 
           <listitem>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 56a029a82e..48dd42ca3c 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -981,6 +981,11 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         the directories is tied directly to the lifetime of the unit, and it is not necessary to ensure that the
         <filename>tmpfiles.d</filename> configuration is executed before the unit is started.</para>
 
+        <para>To remove any of the directories created by these settings, use the <command>systemctl clean
+        …</command> command on the relevant units, see
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+        details.</para>
+
         <para>Example: if a system service unit has the following,
         <programlisting>RuntimeDirectory=foo/bar baz</programlisting>
         the service manager creates <filename>/run/foo</filename> (if it does not exist),
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 22329f6c2f..145f97206c 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -611,6 +611,16 @@
       </varlistentry>
 
       <varlistentry>
+        <term><varname>TimeoutCleanSec=</varname></term>
+        <listitem><para>Configures a timeout on the clean-up operation requested through <command>systemctl
+        clean …</command>, see
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+        details. Takes the usual time values and defaults to <constant>infinity</constant>, i.e. by default
+        no time-out is applied. If a time-out is configured the clean operation will be aborted forcibly when
+        the time-out is reached, potentially leaving resources on disk.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><varname>RuntimeMaxSec=</varname></term>
 
         <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been
diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml
index 340286d912..0f6518dbc2 100644
--- a/man/systemd.timer.xml
+++ b/man/systemd.timer.xml
@@ -286,16 +286,18 @@
       <varlistentry>
         <term><varname>Persistent=</varname></term>
 
-        <listitem><para>Takes a boolean argument. If true, the time
-        when the service unit was last triggered is stored on disk.
-        When the timer is activated, the service unit is triggered
-        immediately if it would have been triggered at least once
-        during the time when the timer was inactive. This is useful to
-        catch up on missed runs of the service when the machine was
-        off. Note that this setting only has an effect on timers
-        configured with <varname>OnCalendar=</varname>. Defaults
-        to <varname>false</varname>.
-        </para></listitem>
+        <listitem><para>Takes a boolean argument. If true, the time when the service unit was last triggered
+        is stored on disk.  When the timer is activated, the service unit is triggered immediately if it
+        would have been triggered at least once during the time when the timer was inactive. This is useful
+        to catch up on missed runs of the service when the system was powered down. Note that this setting
+        only has an effect on timers configured with <varname>OnCalendar=</varname>. Defaults to
+        <varname>false</varname>.</para>
+
+        <para>Use <command>systemctl clean --what=state …</command> on the timer unit to remove the timestamp
+        file maintained by this option from disk. In particular, use this command before uninstalling a timer
+        unit. See
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+        details.</para></listitem>
       </varlistentry>
 
       <varlistentry>