+++ /dev/null
-.. _daemon:
-
-TODO: Basics
-============
-
-.. function:: user(name, [group])
-
- :param string name: user name
- :param string group: group name (optional)
- :return: boolean
-
- Drop privileges and start running as given user (and group, if provided).
-
- .. tip:: Note that you should bind to required network addresses before changing user. At the same time, you should open the cache **AFTER** you change the user (so it remains accessible). A good practice is to divide configuration in two parts:
-
- .. code-block:: lua
-
- -- privileged
- net.listen('127.0.0.1')
- net.listen('::1')
- user('knot-resolver', 'netgrp')
- -- unprivileged
- cache.size = 100*MB
-
- Example output:
-
- .. code-block:: lua
-
- > user('baduser')
- invalid user name
- > user('knot-resolver', 'netgrp')
- true
- > user('root')
- Operation not permitted
-
-
-.. _`JSON-encoded`: http://json.org/example
-.. _`PowerDNS Recursor`: https://doc.powerdns.com/md/recursor/scripting/
-.. _libuv: https://github.com/libuv/libuv
-.. _Lua: https://www.lua.org/about.html
-.. _LuaJIT: http://luajit.org/luajit.html
-.. _`real process managers`: http://blog.crocodoc.com/post/48703468992/process-managers-the-good-the-bad-and-the-ugly
-.. _`socket activation`: http://0pointer.de/blog/projects/socket-activation.html
-.. _`dnsproxy module`: https://www.knot-dns.cz/docs/2.7/html/modules.html#dnsproxy-tiny-dns-proxy
-- 90 % of free memory after machine restart
cache.size = 13453 * MB
+.. note:: The :ref:`garbage-collector` can be used to periodically trim the
+ cache. It is enabled and configured by default when running kresd with
+ systemd integration.
+
.. _`cache_persistence`:
Persistence
[subtree] => 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.
-
-.. include:: ../utils/cache_gc/README.rst
--- /dev/null
+Privileges and capabilities
+===========================
+
+The kresd daemon requires privileges when it is configured to bind to
+well-known ports. There are multiple ways to achieve this.
+
+Using capabilities
+^^^^^^^^^^^^^^^^^^
+
+The most secure and recommended way is to use capabilities and execute kresd as
+an unprivileged user.
+
+* ``CAP_NET_BIND_SERVICE`` is required to bind to well-known ports.
+* ``CAP_SETPCAP`` when this capability is available, kresd drops any extra
+ privileges after the daemon successfully starts.
+
+Running as non-privileged user
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Another possibility is to start the process as privileged user and then switch
+to a non-privileged user after binding to network interfaces.
+
+.. function:: user(name, [group])
+
+ :param string name: user name
+ :param string group: group name (optional)
+ :return: boolean
+
+ Drop privileges and start running as given user (and group, if provided).
+
+ .. tip:: Note that you should bind to required network addresses before
+ changing user. At the same time, you should open the cache **AFTER** you
+ change the user (so it remains accessible). A good practice is to divide
+ configuration in two parts:
+
+ .. code-block:: lua
+
+ -- privileged
+ net.listen('127.0.0.1')
+ net.listen('::1')
+ user('knot-resolver', 'netgrp')
+ -- unprivileged
+ cache.size = 100*MB
+
+ Example output:
+
+ .. code-block:: lua
+
+ > user('baduser')
+ invalid user name
+ > user('knot-resolver', 'netgrp')
+ true
+ > user('root')
+ Operation not permitted
+
+Running as root
+^^^^^^^^^^^^^^^
+
+.. warning:: Executing processes as root is generally insecure, as these
+ proccesses have unconstrained access to the complete system at runtime.
+
+While not recommended, it is also possible to run kresd directly as root.
+
+Please note the process will still attempt to drop capabilities after startup.
+Among other things, this means the cache directory should belong to root to
+have write access.
--- /dev/null
+Process management
+==================
+
+There following should be taken into consideration when running without systemd:
+
+* To utilize multiple CPUs, kresd has to be executed as several independent
+ processes.
+* Maintenance daemon(s) have to be executed separately.
+* If a process crashes, it might be useful to restart it.
+* Using some mechanism similar to :ref:`mod-watchdog` might be desirable to
+ recover in case a process becomes unresponsive.
+
+Please note, systemd isn't the only process manager and other solutions exist,
+such as supervisord_. Configuring these is out of the scope of this
+document. Please refer to their respective documentations.
+
+It is also possible to use kresd without any process management at all, which
+may be suitable for some purposes (such as low-traffic local / home network resolver,
+testing, development or debugging).
+
+.. include:: ../utils/cache_gc/README.rst
+
+.. _`supervisord`: http://supervisord.org/
--- /dev/null
+.. _usage-without-systemd:
+
+*********************
+Usage without systemd
+*********************
+
+.. tip:: Our upstream packages use systemd integration, which is the recommended
+ way to run kresd. This section is only relevant if you choose to use kresd
+ without systemd integration.
+
+Knot Resolver is designed to be a single process without the use of threads.
+While the cache is shared, the individual processes are independent. This
+approach has several benefits, but it also comes with a few downsides, in
+particular:
+
+* Without the use of threads or forking (deprecated, see `#529`_), multiple
+ processes aren't managed in any way by kresd.
+* There is no maintenance thread and these tasks have to be handled by separate
+ daemon(s) (such as :ref:`garbage-collector`).
+
+To offset these these disadvantages without implementing process management in
+kresd (and reinventing the wheel), Knot Resolver provides integration with
+systemd, which is widely used across GNU/Linux distributions.
+
+If your use-case doesn't support systemd (e.g. using macOS, FreeBSD, Docker,
+OpenWrt, Turris), this section describes the differences and things to keep in
+mind when configuring and running kresd without systemd integration.
+
+.. toctree::
+ :maxdepth: 2
+
+ config-no-systemd-processes
+ config-no-systemd-privileges
+
+.. _`#529`: https://gitlab.labs.nic.cz/knot/knot-resolver/issues/529
config-logging-monitoring
config-dnssec
config-experimental
+ config-no-systemd
.. _operation:
Multiple instances
==================
+.. note:: This section describes the usage of kresd when running under systemd.
+ For other uses, please refer to :ref:`usage-without-systemd`.
+
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.
+.. _garbage-collector:
+
Garbage Collector
-----------------
-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`.
+.. note:: When using systemd, ``kres-cache-gc.service`` is enabled by default
+ and does not need any manual configuration.
-Systemd service ``kres-cache-gc.service`` is enabled by default and does not need any manual intervention.
+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`.
-If you decide to experiment with garbage collector configuration you can execute the daemon manually and configure it to run every second:
+To execute the daemon manually, you can use the following command to run it
+every second:
.. code-block:: bash
$ kres-cache-gc -c /var/cache/knot-resolver -d 1000
-
projects / thirdparty / knot-resolver.git / commitdiff
