doc: cache clearing

diff --git a/doc/config-cache.rst b/doc/config-cache.rst
index 11c85cbdd80dc39aa9d67498d966bfff8398baba..6469b5ce615b189fd5569e3736f27ed2d46336ce 100644 (file)
--- a/doc/config-cache.rst
+++ b/doc/config-cache.rst
@@ -48,6 +48,85 @@ Now you can configure cache size to be 90% of the free memory 14 928 MB, i.e. 13
      size-max: 13453M
 
 
+.. _config-cache-clear:
+
+Clearing
+--------
+
+There are two specifics to purging cache records matching specified criteria:
+
+* To reliably remove negative cache entries, you need to clear the subtree with the whole zone. E.g. to clear negative cache entries for the (formerly non-existent)
+  record ``www.example.com. A``, you need to flush the whole subtree starting at the zone apex `example.com.` or closer to the root. [#]_
+* This operation is asynchronous and might not yet be finished when the call to the ``/cache/clear`` API endpoint returns.
+  The return value indicates if clearing continues asynchronously or not.
+
+.. tip::
+
+   Use :ref:`manager-client` to clear the cache.
+
+   .. code-block:: none
+
+      $ kresctl cache-clear example.com.
+
+.. [#] This is a consequence of DNSSEC negative cache which relies on proofs of non-existence on various owner nodes. It is impossible to efficiently flush part of DNS zones signed with NSEC3.
+
+
+Parameters
+``````````
+Parameters for cache clearance are in JSON and are sent with the HTTP request as its body.
+
+.. option:: "name": "<name>"
+
+   Optional, subtree to purge; if the name isn't provided, whole cache is purged (and any other parameters are disregarded).
+
+.. option:: "exact-name": true|false
+
+   :default: false
+
+   If set to ``true``, only records with *the same* name are removed.
+
+.. option:: "rr-type": "<rr-type>"
+
+   Optional, you may additionally specify the type to remove, but that is only supported with :option:`exact-name <"exact-name": true|false>` enabled.
+
+.. option:: "chunk-size": <integer>
+
+   :default: 100
+
+   The number of records to remove in a single round. The purpose is not to block the resolver for too long.
+   By default, the resolver repeats the command after at least one millisecond until all the matching data is cleared.
+
+Return value
+````````````
+
+The return value is an object with the following fields. The ``count`` field is
+always present.
+
+.. option:: "count": integer
+
+   The number of items removed from the cache by this call (may be 0 if no entry matched criteria).
+
+   Always present.
+
+.. option:: "not_apex": true|false
+
+   Cleared subtree is not cached as zone apex; proofs of non-existence were probably not removed.
+
+   Optional. Considered ``false`` when not present.
+
+.. option:: "subtree": "<zone_apex>"
+
+   Hint where zone apex lies (this is an estimation based on the cache contents and may not always be accurate).
+
+   Optional.
+
+.. option:: "chunk_limit": true|false
+
+   More than :option:`chunk-size <"chunk-size": <integer>>` items needs to be cleared, clearing will continue asynchronously.
+
+   Optional. Considered ``false`` when not present.
+
+
 .. _config-cache-persistence:
 
 Persistence

diff --git a/doc/manager-api.rst b/doc/manager-api.rst
index 7992d86a7cde7ce37d39ce57540f3fe2a1f0e51f..bafa86df0d2ac523c029977b0f2a3c1d886f1e9c 100644 (file)
--- a/doc/manager-api.rst
+++ b/doc/manager-api.rst
@@ -88,6 +88,7 @@ List of API endpoints
 - ``GET /metrics`` provides Prometheus metrics
 - ``GET /`` static response that could be used to determine, whether the Manager is running
 - ``POST /stop`` gracefully stops the Manager, empty request body
+- ``POST /cache-clear`` purges cache records matching the specified criteria, see :ref:`cache clearing <config-cache-clear>`
 - ``{GET,PUT,DELETE,PATCH} /v1/config`` allows reading and modifying current configuration
 
 
@@ -109,3 +110,4 @@ The different HTTP methods perform different modifications of the configuration:
 
 To prevent race conditions when changing configuration from multiple clients simultaneously, every response from the Manager has an ``ETag`` header set. Requests then accept ``If-Match`` and ``If-None-Match`` headers with the latest ``ETag`` value and the corresponding request processing fails with HTTP error code 412 (precondition failed).
 
+

diff --git a/doc/manager-client.rst b/doc/manager-client.rst
index 3dcf20cc8b3b1d33ec6b43d1e7cca8211982dad0..2e50c882c684d701a339c801b6aabf81f3e8b2b0 100644 (file)
--- a/doc/manager-client.rst
+++ b/doc/manager-client.rst
@@ -160,29 +160,30 @@ Only one of these arguments can be selected during the execution of a single ``k
 
 .. option:: cache-clear
 
-        Purge cache records matching specified criteria.
+        Purge cache records matching the specified criteria.
 
     .. option:: --exact-name
 
-        If set, only records with the same name are removed.
+        If set, only records with the exact same name are removed, not the whole subtree.
 
     .. option:: --rr-type <rr-type>
 
-        Optional, you may additionally specify the type to remove,
-        but that is only supported with :option:`--exact-name` flag set.
+        The record type to remove. Only supported together with :option:`--exact-name`.
+
+        Optional.
 
     .. option:: --chunk-size <chunk-size>
 
         :default: 100
 
-        Optional, the number of records to remove in one round.
-        The purpose is not to block the resolver for long.
-        The resolver repeats the command after one millisecond until all matching data are cleared.
+        The number of records to remove in a single round.
+        The purpose is not to block the resolver for too long.
+        The resolver repeats the command after at least one millisecond, until all the matching data is cleared.
 
-    .. option:: <name>
+    .. option:: [name]
 
-        Optional, subtree to purge; if the name isn't provided,
-        whole cache is purged (and any other parameters are disregarded).
+        The subtree to purge.
+        If not provided, the whole cache is purged (and any other parameters are disregarded).
 
     .. code-block:: bash