summaryrefslogtreecommitdiffstats
path: root/doc/config-no-systemd-privileges.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:26:00 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:26:00 +0000
commit830407e88f9d40d954356c3754f2647f91d5c06a (patch)
treed6a0ece6feea91f3c656166dbaa884ef8a29740e /doc/config-no-systemd-privileges.rst
parentInitial commit. (diff)
downloadknot-resolver-830407e88f9d40d954356c3754f2647f91d5c06a.tar.xz
knot-resolver-830407e88f9d40d954356c3754f2647f91d5c06a.zip
Adding upstream version 5.6.0.upstream/5.6.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--doc/config-no-systemd-privileges.rst65
1 files changed, 65 insertions, 0 deletions
diff --git a/doc/config-no-systemd-privileges.rst b/doc/config-no-systemd-privileges.rst
new file mode 100644
index 0000000..e2c2ab9
--- /dev/null
+++ b/doc/config-no-systemd-privileges.rst
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+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
+ capabilities after the daemon successfully starts when running as
+ a non-root user.
+
+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
+ processes have unconstrained access to the complete system at runtime.
+
+While not recommended, it is also possible to run kresd directly as root.