From: Karel Bilek <kb@karelbilek.com>
Date: Mon, 1 Sep 2025 21:28:46 +0000 (+0200)
Subject: dnsdist: Clarify different webserver auths
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fpull%2F15773%2Fhead;p=thirdparty%2Fpdns.git

dnsdist: Clarify different webserver auths
---

diff --git a/pdns/dnsdistdist/docs/guides/webserver.rst b/pdns/dnsdistdist/docs/guides/webserver.rst
index 534deb1788..6b3447cfca 100755
--- a/pdns/dnsdistdist/docs/guides/webserver.rst
+++ b/pdns/dnsdistdist/docs/guides/webserver.rst
@@ -51,6 +51,45 @@ For example, to remove the X-Frame-Options header and add a X-Custom one:
 
 Credentials can be changed at run time using the :func:`setWebserverConfig` function.
 
+Credentials
+-----------
+
+The webserver uses two kind of authorization: one is HTTP basic auth, with name and
+password; username doesn't matter, only password is checked. Second kind of authorization is
+with an API key, which must be in ``X-API-Key`` request header. Those keys can be different,
+and are two different options to :func:`setWebserverConfig`.
+
+There are also three different options for :func:`setWebserverConfig`, which can disable
+the auth for the calls altogether by setting them to false; they are true by default.
+
+.. list-table::
+   :header-rows: 1
+
+   * - endpoint
+     - option to disable auth
+     - basic auth
+     - API header auth
+   * - main dashboard
+     - ``dashboardRequiresAuthentication``
+     - allowed
+     - not allowed
+   * - ``/jsonstat``
+     - ``statsRequireAuthentication``
+     - allowed
+     - allowed
+   * - ``/metrics``
+     - ``statsRequireAuthentication``
+     - allowed
+     - allowed
+   * - ``/api/v1/servers/localhost``
+     - ``dashboardRequiresAuthentication``
+     - allowed
+     - allowed
+   * - other ``/api/`` endpoints
+     - ``apiRequiresAuthentication``
+     - not allowed
+     - allowed
+
 dnsdist API
 -----------
 
diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index 644dfe54a8..7970de1f07 100644
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -467,7 +467,7 @@ Webserver configuration
   .. versionchanged:: 1.8.0
     ``apiRequiresAuthentication``, ``dashboardRequiresAuthentication`` optional parameters added.
 
-  Setup webserver configuration. See :func:`webserver`.
+  Setup webserver configuration. See :func:`webserver` and :doc:`../guides/webserver`.
 
   :param table options: A table with key: value pairs with webserver options.