Transport

Active contributors: johnbelamaric, miekg, ykhr53, inigohu, mqasimsarfraz, yongtang

Purpose

These plugins control how the server listens. Where most plugins handle individual queries, the transport plugins set listener-level options on the Config so the appropriate Server constructor (DoT, DoH, DoQ, gRPC) picks them up.

Plugins in this group

Plugin	Source	One-liner
bind	plugin/bind/	Restrict the server to listen on specific addresses
tls	plugin/tls/	Build the *tls.Config consumed by encrypted servers
https	plugin/https/	Caps for the DoH server (MaxHTTPSConnections)
https3	plugin/https3/	Caps for the DoH3 server (MaxHTTPS3Streams)
quic	plugin/quic/	Caps for the DoQ server (MaxQUICStreams, worker pool)
grpc_server	plugin/grpc_server/	Caps for the gRPC server (MaxGRPCStreams, MaxGRPCConnections)
proxyproto	plugin/proxyproto/	PROXY protocol policy and (optional) UDP session tracking
multisocket	plugin/multisocket/	Spin up multiple parallel listeners on the same port
timeouts	plugin/timeouts/	Override read/write/idle timeouts on TCP-style servers
bufsize	plugin/bufsize/	Override the EDNS0 UDP buffer size advertised by clients
nsid	plugin/nsid/	Add an NSID OPT record (RFC 5001) to responses

How they're consumed

graph LR
    Setup[plugin setup] --> Config[Config struct]
    Config --> NewServer[NewServer / NewServerTLS / NewServerHTTPS / ...]
    NewServer --> Listen[reuseport.Listen]
    Listen --> Wrappers[proxyproto / TLS / netutil.LimitListener]
    Wrappers --> Run[Serve / ServeHTTP / streamLoop]

These plugins do not return a meaningful Handler.ServeDNS (or use a thin pass-through). Their effect is on Config. The Server constructors read the Config fields when they're created in MakeServers and produce listeners shaped accordingly.

Plugins in detail

bind

Restricts the server to one or more host addresses. By default Config.ListenHosts is [""] (wildcard); bind replaces it. Supports IPv6 link-local with zones and per-zone-block lists.

tls

Reads cert, key, and (optionally) CA arguments and constructs a *tls.Config via plugin/pkg/tls. Stores the result on Config.TLSConfig. The five encrypted server types (ServerTLS, ServerHTTPS, ServerHTTPS3, ServerQUIC, ServergRPC) all clone this config in MakeServers (propagateConfigParams).

The plugin enforces single-use per server block.

https, https3, quic, grpc_server

Each of these is a thin Caddyfile parser that sets the corresponding Max* field on Config:

• https → MaxHTTPSConnections
• https3 → MaxHTTPS3Streams
• quic → MaxQUICStreams, MaxQUICWorkerPoolSize
• grpc_server → MaxGRPCStreams, MaxGRPCConnections

Defaults live in the constructor in core/dnsserver/server_*.go. See Transports for the table.

proxyproto

Handles HAProxy/Cloudflare PROXY protocol on the listener. Sets ProxyProtoConnPolicy (a function that decides per-incoming-connection what to do) and the optional ProxyProtoUDPSessionTrackingTTL / ProxyProtoUDPSessionTrackingMaxSessions. The TCP path uses pires/go-proxyproto.Listener; the UDP path uses plugin/pkg/proxyproto, which adds an LRU keyed by Spectrum-side remote address so subsequent UDP datagrams keep their real client IP.

multisocket

Sets Config.NumSockets. makeServersForGroup then instantiates NumSockets parallel servers on the same listen address using SO_REUSEPORT. On Linux this distributes UDP receive load across multiple goroutines and CPUs. Has no effect on macOS or BSD.

timeouts

Sets Config.ReadTimeout, Config.WriteTimeout, Config.IdleTimeout. Affects plain DNS over TCP, DoT, DoH, DoH3 (some), and DoQ (where applicable).

bufsize

Walks every incoming request and rewrites the EDNS0 OPT buffer size. Defends against UDP fragmentation by pinning the size below a known fragmentation-safe limit.

nsid

Appends an NSID OPT option to outgoing responses (RFC 5001). Useful for identifying which CoreDNS instance answered when behind a load balancer.

Cross-plugin notes

• tls is required for any encrypted scheme (DoT/DoH/DoH3/DoQ/gRPC). Setup will refuse to start without it.
• multisocket interacts with proxyproto UDP session tracking — each socket has its own session cache.
• bind and proxyproto are routinely combined with cloud load balancers (the load balancer terminates TCP and forwards the original client IP via PROXY protocol).

Key source files

File	Purpose
plugin/bind/bind.go	Listen-host restriction
plugin/tls/tls.go	TLS config builder
plugin/https/setup.go, plugin/https3/setup.go, plugin/quic/setup.go, plugin/grpc_server/setup.go	Caps for each encrypted server
plugin/proxyproto/setup.go	PROXY protocol policy
plugin/multisocket/setup.go	NumSockets
plugin/timeouts/setup.go	TCP timeouts
plugin/bufsize/setup.go	EDNS0 buffer size
plugin/nsid/setup.go	NSID OPT
plugin/pkg/transport/	Default ports/scheme strings
plugin/pkg/reuseport/	SO_REUSEPORT listeners
plugin/pkg/tls/	Shared *tls.Config builder
plugin/pkg/proxyproto/	UDP PROXY protocol
core/dnsserver/server_*.go	Server constructors that consume these settings

Related pages

• Transports — server-side lifecycle of each transport.
• Security — tls is reused by dnssec cooperation.
• Plugin system — these plugins write to Config rather than returning a meaningful handler.