VXVX Docs

DNS

DnsConfig, servers, and hijacking

DNS is configured in ServerConfig.dns (DnsConfig). Schema definition: protos/proto/vx/dns/dns.proto.

dnsServers defines named upstreams; concurrentDnsServers / serialDnsServers can combine multiple upstreams into new named servers; internalResolver and requestDomainResolver reference these servers by name. dnsHijack selects the upstream for hijacked DNS queries.

DnsConfig

records
Record[]

Static domain records answered by the local static server before querying other upstreams.

recordStrings
string[]

Static records in standard DNS RR text format (e.g. www.example.com. 3600 IN A 192.0.2.1), equivalent to records and convenient for pasting full record lines.

dnsServers
DnsServerConfig[]

Named DNS upstream definitions. Each must have a unique name and one server type (type oneof).

internalResolver
Resolver

Resolver used to resolve domains when dialing outbounds.

requestDomainResolver
Resolver

Resolver used by the router and dispatcher to resolve request domains.

concurrentDnsServers
ConcurrentDnsServer[]

Combine multiple defined DNS servers into a new named server by querying them in parallel.

serialDnsServers
SerialDnsServer[]

Combine multiple defined DNS servers into a new named server by trying them in order.

dnsHijack
DnsHijackConfig

DNS hijacking.

Record

domain
string

Hostname

ip
string[]

Static IP answers. IPv4 produces A records; IPv6 produces AAAA records.

proxiedDomain
string

When non-empty, produce a CNAME to proxiedDomain for this domain instead of returning ip directly.

Resolver

Resolvers reference DnsServerConfig, ConcurrentDnsServer, or SerialDnsServer by name from dnsServers. Multiple names are tried serially in order.

dnsServers
string[]

List of named DNS servers to use

interval
uint32

Wait time between queries when trying serially (seconds)

name
string

Resolver name

ConcurrentDnsServer

dnsServers
string[]

Names of DNS servers to query in parallel

name
string

Name of the combined server, referenced by Resolver.dnsServers and DnsRuleConfig.dnsServerName

SerialDnsServer

dnsServers
string[]

Names of DNS servers to try in order

interval
uint32

How long to wait before trying the next server after the current one fails (seconds)

name
string

Name of the combined server

DnsServerConfig

Each server has a unique name.

Only one of plainDnsServer, tlsDnsServer, dohDnsServer, quicDnsServer, fakeDnsServer, goDnsServer, or emptyDnsServer may be set.

name
string

Server name; referenced by resolvers, combined servers, and DNS rules

Do not use hijack as a name

plainDnsServer
PlainDnsServer

Traditional UDP DNS (TCP optional)

tlsDnsServer
TlsDnsServer

DNS over TLS (DoT)

dohDnsServer
DohDnsServer

DNS over HTTPS (DoH)

quicDnsServer
QuicDnsServer

DNS over QUIC (DoQ)

fakeDnsServer
FakeDnsServer

Fake IP pool that assigns fake addresses to matching domains

goDnsServer
GoDnsServer

Go standard library system resolver

emptyDnsServer
EmptyDnsServer

Empty resolver that returns no upstream results

clientIp
string

Client IP sent in EDNS Client Subnet (ECS)

cacheDuration
uint32

Answer cache duration (seconds). When 0, the minimum TTL from the answer is used.

ipTags
string[]

Keep only answer addresses that fall within these geo IP sets; other IPs are discarded

PlainDnsServer

addresses
string[]

Upstream addresses in host:port format (typically port 53)

useDefaultDns
bool

When true, use DNS servers on the system default interface; updates automatically when interface DNS changes. Falls back to addresses when no system DNS is available.

TlsDnsServer

addresses
string[]

DoT upstream addresses in host:port format (typically port 853)

DohDnsServer

url
string

DoH endpoint URL (e.g. https://dns.google/dns-query)

QuicDnsServer

address
string

DoQ upstream address (host:port)

FakeDnsServer

poolConfigs
PoolConfig[]

Fake IP address pool configuration. Avoid configuring multiple overlapping pools for the same IP version (IPv4 / IPv6).

PoolConfig

cidr
string

CIDR for the fake IP pool (e.g. 198.18.0.0/15)

lruSize
uint32

LRU capacity for domain → fake IP mappings in the pool

GoDnsServer

Uses the operating system / Go default resolution path. Its traffic does not go through the dispatcher and is sent directly. This type is typically used on the server side.

EmptyDnsServer

Always returns an empty resolution.

DnsHijackConfig

dnsRules
DnsRuleConfig[]

Route hijacked DNS requests to a specified dnsServerName by domain, set, and query type. Rules are matched in order.

When this configuration is present, a DNS server named hijack is added automatically. A dns outbound is also added so you can specify the dns outbound in routing rules to hijack DNS traffic.

DnsRuleConfig

dnsServerName
string

Target DnsServerConfig.name (or combined server name)

geoDomains
Domain[]

Match query names

domainTags
string[]

Match query names belonging to these geo domain sets

includedTypes
DnsType[]

Restrict query types.

ruleName
string

Label for debugging and display

DnsType

DNS query type enum defined in proto, including DnsType_A, DnsType_AAAA, DnsType_CNAME, DnsType_HTTPS, DnsType_ANY, etc.

Example

Static records + direct DoH + hijack rules:

{
  "dns": {
    "records": [
      { "domain": "internal.example", "ip": ["10.0.0.1"] }
    ],
    "dnsServers": [
      {
        "name": "doh",
        "dohDnsServer": { "url": "https://dns.google/dns-query" }
      }
    ],
    "internalResolver": {
      "dnsServers": ["doh"]
    },
    "requestDomainResolver": {
      "dnsServers": ["doh"]
    },
    "dnsHijack": {
      "enableFakeDns": true,
      "dnsRules": [
        {
          "dnsServerName": "doh",
          "domainTags": ["gfw"],
          "includedTypes": ["DnsType_A", "DnsType_AAAA"],
          "ruleName": "proxy-dns"
        }
      ]
    }
  }
}
  • Geo — domainTags, ipTags on rules and servers
  • Router — fakeIp and domain resolution rules
  • Dialer factory — useInternalResolver

Comments

On this page

DnsConfigRecordResolverConcurrentDnsServerSerialDnsServerDnsServerConfigPlainDnsServerTlsDnsServerDohDnsServerQuicDnsServerFakeDnsServerPoolConfigGoDnsServerEmptyDnsServerDnsHijackConfigDnsRuleConfigDnsTypeExampleRelated