dns.nix
A Nix DSL for defining DNS zones
This repository provides:
- NixOS-style module definitions that describe DNS zones and records in them.
- 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,mapand 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.