Skip to content

Latest commit

 

History

History
163 lines (118 loc) · 6.45 KB

HACKING.md

File metadata and controls

163 lines (118 loc) · 6.45 KB

Hacking on update-systemd-resolved

Nix flake usage

This project supplies a flake.nix file defining a Nix flake.1

This Nix flake defines three important important outputs:

  1. A Nix package for update-systemd-resolved (see here),
  2. A NixOS test of update-systemd-resolved features (see here), and
  3. A Nix development shell2 (see here).

In order to work on the update-systemd-resolved project's Nix features, you'll need to install the Nix package manager and ensure that the flakes and nix-command experimental features are enabled.

Building the update-systemd-resolved package

To build the update-systemd-resolved package exposed by this flake, run the following command:3

$ nix build -L '.#'

Or:

$ nix build -L '.#update-systemd-resolved'

These two forms are functionally equivalent because the update-systemd-resolved package is the default package.

In addition to building the package, nix build will place a symbolic link to its output path at ./result (ls -lAR ./result/, tree ./result/, or similar to see what the package contains).

Nix flake checks

This project includes a NixOS test of update-systemd-resolved's functionality and features, exposed as a Nix flake check.

Please see the NixOS manual's "Testing with NixOS" section for information on writing and calling NixOS tests, as well as information on running them interactively and linking them to Nix packages.

How the test works

This project's NixOS test sets up three machines:

  1. An OpenVPN server,
  2. An OpenVPN client,
  3. A DNS resolver running an instance of dnsmasq bound only to the loopback address, plus an instance of RouteDNS bound to an address reachable by the other machines.

The OpenVPN server and client run a point-to-point configuration with a static key. The client's OpenVPN configuration file includes several instances of the dhcp-options recognized by update-systemd-resolved. The test script starts all three machines, waits for certain systemd services to become active, and then asserts that certain hostnames are resolvable from the client that would not be resolvable unless the client were configured to use the DNS settings specified in its OpenVPN configuration file.

The resolver machine uses dnsmasq for actual name resolution, plus DNSSEC validation. The RouteDNS instance running on the same machine terminates DNS-over-TLS and forwards queries to dnsmasq. Dnsmasq handles DNSSEC (though we exempt the VPN domain from DNSSEC validation, as a test of the SetLinkDNSSECNegativeTrustAnchors feature).

Extending the NixOS test

If you are implementing a new feature or correcting a bug in update-systemd-resolved, you are encouraged to extend the NixOS test with new test cases that exercise your feature or verify that the bug is fixed -- unless you can adequately express these within the unit test suite, as that suite runs significanly faster than the NixOS test and has no prerequisites other than Bash.

Running Nix flake checks

To run the above-mentioned NixOS system test and other checks,4 execute the following command:3

$ nix flake check -L
Running a check for a specific system

Running nix flake check [-L] will execute Nix flake checks for all supported systems.5 To run a check for a particular system, instead use the nix build command. For instance, to execute the NixOS system test for the x86_64-linux system, run:

$ nix build -L '.#checks.x86_64-linux.update-systemd-resolved'

Maintaining NixOS test assets

Regenerating the DNS-over-TLS keypair

To regenerate the keypair used for testing DNS-over-TLS, enter the devshell and run mkdotcert.

Regenerating the DNSSEC root anchors

To regenerate the dnsmasq root anchor specification used for testing DNSSEC, enter the devshell and run mkanchor.

Entering the Nix development shell

To enter the Nix development shell, run the following command:

$ nix develop

You will be presented with a menu of commands available within the development shell.

Summary of available commands

  • fmt: format all shell and Nix code in this project using, respectively, shfmt and alejandra. Additionally, lint shell code with shellcheck.
  • mkdotcert: regenerate the keypair used for encrypting DNS-over-TLS in the NixOS system test.
  • mkanchor: regenerate the DNSSEC trust anchors configuration used with dnsmasq in the NixOS system test.

Footnotes

  1. See the NixOS wiki and the nix flake page in the Nix package manager reference manual for background on Nix flakes. ↩

  2. Based on the numtide/devshell project. ↩

  3. Note that the -L flag can be omitted for terser output. ↩ ↩2

  4. Other checks include linting the Nix source code in this project, and running a syntax check on the polkit rules generated by update-systemd-resolved print-polkit-rules. ↩

  5. Run nix flake show to view flake outputs namespaced by all supported systems. ↩