Docs

pdns/recursordist/rec-rust-lib/docs-new-preamble-in.rst

@@ -531,6 +531,35 @@ For catalog zone members in a group, the forwarding parameters will be taken fro
 
 The forwarding definitions will be written into a file ``$api_dir/catzone.$zonename``. :ref:`setting-yaml-webservice.api_dir` must be defined, the directory must exist and be writable by the :program:`Recursor` process.
 
+IncomingWSConfig
+^^^^^^^^^^^^^^^^^^^^^
+As of version 5.3.0, an incoming web server configuration is defined as
+
+.. code-block:: yaml
+
+   addresses: [] Sequence of SocketAddress
+   tls:
+     certificates: file containing full certificate chain in PEM format
+     key: file contaiing private key in PEM format
+
+
+A :ref:`setting-yaml-webservice.listen` section contains a sequence of `IncomingWSConfig`_, for example:
+
+.. code-block:: yaml
+
+  webservice:
+    listen:
+      - addresses: [127.0.0.1:8083, '[::]:8083']
+        tls:
+          certificate: fullchain.pem
+          key: keyfile.key
+      - addresses: [127.0.0.1:8084, '[::]:8084']
+
+If no ``tls`` section is present, plaintext ``http`` connections are accepted on the listed addresses.
+
+If a ``tls`` section is present, clienst are required to use ``https`` to contact any of the address-port combinations listen in addresses. At the moment it is not possible to list additional properties of the TLS listener and encrypted key files cannot be used.
+
+
 The YAML settings
 -----------------
 

pdns/recursordist/rec-rust-lib/generate.py

@@ -185,6 +185,8 @@ def get_newdoc_typename(typ):
         return 'Sequence of `ProxyMapping`_'
     if typ == LType.ListForwardingCatalogZones:
         return 'Sequence of `ForwardingCatalogZone`_'
+    if typ == LType.ListIncomingWSConfigs:
+        return 'Sequence of `IncomingWSConfig`_'
     return 'Unknown2' + str(typ)
 
 def get_default_olddoc_value(typ, val):

pdns/recursordist/rec-rust-lib/table.py

@@ -3194,8 +3194,8 @@
         'default' : '',
         'help' : 'XXXX',
         'doc' : '''
-XXXXX IP addresses for the webserver to listen on.
-If this setting has a non-default value, :ref:`setting-yaml-webservice.address`  :ref:`setting-yaml-webservice.port` and will be ignored.
+IP addresses and associated attributes for the webserver to listen on.
+If this setting has a non-default value, :ref:`setting-yaml-webservice.address` and :ref:`setting-yaml-webservice.port` will be ignored.
  ''',
         'skip-old': 'No equivalent old-style setting',
         'versionadded': '5.3.0',
@@ -3236,35 +3236,12 @@
         'help' : 'Amount of logging in the webserver (none, normal, detailed)',
         'doc' : '''
 One of ``none``, ``normal``, ``detailed``.
-The amount of logging the webserver must do. 'none' means no useful webserver information will be logged.
-When set to 'normal', the webserver will log a line per request that should be familiar::
-
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 'GET /api/v1/servers/localhost/bla HTTP/1.1' 404 196
-
-When set to 'detailed', all information about the request and response are logged::
-
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e Request Details:
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Headers:
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept-encoding: gzip, deflate
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept-language: en-US,en;q=0.5
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   connection: keep-alive
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   dnt: 1
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   host: 127.0.0.1:8081
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   upgrade-insecure-requests: 1
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   user-agent: Mozilla/5.0 (X11; Linux x86_64; rv:64.0) Gecko/20100101 Firefox/64.0
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  No body
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e Response details:
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Headers:
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Connection: close
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Content-Length: 49
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Content-Type: text/html; charset=utf-8
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Server: PowerDNS/0.0.15896.0.gaba8bab3ab
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Full body:
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   <!html><title>Not Found</title><h1>Not Found</h1>
-  [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 'GET /api/v1/servers/localhost/bla HTTP/1.1' 404 196
-
-The value between the hooks is a UUID that is generated for each request. This can be used to find all lines related to a single request.
+The amount of logging the webserver must do. ``none`` means no useful webserver information will be logged.
+When set to ``normal``, the webserver will log a line per request::
+
+   Feb 03 14:54:00 msg="Request" subsystem="webserver" level="0" prio="Notice" tid="0" ts="1738590840.208" HTTPVersion="HTTP/1.1" method="GET" remote="[::1]:49880" respsize="5418" status="200" uniqueid="a31a280d-29de-4db8-828f-edc862eb8653" urlpath="/"
+
+When set to ``detailed``, all available information about the request and response is logged.
 
 .. note::
   The webserver logs these line on the NOTICE level. The :ref:`setting-loglevel` seting must be 5 or higher for these lines to end up in the log.