From: Vladimír Čunát Date: Mon, 6 May 2024 08:17:14 +0000 (+0200) Subject: doc/user: move cache-clearing API docs to the API page X-Git-Tag: v6.0.12~2^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4bdec42edd745bde1be733648c6cf73a88c8eb8d;p=thirdparty%2Fknot-resolver.git doc/user: move cache-clearing API docs to the API page It seemed to clutter the cache page in docs, even though very few users will be directly interested in the API. --- diff --git a/doc/user/config-cache.rst b/doc/user/config-cache.rst index 66de7da4c..500c7266e 100644 --- a/doc/user/config-cache.rst +++ b/doc/user/config-cache.rst @@ -53,6 +53,16 @@ Now you can configure cache size to be 90% of the free memory 14 928 MB, i.e. 13 Clearing -------- +You can use :ref:`kresctl ` to clear (parts of) the cache, e.g.: + +.. code-block:: none + + $ kresctl cache clear example.com. + + $ kresctl cache clear --help + +It is also possible to use HTTP API directly: :ref:`manager-api-cache-clear`. + 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) @@ -60,73 +70,9 @@ There are two specifics to purging cache records matching specified criteria: * 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/user/manager-api.rst b/doc/user/manager-api.rst index fb1c713b9..95fcd489a 100644 --- a/doc/user/manager-api.rst +++ b/doc/user/manager-api.rst @@ -29,7 +29,7 @@ What can the API do? - ``GET /metrics/prometheus`` provides metrics in Prometheus format The ``prometheus-client`` Python package needs to be installed. If not installed, it returns 404 (Not Found). -- ``POST /cache/clear`` purges cache records matching the specified criteria, see :ref:`cache clearing ` +- ``POST /cache/clear`` purges cache records matching the specified criteria, see :ref:`manager-api-cache-clear` Configuring the API socket @@ -82,3 +82,64 @@ Some configuration options cannot be changed dynamically for stability or securi In the case of an attempt to configure such an option, the operation is rejected. +.. _manager-api-cache-clear: + +Cache clearing API +------------------ +``POST /cache/clear`` purges cache records matching the specified criteria. +Some general properties of cache-clearance are also described at :ref:`config-cache-clear`. + +Parameters +`````````` +Parameters are in JSON and 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.