recursor

README

recursor - CoreDNS Plugin

The recursor resolves domains using defined IP addresses or resolving other mapped domains using defined resolvers.

Use Case

Config Syntax / Examples

The recursor configuration includes the following definitions:

• verbose: The logging level for stdout:
  • 0: minimal logging
  • 1: moderate logging
  • 2: detailed logging
• resolvers: Other DNS servers to use:
  • map-key/id: The name of the resolver. The default overrides the system's default resolver.
  • urls: A list of URL addresses, e.g., udp://127.0.0.1:53 (the system default is represented by ://default).
  • timeout_ms: The connection timeout for the resolver, in milliseconds.
• aliases: Domain aliases:
  • map-key/id: The alias name, a subdomain, or * if you want the recursor to act as a DNS repeater.
  • ips: A list of IP addresses to be returned as part of the response.
  • hosts: Domains that will be resolved, with the resulting IP addresses returned in the response.
  • shuffle_ips: Default is false. If set to true, IP addresses will be returned in random order. Deprecated, use ips_transform instead.
  • ips_transform: A list of transformations applied sequentially to the list of IP addresses before returning them. Default: empty (no transformation). Unknown functions are ignored. Supported functions (applied in order):
    • shuffle: randomizes the order of addresses
    • sort_asc: sorts addresses in ascending binary order
    • sort_desc: sorts addresses in descending binary order
    • first: keeps only the first address (if any)
    • last: keeps only the last address (if any)
    • random_one: keeps exactly one random address (if any)
    • prefer_ipv4: stable-partitions list to place IPv4 first
    • prefer_ipv6: stable-partitions list to place IPv6 first
    • limit_n: keeps only the first n addresses (e.g., limit_2). n≥0, n=0 yields an empty list.
  • ttl: Time To Live for the DNS record, in seconds.
  • resolver_name: The name of the resolver to use. The default is... well, default, of course :)
  • ttl: Time To Live for the DNS record, in seconds.

Corefile

recursor {   
    [external-yaml config-file-path]
    [external-json config-file-path]

    [verbose 0..2]
    resolver dns-c {
        urls udp://1.1.1.1:53 udp://1.0.0.1:53
        timeout_ms 500
    }
    resolver dns-g {
        urls udp://8.8.8.8:53 udp://8.8.4.4:53
    }  
    resolver demo {
        urls udp://10.0.0.1:53
    }  
    alias alias1 {
        hosts www.example.org www.example.com
        ips_transform shuffle first
        resolver_name dns-c
        ttl 11
    }
    alias alias2 {
        ips 10.0.0.1 10.0.0.2
        ttl 12
    }
    alias alias3 {
        ips 10.0.0.1 10.0.0.2
        hosts www.example.net
        resolver_name dns-g
        ttl 13
    }
    alias alias4 {
        hosts www.example.net
        ttl 14
    }  

    alias * {
        resolver_name demo
        ttl 15
    }  
}

External YAML

        resolvers:
          dns-c:
            urls: [ udp://1.1.1.1:53, udp://1.0.0.1:53 ]
            timeout_ms: 500
          dns-g:
            urls: [ udp://8.8.8.8:53, udp://8.8.4.4:53 ]
          demo:
            urls: [ udp://10.0.0.1:53 ]
        aliases:
          alias1:
            hosts: [ www.example.org, www.example.com ]
            ips_transform: [ shuffle first ]
            resolver_name: dns-c
            ttl: 11
          alias2:
            ips: [ 10.0.0.1, 10.0.0.2 ]
            ttl: 12
          alias3:
            ips: [ 10.0.0.1, 10.0.0.2 ]
            hosts: [ www.example.net ]
            resolver_name: dns-g
            ttl: 13
          alias4:
            hosts: [ www.example.net ]
            ttl: 14
          "*":
            resolver_name: demo
            ttl: 15

External JSON

{
  "resolvers": {
    "dns-c": {
      "urls": [
        "udp://1.1.1.1:53",
        "udp://1.0.0.1:53"
      ],
      "timeout_ms": 500
    },
    "dns-g": {
      "urls": [
        "udp://8.8.8.8:53",
        "udp://8.8.4.4:53"
      ]
    },
    "demo": {
      "urls": [
        "udp://10.0.0.1:53"
      ]
    }
  },
  "aliases": {
    "alias1": {
      "hosts": [
        "www.example.org",
        "www.example.com"
      ],
      "ips_transform": [ "shuffle", "first"  ],
      "resolver_name": "dns-c",
      "ttl": 11
    },
    "alias2": {
      "ips": [
        "10.0.0.1",
        "10.0.0.2"
      ],
      "ttl": 12
    },
    "alias3": {
      "ips": [
        "10.0.0.1",
        "10.0.0.2"
      ],
      "hosts": [
        "www.example.net"
      ],
      "resolver_name": "dns-g",
      "ttl": 13
    },
    "alias4": {
      "hosts": [
        "www.example.net"
      ],
      "ttl": 14
    },
    "*": {
      "resolver_name": "demo",
      "ttl": 15
    }
  }
}

More examples

Metrics

• Definition
• Grafana Dashboard

Run It

Build It

#!/bin/bash eu

# Extract coredns source code
tar xzvf coredns.src.tar.gz
pushd coredns
  # Add external plugins
  go get github.com/kinjelom/coredns-recursor@latest
  grep -q '^recursor:' plugin.cfg || echo -e "recursor:github.com/kinjelom/coredns-recursor" >> plugin.cfg
  # Build
  go generate
  go build
  ./coredns -plugins
popd

Deployments Ready to Use

• BOSH Release

Try it

Helpful commands:

# sudo apt-get install dnsutils
dig alias1.demo.svc @127.0.0.1 -p 1053
nslookup -port=1053 -debug -type=A alias2.demo.svc 127.0.0.1