From: Aleš Mrázek Date: Mon, 3 Jul 2023 15:03:44 +0000 (+0200) Subject: docs: config: yaml for cache X-Git-Tag: v6.0.2~16^2~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dba73de0b62acab5c91370442a3faa08e9f6ed23;p=thirdparty%2Fknot-resolver.git docs: config: yaml for cache --- diff --git a/doc/config-cache.rst b/doc/config-cache.rst new file mode 100644 index 000000000..d6b2cd8cc --- /dev/null +++ b/doc/config-cache.rst @@ -0,0 +1,148 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. _config-cache: + +Cache +===== + +Cache in Knot Resolver is stored on disk and also shared between +:ref:`systemd-multiple-instances` 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-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: