.. SPDX-License-Identifier: GPL-3.0-or-later .. _config-cache: Cache ===== Cache in Knot Resolver is shared between :ref:`multiple workers ` and stored in a file, so resolver doesn't lose the cached data on restart or crash. To improve performance even further the resolver implements so-called aggressive caching for DNSSEC-validated data (:rfc:`8198`), which improves performance and also protects against some types of Random Subdomain Attacks. .. _config-cache-sizing: Sizing ------ For personal and small office use-cases cache size around 100 MB is more than enough. For large deployments we recommend to run Knot Resolver on a dedicated machine, and to allocate 90% of machine's free memory for resolver's cache. .. note:: Choosing a cache size that can fit into RAM is important even if the cache is stored on disk (default). Otherwise, the extra I/O caused by disk access for missing pages can cause performance issues. For example, imagine you have a machine with 16 GB of memory. After machine restart you use command ``free -m`` to determine amount of free memory (without swap): .. code-block:: bash $ free -m total used free Mem: 15907 979 14928 Now you can configure cache size to be 90% of the free memory 14 928 MB, i.e. 13 453 MB: .. code-block:: yaml -- 90 % of free memory after machine restart cache: 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 ----------- .. tip:: Using ``tmpfs`` for cache improves performance and reduces disk I/O. By default the cache is saved on a persistent storage device so the content of the cache is persisted during system reboot. This usually leads to smaller latency after restart etc., however in certain situations a non-persistent cache storage might be preferred, e.g.: - Resolver handles high volume of queries and I/O performance to disk is too low. - Threat model includes attacker getting access to disk content in power-off state. - Disk has limited number of writes (e.g. flash memory in routers). If non-persistent cache is desired configure cache directory to be on tmpfs_ filesystem, a temporary in-memory file storage. The cache content will be saved in memory, and thus have faster access and will be lost on power-off or reboot. .. note:: In most of the Unix-like systems ``/tmp`` and ``/var/run`` are commonly mounted as tmpfs. While it is technically possible to move the cache to an existing tmpfs filesystem, it is *not recommended*, since the path to cache is configured in multiple places. Mounting the cache directory as tmpfs_ is the recommended approach. Make sure to use appropriate ``size-max`` option and don't forget to adjust the size in the config file as well. .. code-block:: none # /etc/fstab tmpfs /var/cache/knot-resolver tmpfs rw,size=2G,uid=knot-resolver,gid=knot-resolver,nosuid,nodev,noexec,mode=0700 0 0 .. code-block:: yaml # /etc/knot-resolver/config.yaml cache: storage: /var/cache/knot-resolver size-max: 1G .. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs Configuration reference ----------------------- .. option:: cache/storage: :default: /var/cache/knot-resolver .. option:: cache/size-max: :default: 100M .. note:: Use ``B, K, M, G`` bytes units prefixes. Opens cache with a size limit. The cache will be reopened if already open. Note that the maximum size cannot be lowered, only increased due to how cache is implemented. .. code-block:: yaml cache: storage: /var/cache/knot-resolver size-max: 400M .. option:: cache/ttl-max: