README.md

dns.nix

A Nix DSL for defining DNS zones

This repository provides:

1. NixOS-style module definitions that describe DNS zones and records in them.
2. A DSL that simplifies describing your DNS zones.

An example of a zone

with dns.lib.combinators; {
  SOA = {  # Human readable names for fields
    nameServer = "ns.test.com.";
    adminEmail = "[email protected]";  # Email address with a real `@`!
    serial = 2019030800;
    # Sane defaults for the remaining ones
  };

  NS = [  # A zone consists of lists of records grouped by type
    "ns.test.com."
    "ns2.test.com."
  ];

  A = [
    { address = "203.0.113.1"; }  # Generic A record
    { address = "203.0.113.2"; ttl = 60 * 60; }  # Generic A with TTL
    (a "203.0.113.3")  # Simple a record created with the `a` combinator
    (ttl (60 * 60) (a "203.0.113.4"))  # Equivalent to the second one
  ];

  AAAA = [
    "4321:0:1:2:3:4:567:89ab"  # For simple records you can use a plain string
  ];

  CAA = letsEncrypt "[email protected]";  # Common template combinators included

  MX = mx.google;  # G Suite mail servers;

  TXT = [
    (with spf; strict [google])  # SPF: only allow gmail
  ];

  subdomains = {
    www.A = [ "203.0.114.1" ];

    staging = delegateTo [  # Another shortcut combinator
      "ns1.another.com."
      "ns2.another.com."
    ];
  };
}

You can build an example zone in example.nix by running nix build -f ./example.nix or nix-build ./example.nix.

Why?

• The DNS zone syntax is crazy. Nix is nice and structured.
• Having the full power of a Turing-complete functional language (let, if, map and other things you are used to).
• All kinds of shortcuts and useful combinators.
• Strong typing provded by the NixOS module system.
• Modularity: records defined in different modules get magically merged.

Use

Importing

There are two ways to import dns.nix.

As a flake

Add it as an input to your flake:

# flake.nix

{
  inputs = {
    # ...

    dns = {
      url = "github:kirelagin/dns.nix";
      inputs.nixpkgs.follows = "nixpkgs";  # (optionally)
    };
  };

  outputs = { self, nixpkgs, dns }: {
    # Most functions from `dns.nix` are available in `dns.lib`.
    # Functions that require `stdenv` (e.g. `writeZone`) are in
    # `dns.util.<system>`.
    # ...
  };
}

Importing directly (legacy)

Always get the latest version from GitHub:

let
  dns = import (builtins.fetchTarball "https://github.com/kirelagin/dns.nix/archive/master.zip");
in {
  # ...
}

To make your setup more reproducible, you should pin the version used by specifying a commit hash or using a submodule. This is all a little clumsy and nowadays it is probably best to simply switch to flakes.

In your NixOS configuration

There is a chance that in the future we will either integrate this into existing NixOS modules for different DNS servers, or will provide a separate NixOS module that will configure DNS servers for you.

# example.com.nix

{ dns }:

with dns.lib.combinators;

{
  SOA = {
    nameServer = "ns1";
    adminEmail = "[email protected]";
    serial = 2019030800;
  };

  NS = [
    "ns1.example.com."
    "ns2.example.com."
  ];

  A = [ "203.0.113.1" ];
  AAAA = [ "4321:0:1:2:3:4:567:89ab" ];

  subdomains = rec {
    foobar = host "203.0.113.2" "4321:0:1:2:3:4:567:89bb";

    ns1 = foobar;
    ns2 = host "203.0.113.3" "4321:0:1:2:3:4:567:89cc";
  };
}

These example assume nsd, but it should be pretty much the same for other daemons.

When your system is defined as a flake:

{

# Add `dns.nix` to `inputs` (see above).
# ...

# In `outputs`:

  nixosConfigurations.yourSystem = nixpkgs.lib.nixosSystem {

    # ...

    services.nsd = {
      enable = true;
      zones = {
        "example.com" = {
          # provideXFR = [ ... ];
          # notify = [ ... ];
          data = dns.lib.toString "example.com" (import ./example.com.nix { inherit dns; });
        };
      };
    };

  };

}

If your system configuration is not a flake, everything will be essentially the same, you will just import it differently.

In modules you develop

dns.lib provides the types attribute, which contains DNS-related types to be used in the NixOS module system. Using them you can define an option in your module such as this one:

# dns = ...

{

yourModule = {
  options = {
    # <...>

    zones = lib.mkOption {
      type = lib.types.attrsOf dns.lib.types.zone;
      description = "DNS zones";
    };
  };

  config = {
    # You can call `toString` on a zone from the `zones` attrset and get
    # a string suitable, for example, for writing with `writeTextFile`.
  };
};

}

As another example, take a look at the evalZone function in dns/default.nix, which takes a name for a zone and a zone definition, defines a “fake” module similar to the one above, and then evaluates it.

dns.utils provides writeZone, which is a helper function that additionally calls toString and writes the resulting string to a file.

Contributing

If you encounter any issues when using this library or have improvement ideas, please open an issue on GitHub.

You are also very welcome to submit pull requests.

Please, note that in this repository we are making effort to track the authorship information for all contributions. In particular, we are following the REUSE practices. The tl;dr is: please, add information about yourself to the headers of each of the files that you edited if your change was substantial (you get to judge what is substantial and what is not).

License

MPL-2.0 © Kirill Elagin and contributors (see headers in the files).

Additionally, all code in this repository is dual-licensed under the MIT license for direct compatibility with nixpkgs.