From bd51e34cbbc999faa4878e002fe8275d8a4b9c4e Mon Sep 17 00:00:00 2001 From: Remi Gacogne Date: Thu, 30 Nov 2017 12:57:37 +0100 Subject: [PATCH] dnsdist: Add missing documentation about ClientState, eBPF dynamic filters --- pdns/dnsdistdist/docs/advanced/ebpf.rst | 6 +++ pdns/dnsdistdist/docs/reference/config.rst | 48 ++++++++++++++++++++++ pdns/dnsdistdist/docs/reference/ebpf.rst | 39 +++++++++++++++++- 3 files changed, 92 insertions(+), 1 deletion(-) diff --git a/pdns/dnsdistdist/docs/advanced/ebpf.rst b/pdns/dnsdistdist/docs/advanced/ebpf.rst index d0fe4c495..1b853145c 100644 --- a/pdns/dnsdistdist/docs/advanced/ebpf.rst +++ b/pdns/dnsdistdist/docs/advanced/ebpf.rst @@ -54,4 +54,10 @@ Finally, it's also possible to attach it to specific binds at runtime:: This will dynamically block all hosts that exceeded 20 queries/s as measured over the past 10 seconds, and the dynamic block will last for 60 seconds. +The dynamic eBPF blocks and the number of queries they blocked can be seen in the web interface and retrieved from the API. Note however that eBPF dynamic objects need to be registered before they appear in the web interface or the API, using the :func:`registerDynBPFFilter` function:: + + registerDynBPFFilter(dbpf) + +They can be unregistered at a later point using the :func:`unregisterDynBPFFilter` function. + This feature has been successfully tested on Arch Linux, Arch Linux ARM, Fedora Core 23 and Ubuntu Xenial diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index 80cd1bf4b..b8f5f08f8 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -22,6 +22,7 @@ Within dnsdist several core object types exist: * :class:`QPSLimiter`: implements a QPS-based filter * :class:`SuffixMatchNode`: represents a group of domain suffixes for rapid testing of membership * :class:`DNSHeader`: represents the header of a DNS packet +* :class:`ClientState`: sometimes also called Bind or Frontend, represents the addresses and ports dnsdist is listening on The existence of most of these objects can mostly be ignored, unless you plan to write your own hooks and policies, but it helps to understand an expressions like: @@ -459,6 +460,53 @@ See :doc:`../guides/cache` for a how to. Return the number of entries in the Packet Cache, and the maximum number of entries +Client State +------------ + +Also called frontend or bind, the Client State object returned by :func:`getBind` and listed with :func:`showBinds` represents an address and port dnsdist is listening on. + +.. function:: getBind(index) -> ClientState + + Return a ClientState object. + + :param int index: The object index + +ClientState functions +~~~~~~~~~~~~~~~~~~~~~ + +.. class:: ClientState + + This object represents an address and port dnsdist is listening on. When ``reuseport`` is in use, several ClientState objects can be present for the same address and port. + +.. classmethod:: Server:addPool(pool) + + Add this server to a pool. + + :param str pool: The pool to add the server to + +.. classmethod:: ClientState:attachFilter(filter) + + Attach a BPF filter to this frontend. + + :param BPFFilter filter: The filter to attach to this frontend + +.. classmethod:: ClientState:detachFilter() + + Remove the BPF filter associated to this frontend, if any. + +.. classmethod:: ClientState:toString() -> string + + Return the address and port this frontend is listening on. + + :returns: The address and port this frontend is listening on + +Attributes +~~~~~~~~~~ + +.. attribute:: ClientState.muted + + If set to true, queries received on this frontend will be normally processed and sent to a backend if needed, but no response will be ever be sent to the client over UDP. TCP queries are processed normally and responses sent to the client. + Status, Statistics and More --------------------------- diff --git a/pdns/dnsdistdist/docs/reference/ebpf.rst b/pdns/dnsdistdist/docs/reference/ebpf.rst index 6e7de064f..2c34c4d6d 100644 --- a/pdns/dnsdistdist/docs/reference/ebpf.rst +++ b/pdns/dnsdistdist/docs/reference/ebpf.rst @@ -3,6 +3,15 @@ eBPF functions and objects These are all the functions, objects and methods related to the :doc:`../advanced/ebpf`. +.. function:: addBPFFilterDynBlocks(addresses, dynbpf[, seconds=10]) + + This is the eBPF equivalent of :func:`addDynBlocks`, blocking a set of addresses for (optionally) a number of seconds, using an eBPF dynamic filter. + The default number of seconds to block for is 10. + + :param addresses: set of Addresses as returned by an exceed function + :param DynBPFFilter: The dynamic eBPF filter to use + :param int seconds: The number of seconds this block to expire + .. function:: newBPFFilter(maxV4, maxV6, maxQNames) -> BPFFilter Return a new eBPF socket filter with a maximum of maxV4 IPv4, maxV6 IPv6 and maxQNames qname entries in the block table. @@ -11,11 +20,29 @@ These are all the functions, objects and methods related to the :doc:`../advance :param int maxV6: Maximum number of IPv6 entries in this filter :param int maxQNames: Maximum number of QName entries in this filter +.. function:: newDynBPFFilter(bpf) -> DynBPFFilter + + Return a new dynamic eBPF filter associated to a given BPF Filter. + + :param BPFFilter bpf: The underlying eBPF filter + .. function:: setDefaultBPFFilter(filter) When used at configuration time, the corresponding BPFFilter will be attached to every bind. - :param BPFFilter filter: The filter ro attach + :param BPFFilter filter: The filter to attach + +.. function:: registerDynBPFFilter(dynbpf) + + Register a DynBPFFilter filter so that it appears in the web interface and the API. + + :param DynBPFFilter dynbpf: The dynamic eBPF filter to register + +.. function:: unregisterDynBPFFilter(dynbpf) + + Remove a DynBPFFilter filter from the web interface and the API. + + :param DynBPFFilter dynbpf: The dynamic eBPF filter to unregister .. class:: BPFFilter @@ -55,3 +82,13 @@ These are all the functions, objects and methods related to the :doc:`../advance :param DNSName name: the name to unblock :param int qtype: The qtype to unblock + +.. class:: DynBPFFilter + + Represents an dynamic eBPF filter, allowing the use of ephemeral rules to an existing eBPF filter. + +.. classmethod:: BPFFilter:purgeExpired() + + Remove the expired ephemeral rules associated with this filter. + + -- 2.40.0