From db915f1e973c531f3fb7d815ceac063c219d3cdf Mon Sep 17 00:00:00 2001 From: Tomas Krizek Date: Mon, 13 Jan 2020 16:03:28 +0100 Subject: [PATCH] doc: add section about usage without systemd - mention process management - describe privileges and capabilities which have to be configured - move garbage collector to this section, as is it enabled by default --- daemon/README.rst | 44 ------------------- daemon/bindings/cache.rst | 6 ++- doc/config-no-systemd-privileges.rst | 66 ++++++++++++++++++++++++++++ doc/config-no-systemd-processes.rst | 23 ++++++++++ doc/config-no-systemd.rst | 35 +++++++++++++++ doc/index.rst | 1 + systemd/multiinst.rst | 3 ++ utils/cache_gc/README.rst | 13 ++++-- 8 files changed, 141 insertions(+), 50 deletions(-) delete mode 100644 daemon/README.rst create mode 100644 doc/config-no-systemd-privileges.rst create mode 100644 doc/config-no-systemd-processes.rst create mode 100644 doc/config-no-systemd.rst diff --git a/daemon/README.rst b/daemon/README.rst deleted file mode 100644 index 4701e8d42..000000000 --- a/daemon/README.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _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 diff --git a/daemon/bindings/cache.rst b/daemon/bindings/cache.rst index 52b66b609..7c2821bb0 100644 --- a/daemon/bindings/cache.rst +++ b/daemon/bindings/cache.rst @@ -37,6 +37,10 @@ Now you can configure cache size to be 90% of the free memory 14 928 MB, i.e. 13 -- 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 @@ -311,5 +315,3 @@ Configuration reference [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 diff --git a/doc/config-no-systemd-privileges.rst b/doc/config-no-systemd-privileges.rst new file mode 100644 index 000000000..227ce6c58 --- /dev/null +++ b/doc/config-no-systemd-privileges.rst @@ -0,0 +1,66 @@ +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. diff --git a/doc/config-no-systemd-processes.rst b/doc/config-no-systemd-processes.rst new file mode 100644 index 000000000..b4e9e4d43 --- /dev/null +++ b/doc/config-no-systemd-processes.rst @@ -0,0 +1,23 @@ +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/ diff --git a/doc/config-no-systemd.rst b/doc/config-no-systemd.rst new file mode 100644 index 000000000..814ae49e3 --- /dev/null +++ b/doc/config-no-systemd.rst @@ -0,0 +1,35 @@ +.. _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 diff --git a/doc/index.rst b/doc/index.rst index ca797665c..0e4d9e121 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -27,6 +27,7 @@ and it provides a state-machine like API for extensions. config-logging-monitoring config-dnssec config-experimental + config-no-systemd .. _operation: diff --git a/systemd/multiinst.rst b/systemd/multiinst.rst index 3897f5e00..a2ca7becb 100644 --- a/systemd/multiinst.rst +++ b/systemd/multiinst.rst @@ -3,6 +3,9 @@ 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. diff --git a/utils/cache_gc/README.rst b/utils/cache_gc/README.rst index 80729825a..71d8bd779 100644 --- a/utils/cache_gc/README.rst +++ b/utils/cache_gc/README.rst @@ -1,13 +1,18 @@ +.. _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 - -- 2.47.2