Configuration

Configuration

Settings file

~/.config/natbench/settings.json — created automatically by the GUI on close.

{
  "geometry": "1400x850+100+50",
  "theme": "dark",
  "lang": "de",
  "font_size": 10,
  "col_widths": {
    "rank": 42,
    "name": 200,
    "ip": 130
  },
  "sash_x": 280
}

Delete this file to reset all GUI preferences.

Run history

~/.config/natbench/history.json — the median latency from the last benchmark run, keyed by server name. Used to show ↑/↓ delta arrows in the results table.

{
  "Cloudflare Primary": 5.21,
  "Google Primary": 6.83,
  "dns.wonx.eu": 1.42
}

Profiles

Profiles store a list of selected server names so you can switch between different test sets quickly.

GUI: Profiles tab → Save current selection → name it → Load later.

File format (~/.config/natbench/profiles/<name>.json):

{
  "name": "My Region",
  "description": "Servers from DE + AT",
  "servers": ["Cloudflare Primary", "Google Primary", "dns.wonx.eu"],
  "vpn": false,
  "source": "manual"
}

Plugin system

Plugins are Python files placed in ~/.config/natbench/plugins/.

A plugin must declare PLUGIN_API_VERSION = "1.0" and implement one or more plugin classes.

Source plugin (add custom servers)

PLUGIN_API_VERSION = "1.0"

class MySourcePlugin:
    plugin_type = "source"
    name = "My Servers"

    def get_servers(self):
        return [
            {
                "name": "My DNS",
                "ip4": "192.168.1.1",
                "port": 53,
                "tags": ["fast"],
                "description_en": "My local resolver",
            }
        ]

Filter plugin (exclude servers)

PLUGIN_API_VERSION = "1.0"

class GeoFilter:
    plugin_type = "filter"
    name = "EU Only"

    def filter(self, servers):
        eu = {"DE", "AT", "CH", "NL", "FR", "GB", "SE", "NO"}
        return [s for s in servers if s.get("country", "") in eu]

Exporter plugin (custom output format)

PLUGIN_API_VERSION = "1.0"

class InfluxExporter:
    plugin_type = "exporter"
    name = "InfluxDB Line Protocol"
    extension = "influx"

    def export(self, results, path):
        with open(path, "w") as f:
            for r in results:
                f.write(f"dns_benchmark,server={r.name} median={r.median_ms}\n")