From: Aleš Mrázek Date: Mon, 29 Jan 2024 15:42:18 +0000 (+0100) Subject: doc: cache clearing X-Git-Tag: v6.0.7~23^2~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1fd08704719905a0ffdb8496e8f80469af91617c;p=thirdparty%2Fknot-resolver.git doc: cache clearing --- diff --git a/doc/config-cache.rst b/doc/config-cache.rst index 11c85cbdd..6469b5ce6 100644 --- 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": "" + + 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": "" + + 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": + + :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": "" + + 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": >` 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 7992d86a7..bafa86df0 100644 --- 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 ` - ``{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 3dcf20cc8..2e50c882c 100644 --- 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 - 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 :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:: + .. 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