<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/ebpf.plugin/ebpfgo.plugin/integrations/ebpf_dns.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/ebpf.plugin/ebpfgo.plugin/metadata.yaml"
sidebar_label: "eBPF DNS"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Collectors/Operating Systems"
keywords: ['DNS', 'mDNS', 'Network monitoring', 'eBPF']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
endmeta-->

# eBPF DNS


<img src="https://netdata.cloud/img/ebpf.jpg" width="150"/>


Plugin: ebpf-go.plugin
Module: dns

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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`.


<details open><summary>Config options</summary>



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


</details>



#### via File

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


You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
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.) |
