Cache
-=====
+-----
-The default cache in Knot Resolver is persistent on disk, which means that the daemon doesn't lose
-the cached data on restart or crash, and thus performace does not suffer from cold-starts.
+Cache in Knot Resolver is stored on disk and also shared between `Multiple instances`_
+so resolver doesn't lose the cached data on restart or crash.
-The cache may be reused between cache
-daemons or manipulated from other processes, making for example synchronized load-balanced recursors possible.
+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.
+
+
+.. _`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.
+
+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:: lua
+
+ -- 90 % of free memory after machine restart
+ cache.size = 13453 * MB
+
+.. _`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 to tmpfs.
+ While it is technically possible to move the cache to an existing
+ tmpfs filesystem, it is *not recommended*: The path to cache is specified in
+ multiple systemd units, and a shared tmpfs space could be used up by other
+ applications, leading to ``SIGBUS`` errors during runtime.
+
+Mounting the cache directory as tmpfs_ is recommended apparoach.
+Make sure to use appropriate ``size=`` 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:: lua
+
+ # /etc/knot-resolver/config
+ cache.size = 2 * GB
+
+.. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs
+
+Configuration reference
+^^^^^^^^^^^^^^^^^^^^^^^
.. function:: cache.open(max_size[, config_uri])
.. include:: ../daemon/README.rst
.. include:: ../daemon/bindings/net.rst
-.. include:: ../daemon/bindings/cache.rst
.. include:: ../daemon/lua/trust_anchors.rst
-Multiple instances
-==================
-
-Knot Resolver can utilize multiple CPUs running in multiple independent instances (processes), where each process utilizes at most single CPU core on your machine. If your machine handles a lot of DNS traffic run multiple instances.
-
-All instances typically share the same configuration and cache, and incomming queries are automatically distributed by operating system among all instances.
-
-Advantage of using multiple instances is that a problem in a single instance will not affect others, so a single instance crash will not bring whole DNS resolver service down.
-
-.. tip:: For maximum performance, there should be as many kresd processes as
- there are available CPU threads.
-
-To run multiple instances, use a different identifier after `@` sign for each instance, for
-example:
-
-.. code-block:: bash
-
- $ systemctl start kresd@1.service
- $ systemctl start kresd@2.service
- $ systemctl start kresd@3.service
- $ systemctl start kresd@4.service
-
-With the use of brace expansion in BASH the equivalent command looks like this:
-
-.. code-block:: bash
-
- $ systemctl start kresd@{1..4}.service
-
-For more details see ``kresd.systemd(7)``.
-
-
-Zero-downtime restarts
-----------------------
-Resolver restart normally takes just miliseconds and cache content is persistent to avoid performance drop
-after restart. If you want real zero-downtime restarts use `multiple instances`_ and do rolling
-restart, i.e. restart only one resolver process at a time.
-
-On a system with 4 instances run these commands sequentially:
-
-.. code-block:: bash
-
- $ systemctl restart kresd@1.service
- $ systemctl restart kresd@2.service
- $ systemctl restart kresd@3.service
- $ systemctl restart kresd@4.service
-
-At any given time only a single instance is stopped and restarted so remaining three instances continue to service clients.
-
-
-.. _instance-specific-configuration:
-
-Instance-specific configuration
--------------------------------
-
-Instances can use arbitraty identifiers for the instances, for example we can name instances like `dns1`, `tls` and so on.
-
-.. code-block:: bash
-
- $ systemctl start kresd@dns1
- $ systemctl start kresd@dns2
- $ systemctl start kresd@tls
- $ systemctl start kresd@doh
-
-The instance name is subsequently exposed to kresd via the environment variable
-``SYSTEMD_INSTANCE``. This can be used to tell the instances apart, e.g. when
-using the :ref:`mod-nsid` module with per-instance configuration:
-
-.. code-block:: lua
-
- local systemd_instance = os.getenv("SYSTEMD_INSTANCE")
-
- modules.load('nsid')
- nsid.name(systemd_instance)
-
-More arcane set-ups are also possible. The following example isolates the
-individual services for classic DNS, DoT and DoH from each other.
-
-.. code-block:: lua
-
- local systemd_instance = os.getenv("SYSTEMD_INSTANCE")
-
- if string.match(systemd_instance, '^dns') then
- net.listen('127.0.0.1', 53, { kind = 'dns' })
- elseif string.match(systemd_instance, '^tls') then
- net.listen('127.0.0.1', 853, { kind = 'tls' })
- elseif string.match(systemd_instance, '^doh') then
- net.listen('127.0.0.1', 443, { kind = 'doh' })
- else
- panic("Use kresd@dns*, kresd@tls* or kresd@doh* instance names")
- end
-
Logging, monitoring, diagnostics
================================
Knot Resolver logs to standard outputs, which is then captured by supervisor
It is disabled by default.
+.. _performance:
Performance and resiliency
==========================
+For DNS resolvers, the most important parameter from performance perspective
+is cache hit rate, i.e. percentage of queries answered from resolver's cache.
+Generally the higher cache hit rate the better.
+
+Performance tunning should start with cache :ref:`cache_sizing`
+and :ref:`cache_persistence`.
+
+It is also recommended to run `Multiple instances`_ (even on a single machine!)
+because it allows to utilize multiple CPU threads
+and increases overall resiliency.
+
+Other features described in this section can be used for fine-tunning
+performance and resiliency of the resolver but generally have much smaller
+impact than cache settings and number of instances.
+
+.. include:: ../daemon/bindings/cache.rst
+.. include:: ../systemd/multiinst.rst
.. include:: ../modules/predict/README.rst
.. include:: ../modules/priming/README.rst
.. include:: ../modules/rfc7706.rst
:caption: Operation
:maxdepth: 1
- performance
monitoring
upgrading
NEWS
-.. _performance:
-
-Performance tunning
-===================
-
.. _cache_sizing:
Cache sizing
cache.size = 2 * GB
.. _tmpfs: https://en.wikipedia.org/wiki/Tmpfs
-
-
-Utilizing all CPUs
-------------------
-
--- /dev/null
+Multiple instances
+------------------
+
+Knot Resolver can utilize multiple CPUs running in multiple independent instances (processes), where each process utilizes at most single CPU core on your machine. If your machine handles a lot of DNS traffic run multiple instances.
+
+All instances typically share the same configuration and cache, and incomming queries are automatically distributed by operating system among all instances.
+
+Advantage of using multiple instances is that a problem in a single instance will not affect others, so a single instance crash will not bring whole DNS resolver service down.
+
+.. tip:: For maximum performance, there should be as many kresd processes as
+ there are available CPU threads.
+
+To run multiple instances, use a different identifier after `@` sign for each instance, for
+example:
+
+.. code-block:: bash
+
+ $ systemctl start kresd@1.service
+ $ systemctl start kresd@2.service
+ $ systemctl start kresd@3.service
+ $ systemctl start kresd@4.service
+
+With the use of brace expansion in BASH the equivalent command looks like this:
+
+.. code-block:: bash
+
+ $ systemctl start kresd@{1..4}.service
+
+For more details see ``kresd.systemd(7)``.
+
+
+Zero-downtime restarts
+^^^^^^^^^^^^^^^^^^^^^^
+Resolver restart normally takes just miliseconds and cache content is persistent to avoid performance drop
+after restart. If you want real zero-downtime restarts use `multiple instances`_ and do rolling
+restart, i.e. restart only one resolver process at a time.
+
+On a system with 4 instances run these commands sequentially:
+
+.. code-block:: bash
+
+ $ systemctl restart kresd@1.service
+ $ systemctl restart kresd@2.service
+ $ systemctl restart kresd@3.service
+ $ systemctl restart kresd@4.service
+
+At any given time only a single instance is stopped and restarted so remaining three instances continue to service clients.
+
+
+.. _instance-specific-configuration:
+
+Instance-specific configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instances can use arbitraty identifiers for the instances, for example we can name instances like `dns1`, `tls` and so on.
+
+.. code-block:: bash
+
+ $ systemctl start kresd@dns1
+ $ systemctl start kresd@dns2
+ $ systemctl start kresd@tls
+ $ systemctl start kresd@doh
+
+The instance name is subsequently exposed to kresd via the environment variable
+``SYSTEMD_INSTANCE``. This can be used to tell the instances apart, e.g. when
+using the :ref:`mod-nsid` module with per-instance configuration:
+
+.. code-block:: lua
+
+ local systemd_instance = os.getenv("SYSTEMD_INSTANCE")
+
+ modules.load('nsid')
+ nsid.name(systemd_instance)
+
+More arcane set-ups are also possible. The following example isolates the
+individual services for classic DNS, DoT and DoH from each other.
+
+.. code-block:: lua
+
+ local systemd_instance = os.getenv("SYSTEMD_INSTANCE")
+
+ if string.match(systemd_instance, '^dns') then
+ net.listen('127.0.0.1', 53, { kind = 'dns' })
+ elseif string.match(systemd_instance, '^tls') then
+ net.listen('127.0.0.1', 853, { kind = 'tls' })
+ elseif string.match(systemd_instance, '^doh') then
+ net.listen('127.0.0.1', 443, { kind = 'doh' })
+ else
+ panic("Use kresd@dns*, kresd@tls* or kresd@doh* instance names")
+ end
Garbage Collector
------------------
+^^^^^^^^^^^^^^^^^
-Knot Resolver employs a separate garbage collector daemon (process ``kres-cache-gc``) which periodically trims the cache to keep its size below a configured size limit.
+Knot Resolver employs a separate garbage collector daemon which periodically trims the cache to keep its size below size limit configured using :envvar:`cache.size`.
Systemd service ``kres-cache-gc.service`` is enabled by default and does not need any manual intervention.
projects / thirdparty / knot-resolver.git / commitdiff
