Meziantou.Framework

Overview

edit

Meziantou.Framework.DnsServer handles the DNS protocol: it receives the queries, decodes and checks them, calls your handler, and encodes, truncates and sends the response. It has no zone files, cache or recursion: the handler decides what every query returns, from a dictionary, a database, another DNS server, or anything else.

How it is hosted

The server runs in an ASP.NET Core application:

  • builder.AddDnsServer(options => ...) adds the listeners. TCP and DNS over TLS listeners are Kestrel endpoints, so they need a web host (WebApplication.CreateBuilder): without one, AddDnsServer throws InvalidOperationException. UDP and QUIC listeners are hosted services.
  • app.MapDnsHandler(handler) registers the handler. Call it exactly once, before the application starts: a second call throws InvalidOperationException. Until a handler is registered, every query is answered with ServerFailure.
  • app.MapDnsOverHttps("/dns-query") adds the DNS over HTTPS endpoints, on the HTTP endpoints of the application.

The listeners start and stop with the application, and log through its logging configuration. See Listeners.

How a query is handled

  1. A listener receives the message.
  2. The server decodes it. A message it cannot parse is answered with FormError (HTTP 400 for DNS over HTTPS), a message that is itself a response is dropped, and an EDNS version other than 0 is answered with BadVersion.
  3. The handler gets a DnsRequestContext with the query, the transport and the address of the client, and returns the response. See Writing a handler.
  4. The server encodes the response and sends it, truncated if it is too large for the transport.

Pages

  • Listeners: UDP, TCP, DNS over TLS, DNS over HTTPS and DNS over QUIC, ports and addresses.
  • Writing a handler: read the query, build the response, response codes, errors.
  • Serving a zone: answer authoritatively for a domain, with NXDOMAIN, NODATA and SOA records.
  • Limits and hardening: response sizes, timeouts, concurrency, and the protections built in.