Struct DnsServer 

pub struct DnsServer { /* private fields */ }

DNS server for overlay networks

Implementations

impl DnsServer

pub fn new(listen_addr: SocketAddr, zone: &str) -> Result<Self, DnsError>

Create a new DNS server for the given zone.

Upstreams for non-overlay forwarding are auto-detected from the host /etc/resolv.conf (loopback/stub filtered, public fallback if empty). Use Self::from_config with DnsConfig::with_upstreams to override.

Errors

Returns DnsError::InvalidName if the zone name is invalid.

pub fn new_with_upstreams( listen_addr: SocketAddr, zone: &str, upstreams: Vec<SocketAddr>, ) -> Result<Self, DnsError>

Create a DNS server with an explicit, already-resolved upstream list.

Bypasses resolv.conf detection entirely — upstreams is used verbatim for the root-zone forwarder. Primarily an internal/testing seam so a stub upstream can be injected without touching the host /etc/resolv.conf.

Errors

Returns DnsError::InvalidName if the zone name is invalid.

pub fn from_config(config: &DnsConfig) -> Result<Self, DnsError>

Create from a DnsConfig

Upstreams follow [resolve_upstreams] precedence: config.upstreams override wins, else filtered /etc/resolv.conf, else public fallback.

Errors

Returns DnsError::InvalidName if the zone name is invalid.

pub fn upstreams(&self) -> &[SocketAddr]

The upstream resolvers this server forwards non-overlay queries to.

pub fn handle(&self) -> DnsHandle

Get a handle for managing DNS records

The handle can be cloned and used to add/remove records even after the server has been started.

pub async fn add_record( &self, hostname: &str, ip: IpAddr, ) -> Result<(), DnsError>

Add a DNS record for a hostname to IP mapping

Creates an A record for IPv4 addresses and an AAAA record for IPv6 addresses.

Errors

Returns DnsError::InvalidName if the hostname is invalid.

pub async fn remove_record(&self, hostname: &str) -> Result<bool, DnsError>

Remove DNS records for a hostname (both A and AAAA)

Errors

Returns DnsError::InvalidName if the hostname is invalid.

pub async fn start(self) -> Result<DnsHandle, DnsError>

Start the DNS server and return a handle for record management

This spawns the DNS server in a background task and returns a handle that can be used to add/remove records while the server is running.

Errors

This method currently always succeeds but returns Result for API consistency.

pub async fn start_background(&self) -> Result<DnsHandle, DnsError>

Start the DNS server in a background task without consuming self.

Unlike start(self), this method borrows self, allowing the DnsServer to be wrapped in an Arc and shared (e.g., with ServiceManager) while the server runs in the background.

Errors

This method currently always succeeds but returns Result for API consistency.

pub async fn bind_windows_fallback( &self, bind_ip: IpAddr, ) -> Result<DnsHandle, DnsError>

Bind a second DNS listener on port 53 of bind_ip, sharing this server’s authority + zone so the same records answer both listeners.

Windows containers always query DNS on port 53 — HNS endpoints do not support setting a non-standard DNS port in the schema. The canonical overlay listener on DEFAULT_DNS_PORT (15353) is therefore unreachable from a Windows container; this method adds a second listener on port 53 of the overlay IP so containers that point at <overlay_ip>:53 via Dns.ServerList can actually resolve.

bind_ip is typically the node’s overlay IP (e.g. 10.200.42.1). Binding to 0.0.0.0:53 would collide with whatever resolver the host already runs (systemd-resolved on Linux, DNS Client on Windows). The method itself is cross-platform; callers decide whether to invoke it based on their workload mix.

The bound UDP + TCP sockets live on a detached tokio task that shares the same Arc<InMemoryAuthority> as the primary listener, so DnsHandle::add_record / remove_record updates both responders atomically. Returns a cloneable DnsHandle for convenience.

Errors

Returns DnsError::Io when either port 53 socket (UDP or TCP) cannot be bound — typically because another DNS resolver already owns the address, or because the process lacks the privilege to bind below 1024 on platforms that require it. Callers should treat this as a warning and fall back to the primary 15353 listener for non-Windows workloads.

pub async fn bind_secondary( &self, listen_addr: SocketAddr, ) -> Result<DnsHandle, DnsError>

Bind an additional DNS listener on an arbitrary listen_addr, sharing this server’s authority + zone so the same records answer on both the primary listener and this one.

Unlike bind_windows_fallback (which is hard-wired to port 53 for Windows HNS containers), this lets the caller pick a non-privileged port — required on macOS where an unprivileged daemon cannot bind below 1024. The VZ-Linux path uses this to expose the overlay resolver on <node_overlay_ip>:<dns_port> so a tiny in-guest relay can forward the guest’s port-53 queries to it.

Errors

Returns DnsError::Io when either the UDP or TCP socket cannot be bound.

pub fn listen_addr(&self) -> SocketAddr

Get the listen address

pub fn zone_origin(&self) -> &Name

Get the zone origin