DNS Authoritative Server

Understanding the built-in DNS authoritative server for reverse IP lookups.

Wiretastix embeds a DNS authoritative server primarily for handling PTR (pointer) records, enabling reverse DNS lookups for WireGuard peers. This feature is crucial for operational visibility, allowing administrators to easily identify the user associated with a specific WireGuard peer IP address, especially when analyzing network logs.

How it Works

When a WireGuard peer is provisioned by Wiretastix, it is assigned unique IPv4 and/or IPv6 addresses. The embedded DNS authoritative server is configured to respond to reverse DNS queries (PTR records) for these assigned IP addresses within a specified internal domain.

If a system (e.g., a logging server, a monitoring tool) performs a reverse DNS lookup for an IP address belonging to a Wiretastix-managed peer, the Wiretastix authoritative server will respond with a dynamically generated hostname. This hostname typically includes the associated user’s nickname and the peer’s ID (e.g., john-doe.123.wg.local or standalone.456.wg.local for standalone peers).

Key Use Case: Log Analysis and User Identification

The primary benefit of this authoritative DNS server is to enhance the readability and utility of network logs. Instead of seeing only IP addresses in firewall logs or connection records, you can perform a reverse lookup to immediately identify the user and peer responsible for the traffic. This greatly simplifies troubleshooting, auditing, and security investigations.

Configuration

The resolver is disabled by default (resolver.enabled: false) – you have to turn it on explicitly in wiretastix.yaml. This is deliberate: anyone who can reach the resolver can enumerate every connected peer’s nickname and VPN IP via PTR queries, so it stays off unless you actually use the DNS integration.

resolver:
    enabled: false
    binding: 127.0.0.1:5353
    concurrency: 5
    domain: vpn.local
    acls: []

The binding address, concurrency, and the internal domain are configured here too. It’s important to set domain to match whatever domain you intend to use for internal reverse resolution.

concurrency bounds how many queries are processed at once; a query that can’t get a free slot within 2 seconds is dropped rather than queued indefinitely, so a sustained flood from any ACL-permitted source can’t build an unbounded backlog – it just gets its queries dropped once the resolver is already at capacity.

If enabled is true but binding is empty, malformed, or missing a port, Wiretastix doesn’t fail startup or silently fall through to binding every interface on a random port – it forces binding back to 127.0.0.1:5353 (loopback-only) and logs a warning. This is a fail-safe for a misconfiguration, not a way to leave binding unset intentionally: set it explicitly to whatever address you actually intend the resolver to listen on.

Access Control (acls)

If you widen binding beyond loopback (for example, to let a real resolver on your VPN interface forward the zone to Wiretastix), set acls to the source networks that should be allowed to query it – a list of CIDR blocks (IPv4 or IPv6). An empty list (the default) allows queries from any source that can reach the resolver, matching the resolver’s pre-ACL behavior. A malformed CIDR entry fails config validation at load time rather than silently being ignored. Sources outside the configured ACLs get a standard DNS REFUSED response rather than being silently dropped, and that check happens before a query enters the concurrency queue, so a flood from a disallowed source can’t starve legitimate queries.

This is access control for the resolver as a whole, not per-peer isolation. acls only gates which sources may query the resolver at all – it does not restrict what an allowed source can ask about. Any source that clears the ACL check can still look up any other peer’s nickname and IP, not just its own: PTR queries carry an arbitrary IP chosen by the querier, and the resolver answers whichever one is asked, regardless of who’s asking. Treat acls as “who may see the peer roster at all,” not as isolation between peers.

PTR Records

The Wiretastix DNS authoritative server dynamically generates PTR records. When an IP address (e.g., 10.0.0.2) is queried for its hostname, the server looks up the corresponding peer in its database and returns a hostname like john-doe.123.wg.local.

A Records (Limited Scope)

While the primary focus is on PTR records, the authoritative server can also provide A (address) records for these dynamically generated hostnames, mapping them back to the peer’s IP addresses. This allows for forward lookups of the internal hostnames if needed, though the main emphasis remains on reverse resolution for user identification.

Advanced: Delegating Reverse DNS from Your Existing Infrastructure

The resolver answers standard in-addr.arpa (IPv4) and ip6.arpa (IPv6) PTR queries directly – it isn’t limited to only responding when queried on the configured domain. This means an advanced setup can point the reverse zone matching your WireGuard subnet(s) at Wiretastix from your existing DNS infrastructure, so that any client already using your normal DNS servers gets working reverse lookups for VPN peers, without needing to query Wiretastix directly.

Because the resolver typically binds to a non-standard port (5353 in most examples in this documentation, rather than the standard 53), this is usually done with conditional/forward-zone configuration rather than NS-based zone delegation, which requires the target to listen on port 53. Both the IPv4 reverse zone and, if you’ve configured an IPv6 subnet, the corresponding ip6.arpa zone can be forwarded this way. See DNS Server Configuration for concrete BIND9 and dnsmasq examples covering both.

This built-in DNS authoritative server significantly improves the manageability and observability of your Wiretastix VPN by providing clear, user-identifiable hostnames for your WireGuard peers.