eBPF DNS

Plugin: ebpf-go.plugin Module: dns

Overview

Monitor DNS query and response traffic at the kernel level, broken down by transport protocol (UDP/TCP) and IP family (IPv4/IPv6). Data is exposed through the on-demand dns-queries function consumed by the network-viewer.

Attach a BPF socket filter to a raw AF_PACKET socket to capture and count DNS packets on port 53 (standard DNS) and port 5353 (mDNS). The filter runs entirely in the kernel; only per-packet counters are copied to userspace.

This collector is only supported on the following platforms:

• Linux

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

The plugin needs setuid because it loads data inside the kernel. Netdata sets the necessary permissions during installation.

Default Behavior

Auto-Detection

The plugin checks kernel compilation flags (CONFIG_KPROBES, CONFIG_BPF, CONFIG_BPF_SYSCALL, CONFIG_BPF_JIT) and selects the best available BPF object flavor (arena, buffer, or base) for the running kernel.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The BPF socket filter runs in the kernel for every received Ethernet frame. Overhead is proportional to DNS traffic volume and is negligible on typical hosts.

Setup

Prerequisites

Compile kernel

Check if your kernel was compiled with necessary options (CONFIG_KPROBES, CONFIG_BPF, CONFIG_BPF_SYSCALL, CONFIG_BPF_JIT) in /proc/config.gz or inside /boot/config file. Some cited names can be different according to the preferences of Linux distributions. When you do not have options set, it is necessary to get the kernel source code from https://kernel.org or a kernel package from your distribution, this last is preferred. The kernel compilation has a well defined pattern, but distributions can deliver their configuration files with different names.

Now follow steps:

1. Copy the configuration file to /usr/src/linux/.config.
2. Select the necessary options: make oldconfig
3. Compile your kernel image: make bzImage
4. Compile your modules: make modules
5. Copy your new kernel image for boot loader directory
6. Install the new modules: make modules_install
7. Generate an initial ramdisk image (initrd) if it is necessary.
8. Update your boot loader

Configuration

Options

The dns option in section [ebpf programs] controls whether the module is loaded. Per-module overrides (update every, ebpf object flavor, per query tracking, flow ttl) belong in ebpf.d/dns.conf.

Config options

Option	Description	Default	Required
dns	Enable (yes) or disable (no) the DNS monitoring module.	no	no
update every	Data collection frequency in seconds.	10	no
ebpf object flavor	Select the BPF object flavor. Available values are arena, buffer ring (also accepted as buffer), and legacy (also accepted as tracing). The collector falls back to the next available flavor when the requested one is not supported by the running kernel.	buffer	no
per query tracking	Enable per-DNS-query latency tracking. When enabled (yes), the collector records the time between each DNS request and its matching response, producing per-query latency metrics. Required for the dns-queries Function consumed by network-viewer.plugin.	yes	no
flow ttl	DNS flow record lifetime in seconds. Must equal NV_DNS_UPDATE_EVERY (20) in network-viewer.c: a value greater than 20 causes double-counting and a value less than 20 causes silent record loss in the dns-queries Function. Also, update every must not exceed this value or records expire in the kernel ring before collection.	20	no

via File

The configuration file name for this integration is ebpf.d.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config ebpf.d.conf

Examples

There are no configuration examples.

Alerts

There are no alerts configured by default for this integration.

Metrics

The DNS module does not publish standalone Netdata charts. It writes DNS flow data to a POSIX shared-memory segment; the network-viewer.plugin reads that segment and registers the dns-queries on-demand function (FUNCTIONGLOBAL).

The function returns a table with one row per DNS query/response transaction (not an aggregate). Each row represents one captured DNS exchange from the ring buffer maintained by ebpf-go.plugin.

dns-queries function columns

Column	Description
Domain	Queried domain name
QueryType	DNS query type (A, AAAA, MX, etc.)
Transport	Transport protocol (UDP or TCP)
IPFamily	IP family (IPv4 or IPv6)
ServerIP	DNS server IP address
Latency	Query-to-response latency (seconds)
Status	Query completion status (OK or Timeout)
RCode	DNS response code (NOERROR, NXDOMAIN, SERVFAIL, etc.)