A Nix DSL for defining DNS zones
This repository provides:
with dns.lib.combinators; {
SOA = { # Human readable names for fields
nameServer = "ns.test.com.";
adminEmail = "admin@test.com"; # 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 "admin@example.com"; # 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
.
let
, if
, map
and other things you are used to).There are two ways to import dns.nix
.
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>`.
# ...
};
}
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.
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 = "admin@example.com";
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.
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.
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).
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.