nixdiag

Static infrastructure docs from any Nix flake: topology, module tree, flake inputs and an mdBook wiki from nixosConfigurations and darwinConfigurations.

nix run github:kucendro/nixdiag

Topology comes from the NixOS module system. Adapters read the options you already set, nixdiag.* options override them.

Both are the two-host fixture, the live demo.

What you get

Next

• Quickstart
• Topology: adapters, nixdiag.* options, overrides
• Build and serve: mkDocs, the nginx module
• CLI: flags

Quickstart

Render an existing flake

cd ~/my-nix-config
nix run github:kucendro/nixdiag

Prints the store path of the docs. Open wiki/book/index.html in it.

Start a new flake

nix flake init -t github:kucendro/nixdiag
nix build .#docs

First override

{
  nixdiag.units.nginx.role = "gateway";
  nixdiag.units.exporter.connections = [ { to = "grafana"; label = "metrics"; } ];
}

More in Topology.

Keep it honest in CI

checks.x86_64-linux.docs = self.packages.x86_64-linux.docs;

An unresolved connection fails nix flake check.

Topology

{
  services.headscale = {
    enable = true;
    port = 8080;
    settings.server_url = "https://hs.ts.example";
  };
  services.nginx.virtualHosts."hs.ts.example" = {
    forceSSL = true;
    locations."/".proxyPass = "http://127.0.0.1:8080";
  };
}

Adapters turn that into headscale on 8080, a proxy exposing hs.ts.example on 443 to the internet, and the connection between them. Override with nixdiag.* options in plain Nix.

Adapters

Scope from listen addresses: 100.64.0.0/10 is mesh, RFC 1918 is lan, anything else public when the firewall opens the port.

Options

nixdiag.units.<unit>:

nixdiag.description, scope, names, expose: the same for the host.

plane is data (default), control or mgmt: control is infrastructure coordinating itself, a mesh node talking to its server; mgmt is you operating it, scrapes, backups, deploys. The overview draws only data; host boards draw every plane, control and mgmt thin and dashed.

Networks

Every static interface address puts its host on the subnet it belongs to. Name a subnet, or join more under one name, on any host:

nixdiag.networks.lan.cidrs = [ "192.168.1.0/24" "fd00:1::/64" ];

A network belongs to the nixdiag.location of the hosts on it, so the same range at two locations is two networks, 192.168.1.0/24 @ home and 192.168.1.0/24 @ lab. A declared name splits the same way into lan @ home and lan @ lab; a mesh network never splits. A host without a location joins the only copy of its range, and fails the build when there are several.

The same name declared differently at one location, or two declared networks that overlap without sitting at two different locations, fails the build.

The overlay board draws every mesh network: its members by interface, the routes they carry, and the control server their control connections reach. Any mesh shows up once an adapter or your config declares the network, the member interfaces and the control connection; nothing on the board is specific to tailscale.

Locations

nixdiag.location = "home";

Hosts sharing a lan or public network share a location: name it on one host and the rest follow. A host’s own nixdiag.location wins; two names in one group leave its unnamed hosts out. The overview and the networks board draw each location as a box around its hosts and the networks inside it; mesh networks and the internet stay outside.

Firewall

The firewall page lists, per host, what networking.firewall opens on every interface, on each one, and trusts, then what does not add up:

• a port open that no unit, port or expose uses
• an expose closed on every interface its scope reaches
• a trusted interface other than lo: every port on it is open
• a connection from another host to a port closed on every interface they share

A port counts as used only when nixdiag knows it: a service with no adapter and no nixdiag.units entry shows as unused. Raw nftables or iptables rules are not read.

An expose with no scope is reached from the networks behind every interface the firewall opens its port on, and takes the widest of their kinds.

Overriding

{ lib, ... }:
{
  nixdiag.units.nginx.role = "gateway";
  nixdiag.units.grafana = {
    scope = "mesh";
    expose = [ { port = 3000; name = "grafana.ts.example"; } ];
    connections = [ { to = "exporter"; label = "scrapes"; } ];
  };
  nixdiag.units.tailscale.connections = lib.mkForce [ ];
  nixdiag.units.exporter = { };
}

Assignment wins over an adapter, lists append, mkForce replaces. An empty attrset declares a unit no adapter knows.

Targets

A network, CIDR or address found at several locations resolves at the source host’s location; from a host with no location it fails the build.

Unresolved fails the build. lan is no longer built in: declare nixdiag.networks.lan.cidrs and to = "lan" keeps working.

Adding an adapter

Copy nix/adapters/example.nix to nix/adapters/foo.nix. Every field is explained there. Besides topology, an adapter may define networks and interfaces: reads in, nixdiag.networks and nixdiag.interfaces out. tests is required: nix flake check boots the VMs it names and compares the adapter’s claims to what runs.

Audit

nix run github:kucendro/nixdiag#audit -- nixos-unstable github:NixOS/nixpkgs/master

Checks every read against options.json, downloaded for a channel or built for any nixpkgs ref: ok, renamed, unaudited, broken; --json for rows. Every day at 20:00 Prague time the monitor workflow runs it against master, nixos-unstable and nixos-26.05, boots the adapter VMs on both channels, evaluates them on master, and records both on the data branch. An adapter that is not ok gets an issue mentioning its maintainers, which are GitHub handles; it closes once every head is ok again.

Adapters

master

Last run at nixpkgs 7e53cc6.

nixos-26.05

Last run at nixpkgs da6dc0e.

nixos-unstable

Last run at nixpkgs 3ec6363.

Build and serve

inputs.nixdiag.url = "github:kucendro/nixdiag";

packages.x86_64-linux.docs = nixdiag.lib.mkDocs {
  pkgs = nixpkgs.legacyPackages.x86_64-linux;
  flake = self;
  title = "my infrastructure wiki";
};

nix build .#docs: your flake evaluates its configurations, the sandbox renders, nothing is committed back. nix run github:kucendro/nixdiag does the same for the current directory without touching the flake.

Closure metrics

closures builds every host it measures. Nar sizes exist only for realised paths, so each measured system.build.toplevel becomes a build input. Mostly substituted, but budget for it. NixOS only.

A host that serves the docs is measured with an empty directory in the docs’ place, so a build may document the host that serves it. The Closures page says so under that host.

Each bar is one host’s closure split into what every host carries, what some carry, and what this host alone costs; each measured host also gets a treemap of its packages. An unmeasured host keeps its row with —. Packages are named without their store path, so the docs never retain the closures they describe.

Chart colors: chartShared, chartPartial, chartUnique, chartMark, chartInk, chartMuted, chartTrack, chartTileInk.

Build and root the systems in your own pipeline first, on the machine that runs the docs build; the measurement then finds everything realised and costs seconds of jq:

- run: |
    for host in nas edge nixbook; do
      nix build ".#nixosConfigurations.$host.config.system.build.toplevel" \
        --out-link "/var/lib/ci/gcroots/$host"
    done
- run: nix build .#docs

The docs hold no references to the systems, so anything unrooted goes at the next nix-collect-garbage. The measurement is preferLocalBuild, so invoking it elsewhere copies every closure to the invoking machine.

Diagram styling

theme = "light";
background = "#ffffff";
colors = { public = "#ff5555"; mesh = "#7fa7e8"; };

Names: appFill, appStroke, infraFill, infraStroke, baseFill, baseStroke, hostFill, hostStroke, progFill, hostCloud, public, lan, mesh, ink for text, line for plain edges. An unknown name is an error listing the palette.

theme also picks the mdBook theme the seeded book.toml starts with: navy for dark, light with coal for dark-preferring viewers otherwise.

Serving it

{
  imports = [ inputs.nixdiag.nixosModules.default ];

  services.nixdiag.serve = {
    enable = true;
    docs = inputs.self.packages.x86_64-linux.docs;
    virtualHost = "wiki.example.com";
    virtualHostExtra = {
      listenAddresses = [ "100.64.0.1" ];
      useACMEHost = "example.com";
      forceSSL = true;
    };
  };
}

The vhost points straight at the docs derivation, so the wiki ships with every deploy. No daemon, no timer, no checkout.

The module also declares the nixdiag.* options; mkFacts adds it itself when a host does not import it. Keep one nixdiag input for both, a module from another revision fails with a schema mismatch.

Printing

mdBook’s print icon lays the book out on one page, and the browser’s “Save as PDF” turns that into a vector PDF, diagrams included. Choose landscape or a larger paper size where a dense diagram has to stay legible.

CLI

nixdiag --facts facts.json --repo . --out docs

Renders from a facts.json that lib.mkFacts produced and never calls nix. This is what mkDocs runs in the sandbox; nix run github:kucendro/nixdiag builds it for the flake in the current directory.

SVG rendering needs d2 on PATH; the packaged binary wraps it in.

nix run github:kucendro/nixdiag#audit

Checks the adapters against nixpkgs, see Topology.

Live demo

Open the demo wiki

The two-host fixture in tests/fixture/, rendered by nix build .#demo-docs: around sixty lines of NixOS config and one nixdiag.units block produce every page there.

The same render feeds checks.reference and supplies the diagrams on this site, so fixture, tests, images and demo cannot drift apart.