eBPF functions and objects

These are all the functions, objects and methods related to the eBPF Socket Filtering.

addBPFFilterDynBlocks(addresses, dynbpf[[, seconds=10], msg])

This is the eBPF equivalent of 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. Since 1.6.0, the use of a DynBlockRulesGroup is a much more efficient way of doing the same thing.

Parameters:
  • addresses – set of Addresses as returned by an exceed function
  • dynbpf (DynBPFFilter) – The dynamic eBPF filter to use
  • seconds (int) – The number of seconds this block to expire
  • msg (str) – A message to display while inserting the block
newBPFFilter(options) → BPFFilter
newBPFFilter(v4Parameters, v6Parameters, qnamesParameters) -> BPFFilter (1.7.x)
newBPFFilter(maxV4, maxV6, maxQNames) -> BPFFilter (before 1.7.0)

Changed in version 1.7.0: This function now supports a table for each parameters, and the ability to use pinned eBPF maps.

Changed in version 1.8.0: This function now gets its parameters via a table.

Return a new eBPF socket filter with a maximum of maxV4 IPv4, maxV6 IPv6 and maxQNames qname entries in the block tables. Maps can be pinned to a filesystem path, which makes their content persistent across restarts and allows external programs to read their content and to add new entries. dnsdist will try to load maps that are pinned to a filesystem path on startups, inheriting any existing entries, and fall back to creating them if they do not exist yet. Note that the user dnsdist is running under must have the right privileges to read and write to the given file, and to go through all the directories in the path leading to that file. The pinned path must be on a filesystem of type BPF, usually below /sys/fs/bpf/.

Parameters:options (table) – A table with key: value pairs with options.

Options:

  • ipv4MaxItems: int - The maximum number of entries in the IPv4 map. Default is 0 which will not allow any entry at all.
  • ipv4PinnedPath: str - The filesystem path this map should be pinned to.
  • ipv6MaxItems: int - The maximum number of entries in the IPv6 map. Default is 0 which will not allow any entry at all.
  • ipv6PinnedPath: str - The filesystem path this map should be pinned to.
  • cidr4MaxItems: int - The maximum number of entries in the IPv4 range block map. Default is 0 which will not allow any entry at all.
  • cidr4PinnedPath: str - The filesystem path this map should be pinned to.
  • cidr6MaxItems: int - The maximum number of entries in the IPv6 range block map. Default is 0 which will not allow any entry at all.
  • cidr6PinnedPath: str - The filesystem path this map should be pinned to.
  • qnamesMaxItems: int - The maximum number of entries in the qname map. Default is 0 which will not allow any entry at all.
  • qnamesPinnedPath: str - The filesystem path this map should be pinned to.
  • external: bool - If set to true, DNSDist does not load the internal eBPF program.
newDynBPFFilter(bpf) → DynBPFFilter

Return a new dynamic eBPF filter associated to a given BPF Filter.

Parameters:bpf (BPFFilter) – The underlying eBPF filter
setDefaultBPFFilter(filter)

When used at configuration time, the corresponding BPFFilter will be attached to every bind.

Parameters:filter (BPFFilter) – The filter to attach
registerDynBPFFilter(dynbpf)
Register a DynBPFFilter filter so that it appears in the web interface and the API.
Parameters:dynbpf (DynBPFFilter) – The dynamic eBPF filter to register
unregisterDynBPFFilter(dynbpf)
Remove a DynBPFFilter filter from the web interface and the API.
Parameters:dynbpf (DynBPFFilter) – The dynamic eBPF filter to unregister
class BPFFilter

Represents an eBPF filter

:attachToAllBinds()

Attach this filter to every bind already defined. This is the run-time equivalent of setDefaultBPFFilter(). This method can be used at run-time only.

:block(address)

Block this address

Parameters:address (ComboAddress) – The address to block
:addRangeRule(Netmask, action[, force=false])

New in version 1.8.0.

Block all IP addresses in this range.

DNSDist eBPF code first checks if an exact IP match is found, then if a range matches, and finally if a DNSName does.

Parameters:
  • Netmask (string) – The ip range to block, allow or truncate
  • action (int) – set action to 0 to allow a range, set action to 1 to block a range, set action to 2 to truncate a range.
  • force (bool) – When force is set to true, DNSDist always accepts adding a new item to BPF maps, even if the item to be added may already be included in the larger network range.
:blockQName(name[, qtype=255])

Block queries for this exact qname. An optional qtype can be used, defaults to 255.

Parameters:
  • name (DNSName) – The name to block
  • qtype (int) – QType to block
:getStats()

Print the block tables.

:unblock(address)

Unblock this address.

Parameters:address (ComboAddress) – The address to unblock
:rmRangeRule(Netmask)

New in version 1.8.0.

Parameters:string (Netmask) – The rule you want to remove
:lsRangeRule()

New in version 1.8.0.

List all range rule.

:unblockQName(name[, qtype=255])

Remove this qname from the block list.

Parameters:
  • name (DNSName) – the name to unblock
  • qtype (int) – The qtype to unblock
class DynBPFFilter

Represents an dynamic eBPF filter, allowing the use of ephemeral rules to an existing eBPF filter. Note that since 1.6.0 the default BPF filter set via setDefaultBPFFilter() will automatically be used by a DynBlockRulesGroup, becoming the preferred way of dealing with ephemeral rules.

:purgeExpired()

Remove the expired ephemeral rules associated with this filter.

:excludeRange(netmasks)

Exclude this range, or list of ranges, meaning that no dynamic block will ever be inserted for clients in that range. Default to empty, meaning rules are applied to all ranges. When used in combination with DynBPFFilter:includeRange(), the more specific entry wins.

Parameters:or list of str netmasks (str) – A netmask, or list of netmasks, as strings, like for example “192.0.2.1/24”
:includeRange(netmasks)

Include this range, or list of ranges, meaning that rules will be applied to this range. When used in combination with DynBPFFilter:excludeRange(), the more specific entry wins.

Parameters:or list of str netmasks (str) – A netmask, or list of netmasks, as strings, like for example “192.0.2.1/24”