Home

Awesome

ocaml-dns - a Domain Name System (DNS) library

(c) 2017-2019 Hannes Mehnert (robur.io, Center for the Cultivation of Technology)

%%VERSION%%

This library supports most of the domain name system used in the wild. It adheres to strict conventions. Failing early and hard. It is mostly implemented in the pure fragment of OCaml (no mutation, isolated IO, no exceptions).

It all started out as an experiment to run a recursive resolver, but after initial prototypes it turned out that every configurable recursive resolver needs a fully-fledged authoritative nameserver as well (for overriding various zones such as .localhost and reverse lookups of RFC 1918 IP ranges).

Legacy resource record types are not dealt with, and there is no plan to support ISDN, MAILA, MAILB, WKS, MB, HINFO, ... . AXFR, IXFR, and UPDATE is only handled via TCP connections. The only resource class supported is IN (the Internet). Truncated hmac in TSIG are not supported (always the full length of the hash algorithm is used).

Please read the blog article for a more detailed overview.

This library is published under the 2 clause BSD license.

Supported RFCs

*: Please note that the RFCs marked with * are only partially implemented (i.e. only wire format, but no logic handling the feature).

Installation

You first need to install OCaml (at least 4.08.2) and opam, the OCaml package manager (at least 2.0.0) on your machine (you can use opam to install an up-to-date OCaml (opam switch 4.08.2)).

You may want to follow the mirage installation instructions to get mirage installed on your computer.

To minimize the amount of run-time dependencies for each individual functionality, the library is split into multiple opam packages (core, server, client, resolver, cli, certify), with multiple ocamlfind libraries for the different backends (no optional dependencies) -- i.e. dns-server.mirage contains the MirageOS-specific DNS server code.

Now the µDNS library is installed, and you can try out the examples. Find some examples at the unikernel repository.

Documentation

API documentation is available online.

Transition from older versions

The pre-4.0.0 versions of ocaml-dns had a significantly different interface, and so applications using them will need to be rewritten to follow the stricter coding style used in the post-4.0.0 branches. The major improvements from 1.x to the 4.x series are:

Please get in touch on mirageos-devel@lists.xenproject.org or on the Discuss forum at https://discuss.ocaml.org (with the mirageos tag) if you have any questions about migrating (or just general questions).

Development

To work with the opam packages provided when developing modifications to DNS, or when pinning a specific version, you will have to pin the same version for all of them:

: csh syntax
set version=4.99.0
set repo=git+https://github.com/mirage/ocaml-dns.git

# the -y parameter means "force" or
# "do go ahead and register a new package"

# the -n parameter means
# "just register the pin, don't actually install it yet"

foreach pkg ( dns dns-{certify,cli,client,resolver,server,mirage,tsig,stub} )
  opam pin add -y -n $pkg.$version --dev $repo
end

: bash syntax
version=4.99.0
repo=git+https://github.com/mirage/ocaml-dns.git

for pkg in dns dns-{certify,cli,client,resolver,server,mirage,tsig,stub}
do
  opam pin add -y -n $pkg.$version --dev $repo
done

Now you can install the packages you need, for instance:

opam install dns-client

or

opam install dns-resolver