About

The UDP listener half of the dns-gateway extension set. It intercepts DNS queries for configured domain patterns, allocates a virtual IP from each domain's dedicated CIDR range, and responds with an A record (IPv4 base_ip) or AAAA record (IPv6 base_ip). The application receives this virtual IP and connects to it as if it were the real destination. Non-matching queries pass through to upstream resolvers.

Each allocated virtual IP, its domain, and per-domain metadata are written to a process-wide cache that the companion lookup network filter reads on the subsequent TCP connection. Both filters ship in the same dns-gateway dynamic module, so the cache is shared in-process.

Backward compatibility: this filter is also reachable under the legacy name dns-gateway via --extension dns-gateway --filter-type udp_listener.

Configuration

Field Type Required Description
domains array yes List of domain patterns to intercept
domains[].domain string yes Exact (example.com) or single-level wildcard (*.aws.com)
domains[].base_ip string yes Base address of the virtual IP CIDR range. IPv4 (e.g. 10.0.0.0, answered as an A record) or IPv6 (e.g. fd00::, answered as an AAAA record)
domains[].prefix_len integer yes CIDR prefix length. IPv4: 1–32 (a /24 gives 256 virtual IPs). IPv6: 1–128 (a /64 gives 2^64 virtual IPs)
domains[].metadata object no String key-value pairs propagated to filter state
fail_open boolean no If true, forward queries upstream when a CIDR range is exhausted. Default: false (return NODATA)

Prerequisites

Requires iptables/nftables rules to redirect DNS (UDP port 53) to Envoy's DNS listener.

Usage Examples

Single Wildcard Domain

Intercept DNS queries for *.aws.com, allocating virtual IPs from a dedicated /24 range. Pair with the lookup network filter so TCP connections to those virtual IPs resolve back to the original domain and metadata via the shared cache.

boe run \
  --extension dns-gateway/resolver --config '
    {
      "domains": [
        {
          "domain": "*.aws.com",
          "base_ip": "10.0.0.0",
          "prefix_len": 24,
          "metadata": {
            "cluster": "aws_cluster"
          }
        }
      ]
    }' \
  --extension dns-gateway/lookup

Multiple Domains with Routing Metadata

Route different domain patterns to different upstream clusters using per-domain metadata. Downstream filters can read the domain and metadata from Envoy filter state (written by lookup), e.g. %FILTER_STATE(io.builtonenvoy.dns_gateway.domain:PLAIN)% in a tcp_proxy route.

boe run \
  --extension dns-gateway/resolver --config '
    {
      "domains": [
        {
          "domain": "*.aws.com",
          "base_ip": "10.0.0.0",
          "prefix_len": 24,
          "metadata": {
            "cluster": "aws_cluster",
            "token": "abc123"
          }
        },
        {
          "domain": "example.com",
          "base_ip": "10.0.1.0",
          "prefix_len": 24,
          "metadata": {
            "cluster": "example_cluster",
            "token": "def456"
          }
        }
      ]
    }' \
  --extension dns-gateway/lookup