dnsdist: Add more documentation about XPF and the Proxy Protocol

diff --git a/pdns/dnsdistdist/docs/advanced/index.rst b/pdns/dnsdistdist/docs/advanced/index.rst
index f9cc4ace693c5f8eefc084a427fad14cd8d200dc..966cab90f47365c2479c39c4d445b6531b6fee78 100644 (file)
--- a/pdns/dnsdistdist/docs/advanced/index.rst
+++ b/pdns/dnsdistdist/docs/advanced/index.rst
@@ -11,6 +11,8 @@ These chapters contain information on the advanced features of dnsdist
    luaaction
    timedipsetrule
    ecs
+   xpf
+   proxyprotocol
    qpslimits
    ebpf
    tuning

diff --git a/pdns/dnsdistdist/docs/advanced/proxyprotocol.rst b/pdns/dnsdistdist/docs/advanced/proxyprotocol.rst
new file mode 100644 (file)
index 0000000..7ecb3dc
--- /dev/null
+++ b/pdns/dnsdistdist/docs/advanced/proxyprotocol.rst
@@ -0,0 +1,9 @@
+Using the Proxy Protocol
+------------------------
+
+In order to provide the downstream server with the address of the real client, or at least the one talking to dnsdist, the ``useProxyProtocol`` parameter can be used when creating a :func:`new server <newServer>`.
+This parameter indicates whether a Proxy Protocol header should be prepended to the query before forwarding it to the backend, over UDP or TCP. This header contains the initial source and destination addresses and ports, and can also contain several custom values in a Type-Length-Value format. More information about the Proxy Protocol can be found at https://www.haproxy.org/download/2.2/doc/proxy-protocol.txt
+
+Custom values can be added to the header via :meth:`DNSQuestion:setProxyProtocolValues` and :func:`SetProxyProtocolValuesAction`.
+
+As of 1.5.0 only outgoing Proxy Protocol support has been implemented, although support for parsing incoming Proxy Protocol headers will likely be implemented in the future.

diff --git a/pdns/dnsdistdist/docs/advanced/xpf.rst b/pdns/dnsdistdist/docs/advanced/xpf.rst
new file mode 100644 (file)
index 0000000..abe30ce
--- /dev/null
+++ b/pdns/dnsdistdist/docs/advanced/xpf.rst
@@ -0,0 +1,13 @@
+Using XPF
+---------
+
+In order to provide the downstream server with the address of the real client, or at least the one talking to dnsdist, the ``addXPF`` parameter can be used when creating a :func:`new server <newServer>`.
+This parameter indicates whether an experimental XPF record (from `draft-bellis-dnsop-xpf <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_) shall be added to the query. Since that record is experimental, there is currently no option code assigned to it, and therefore one needs to be specified as an argument to the ``addXPF`` parameter.
+
+The XPF record is an alternative to the use of EDNS Client Subnet which has the advantages of preserving any existing EDNS Client Subnet value sent by the client, and of passing along the original destination address, as well as the initial source and destination ports.
+
+If the incoming request already contains a XPF record, it will not be overwritten. Instead a new one will be added to the query and the existing one will be preserved.
+That might be an issue by allowing clients to spoof their source address by adding a forged XPF record to their query. That can be prevented by using a rule to drop incoming queries containing a XPF record (in that example the 65280 option code has been assigned to XPF):
+
+  addAction(RecordsTypeCountRule(DNSSection.Additional, 65280, 1, 65535), DropAction())
+