1. Overview
  2. Docs

µDNS - an opinionated Domain Name System (DNS) library

The Domain Name System is a hierarchical and decentralized naming system used on the Internet. It associates domain names with nearly arbitrary information. Best known is the translation of easily memoizable domain names to numerical IP addresses, which are used by computers for establishing communication channels - so called address records. DNS has been deployed since 1985 on the Internet. It is a widely deployed, fault-tolerant, distributed key-value store with built-in caching mechanisms. The keys are domain names and record types, the values are record sets. Each record set has a time-to-live associated with it: the maximum time this entry may be cached. The domain name library provides operations on domain names. Hostnames are domain names with further restrictions: Only letters, digits, and hyphen are allowed. Domain name comparison is usually done ignoring the case.

A set of 13 authoritative name servers form the root zone which delegate authority for subdomains to registrars (using country codes, etc.), which delegate domains to individuals who host their Internet presence there.

The delegation mechanism utilizes the DNS protocol itself, using name server records, and start of authority records. The globally federated eMail system uses mail exchange records.

Each Internet domain has at least two authoritative name servers registered to enable fault tolerance. To keep these synchronised, a zone transfer mechanism is part of DNS. In-protocol DNS extension mechanisms include dynamic updates, authentication, and notifications, which allow arbitrary synchronized, authenticated modifications.

From a client perspective, the C library functions gethostbyname or getaddrinfo are mainly used, which receive a string (and a record type) and return a reply. A client requests a caching recursive resolver hosted close to the client - e.g. at their ISP, and awaits an answer. The recursive resolver iterates over the domain name parts, and requests the registered authoritative name servers, until the name server responsible for the requested domain name is found.

The core µDNS library includes type definitions of supported record types, decoding and encoding thereof to the binary protocol used on the Internet, also serialising and parsing of the standardized text form. The record types and their values are defined by the key type, which has for each record type a specific value type, using a generalized algebraic data type -- i.e. an address record may only contain a time-to-live and a set of IPv4 addresses. This is used to construct a map data structure.

This core µDNS library is used by various DNS components:

  • Dns_tsig implements TSIG authentication
  • Dns_server implements an authoritative server
  • Dns_client implements a client
  • Dns_zone implements a zone file parser
  • Dns_resolver implements a recursive resolver

These core libraries are pure, i.e. it is independent of network communnication, uses immutable values, and errors are explicit as result type. Timestamps are passed in to the main handle functions. Some components, such as a secondary server, which needs to check freshness of its data in regular intervals. The logic is implemented and exposed as function, which needs to be called from a side-effecting layer.

For the client library, several side-effecting layers are implemented: dns-client.unix uses the blocking Unix API (distributed with the OCaml runtime), dns-client.lwt uses the non-blocking Lwt API, and dns-client.mirage using MirageOS interfaces. Unix command line utilities are provided in the dns-cli package.

For the server and resolver components, side-effecting implementations using MirageOS interfaces are provided in dns-server.mirage and dns-resolver.mirage. Example unikernels are provided externally, including authoritative primary and secondary servers, recursive and stub resolvers. The certificate authority Let's Encrypt implements a protocol (ACME) which automatically provisions X.509 certificates (which are trusted by common web browsers); one of the methods to produce proof of ownership is with a DNS TXT record. Together with ocaml-letsencrypt, this DNS library can be used to provision certificate signing requests for the domain where you run an authoritative server. The certificate signing request and certificate are both stored as TLSA records in DNS.

v6.0.0 - homepage

type proto = [
  1. | `Tcp
  2. | `Udp

The type of supported protocols. Used by Packet.encode to decide on maximum buffer length, etc.

val max_rdata_length : int

Maximum size of resource data. This limitation is close to (2 ^ 16) - 1 (the limit of DNS-over-TCP and EDNS payload size, but slightly smaller, since an rdata must fit into this DNS message together with a DNS header, a question, and a TSIG signature (for e.g. zone transfer).

module Opcode : sig ... end


module Rcode : sig ... end

Response code

module Soa : sig ... end

Start of authority

module Ns : sig ... end

Name server

module Mx : sig ... end

Mail exchange

module Cname : sig ... end

Canonical name

module A : sig ... end

Adress record

module Aaaa : sig ... end

Quad A record

module Ptr : sig ... end

Domain name pointer

module Srv : sig ... end

Service record

module Dnskey : sig ... end

DNS keys

module Caa : sig ... end

Certificate authority authorization

module Tlsa : sig ... end

Transport layer security authentication

module Sshfp : sig ... end

Secure shell fingerprint

module Txt : sig ... end

Text records

module Tsig : sig ... end

Transaction signature

module Edns : sig ... end

Extensions to DNS

module Rr_map : sig ... end

A map whose keys are record types and their values are the time-to-live and the record set. The relation between key and value type is restricted by the below defined GADT.

module Name_rr_map : sig ... end

Name resource record map

module Packet : sig ... end

The DNS packet.

module Tsig_op : sig ... end

Signature operations and their errors.