DNS

Use DNS settings when you want domains in a list to be resolved through a specific DNS server, usually the same VPN that will carry the matching traffic.

On package-based router installs, keen-pbr normally takes care of dnsmasq integration for you. Most users only need to define:

• system_resolver (keep the defaults)
• servers
• rules
• fallback

Configuration

{
  "dns": {
    "system_resolver": {
      "address": "127.0.0.1"
    },
    "servers": [...],
    "rules": [...],
    "fallback": ["google_dns", "quad9"]
  }
}

System Resolver

dns.system_resolver tells keen-pbr how to check dnsmasq state after configuration changes.

On normal router package installs, you usually should not change these settings.

DNS Test Server

dns.dns_test_server is optional. It is mainly useful when you are troubleshooting DNS and want keen-pbr to expose a simple test DNS listener.

{
  "dns": {
    "dns_test_server": {
      "listen": "127.0.0.88:53"
    }
  }
}

When the HTTP API is enabled, you can verify if your DNS works or not via Web UI.

DNS Servers

Each server has a tag, optional type, optional address, and optional detour. DNS server tag values must match ^[a-z][a-z0-9_]*$, be at most 24 characters, and must be unique.

The detour field is useful when a DNS server must be reached through a specific connection, usually the same VPN that will carry the matching traffic.

{
  "dns": {
    "servers": [
      {
        "tag": "vpn_dns",
        "type": "static",
        "address": "10.8.0.1:5353",
        "detour": "vpn"
      },
      {
        "tag": "google_dns",
        "address": "8.8.8.8"
      },
      {
        "tag": "google_dns_v6",
        "address": "[2001:4860:4860::8888]:53"
      },
      {
        "tag": "keenetic_dns",
        "type": "keenetic"
      }
    ]
  }
}

type: keenetic (built-in router DNS via RCI)

On Keenetic routers, type: "keenetic" tells keen-pbr to reuse the router’s current built-in DNS settings automatically.

Rules and behavior:

• At most one dns.servers entry may use type: "keenetic".
• address must not be set for type: "keenetic" (resolved from RCI).
• keen-pbr reads unscoped dns_server = ... entries from the System proxy policy.
• If unscoped encrypted upstreams (DoH/DoT) are present, all of them are used in order.
• Otherwise, all unscoped plaintext upstreams are used in order.
• static_a / static_aaaa entries from the System policy are also propagated to generated dnsmasq config.

How detour works

When detour is set, keen-pbr makes sure DNS queries for that server leave through the selected outbound; keen-pbr would automatically create firewall rule for specified DNS IP and port. This can also affect other clients in your network that trying to contact this DNS server directly.

For example, if vpn_dns has detour: "vpn", then the DNS requests to vpn_dns will also go through vpn.

DNS Rules

Rules map list names to a DNS server tag. Domains from the specified lists are resolved using the specified server.

{
  "dns": {
    "rules": [
      {
        "enabled": true,
        "list": ["my_domains", "remote_list"],
        "server": "vpn_dns"
      }
    ]
  }
}

If enabled is omitted or set to null, the DNS rule is still treated as enabled.

dnsmasq Integration

On packaged router installs, you usually do not need to configure dnsmasq manually.

conf-script=/usr/sbin/keen-pbr generate-resolver-config dnsmasq-nftset

Complete Example

{
  "dns": {
    "servers": [
      {
        "tag": "vpn_dns",
        "address": "10.8.0.1:5353",
        "detour": "vpn"
      },
      {
        "tag": "google_dns",
        "address": "8.8.8.8"
      },
      {
        "tag": "google_dns_v6",
        "address": "[2001:4860:4860::8888]:53"
      }
    ],
    "rules": [
      {
        "list": ["my_domains", "remote_list"],
        "server": "vpn_dns"
      }
    ],
    "fallback": ["google_dns", "quad9"]
  }
}