From: Otto Moerbeek Date: Mon, 3 Feb 2025 13:57:34 +0000 (+0100) Subject: Docs X-Git-Tag: dnsdist-2.0.0-alpha1~95^2~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fdb513a711e4fc57742e2615e02be702a11bc7d2;p=thirdparty%2Fpdns.git Docs --- diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index 851f849ecb..ec17629a36 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -917,6 +917,7 @@ Novell nproxy NPTL NSes +NSID nsid nsis nsrecord @@ -1016,9 +1017,9 @@ pickchashed pickclosest pickhashed picknamehashed -pickselfweighted pickrandom pickrandomsample +pickselfweighted pickwhashed pickwrandom piddir @@ -1498,6 +1499,7 @@ versionmodified Viala viewcode visitedlinkcolor +Vixie vixie vla Voegeli diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index ce51884240..8b5c147ee7 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -46,7 +46,7 @@ make -nwk | /path/to/compiledb -o- > compile_commands.json to generate the compilation database. For the authoritative server, the configure command is run in the top level directory, while the compiledb command should be run in the `pdns` subdirectory. -# Seting up the LSP client +# Setting up the LSP client Once the compilation database is generated, you can now move onto setting up an LSP client in your editor or IDE. diff --git a/pdns/recursordist/rec-rust-lib/docs-new-preamble-in.rst b/pdns/recursordist/rec-rust-lib/docs-new-preamble-in.rst index 0220b5de17..7723373f06 100644 --- a/pdns/recursordist/rec-rust-lib/docs-new-preamble-in.rst +++ b/pdns/recursordist/rec-rust-lib/docs-new-preamble-in.rst @@ -536,6 +536,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 ----------------- diff --git a/pdns/recursordist/rec-rust-lib/generate.py b/pdns/recursordist/rec-rust-lib/generate.py index cf9dfd1ea8..b9ec2a71fc 100644 --- a/pdns/recursordist/rec-rust-lib/generate.py +++ b/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): diff --git a/pdns/recursordist/rec-rust-lib/table.py b/pdns/recursordist/rec-rust-lib/table.py index dbdcd4867a..93600481b8 100644 --- a/pdns/recursordist/rec-rust-lib/table.py +++ b/pdns/recursordist/rec-rust-lib/table.py @@ -3210,8 +3210,8 @@ IP address for the webserver to listen on. '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', @@ -3252,35 +3252,12 @@ Note that this option only applies to credentials stored in the configuration as '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 Not Found

Not Found

- [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.