The config.yaml file

config.yaml is a simple, high-level configuration. It is the source of truth for the network. The generator reads it and produces var/generated/*.nix, consumed by the framework.

Validate changes

After every change, run just generate (or just clean), then just apply.

The file has four sections :

Section	Role
network	Global parameters: domain, locale, VPN coordination.
zones	Subnets: IP prefix, gateway, non-NixOS devices.
users	Accounts, common to all zones.
hosts	Machines to deploy.

Convention

Keys use camelCase (they become Nix attributes). The examples below are generic (domain.tld, 10.0/10.1 prefixes).

“network” section

This optional section defines the global parameters of our network.

etc/config.yaml

network:
  domain: "domain.tld"          # root DNS domain (services, VPN, certificates)
  default:
    locale: "fr_FR.UTF-8"       # default locale for every host
    timezone: "Europe/Paris"    # default timezone
  coordination:
    enable: true                # enables VPN mesh (Headscale)
    hostname: "hcs"             # short name of the coordination host
    domain: "headscale"         # subdomain → headscale.domain.tld

Choose a domain

It is strongly recommended to use a real domain for network.domain. This facilitates external access to services, as well as setting up the VPN network.

Furthermore, these features need TLS to operate. The network’s TLS certificate management is automatic (acme, transfer to zones) but requires using a real domain and appropriate DNS configuration.

Key	Role
domain	Root DNS domain (services, Headscale, certificates).
default.locale	Default values, possibly overridden by zone.
default.timezone	Default values, possibly overridden by zone.
coordination.enable	Enables VPN coordination. false → local zones only.
coordination.hostname	Headscale host and subdomain.
coordination.domain	Headscale host and subdomain.

Network without VPN

coordination.enable: false is still valid : you can define one or more zones and deploy locally. With multiple zones, a VPN nevertheless facilitates administration of remote nodes thanks to direct secured access.

”zones” section

A zone is a subnet (home LAN, guest network, remote site…). Each zone has an IP /16 prefix, a gateway and, optionally, non-NixOS devices.

etc/config.yaml

zones:
  main:
    description: "Main network"
    locale: "fr_FR.UTF-8"        # optional (default: network.default.locale)
    timezone: "Europe/Paris"     # optional
    ipPrefix: "10.0"             # the zone uses 10.0.0.0/16
    gateway:
      wan:
        interface: "enp1s0"      # interface to Internet (required)
      lan:
        interfaces: ["enp2s0"]   # internal interface(s) (required)
      vpn:
        ipv4: "10.0.0.1"         # gateway VPN IP (after registration)

Key	Role
description	Zone label.
locale / timezone	Local overrides (otherwise network.default).
ipPrefix	First two octets of an RFC1918 /16 (e.g. 10.0).
gateway	Gateway configuration (see below).
extraHosts	Non-NixOS devices resolved by name (see below).

Addressing convention

The project reserves octets as follows (prefix 10.0) :

• 10.0.1.x servers and network nodes (.1.1 = gateway),
• 10.0.2.x NixOS workstations,
• 10.0.3.x DHCP range,
• 10.0.4-5.x non-NixOS devices,
• 10.0.11-99.x hosts in range.

The gateway

Key	Role
wan.interface	Network interface to Internet (required).
lan.interfaces	List of internal interfaces (required), integrated into the lan0 bridge.
lan.dhcp-range	DHCP range (optional; default <prefix>.3.200,<prefix>.3.249,24h).
vpn.ipv4	Gateway VPN IP, to fill in after Headscale registration.

Auto-detection

The host whose IP ends in .1.1 is automatically the gateway of its zone. See Gateway.

Non-NixOS devices (extraHosts)

Phones, printers, IoT devices: resolved by name and fixed on DHCP. The common key is merged into each zone (devices present everywhere).

etc/config.yaml

zones:
  main:
    # ...
    extraHosts:
      printer:
        ip: "4.1"                # suffix → 10.0.4.1
        name: "Living room printer"
        mac: "aa:bb:cc:dd:ee:01"
  common:
    extraHosts:                  # added to ALL zones
      phone-alice:
        ip: "5.1"
        name: "Alice's phone"
        mac: "aa:bb:cc:dd:ee:02"

Section “users”

Shared accounts across all zones. Each account receives a profile Home Manager and groups.

etc/config.yaml

users:
  alice:
    uid: 1000
    name: "Alice Martin"
    email: "alice@domain.tld"
    profile: "nix-admin"
    groups: ["zone-main", "global", "idm-admins"]
  bob:
    uid: 1001
    name: "Bob Durand"
    profile: "normal"
    groups: ["zone-main"]

Key	Type	Role
(key)		Account identifier (login) ([a-z]…).
uid	integer	Stable numeric identifier (required).
name	text	Display name (required).
email	text	Email address (also used for SSO identity), defaults to <login>@<domain.tld>.
profile	text	User profile (default minimal).
groups	list	Installs the user on hosts with the same group.

User nix

The maintenance account nix (profile nix-admin) is automatically added to every host. Do not declare it.

Groups = access

A host authorizes a user if it is listed in users, or if one of its groups matches. See Users.

”hosts” section

hosts is a list of entries (- hostname: …). A machine can be declared in three ways depending on the need.

Static type: one host per entry

One entry = one machine. The simplest and most common form.

etc/config.yaml

hosts:

  - hostname: "gw"
    name: "Main gateway"
    zone: "main:1.1"             # fixed IP 10.0.1.1 → gateway
    profile: "gateway"
    tags: ["main"]
    features: ["monitoring-node"]
    services:
      adguardhome:
      homepage:

  - hostname: "server"
    name: "Home server"
    zone: "main:1.2"             # fixed IP 10.0.1.2
    profile: "server"
    users: ["alice"]
    services:
      nextcloud:
      restic:

Collection type: similar machines

A common config + a sub-map hosts:: each member (key) inherits the group’s keys (profile, groups, features, tags, disko) and specifies its own name, zone, MAC address. The %s in the group’s hostname/name is replaced by the member’s key (and by its name).

etc/config.yaml

hosts:

  - hostname: "%s-laptop"        # %s → member key
    name: "Portable de %s"       # %s → member's name
    profile: "laptop"
    groups: ["zone-main"]
    hosts:
      alice:                     # → hostname "alice-laptop"
        name: "Alice"
        zone: "main:2.4"
        mac: "aa:bb:cc:dd:ee:10"
      bob:                       # → hostname "bob-laptop"
        name: "Bob"
        zone: "main:2.5"
        mac: "aa:bb:cc:dd:ee:11"

What wins?

The group keys (profile, groups, features, tags, disko) override each member; the member provides the rest (name, zone, mac…).

Range type: identical machines

Generates N identical hosts numbered sequentially. range: [start, end] (inclusive bounds). Template tokens (similar to printf substitutions 🡕) are replaced by the index :

Token	Effect	Example (i=3)
%d or %s	The index	vm-%d → vm-3
%'02s	Padded index (char + width)	vm-%'02s → vm-03

etc/config.yaml

hosts:

  - hostname: "desktop-%'02s"    # desktop-01 … desktop-04
    name: "Guest workstation n°%'02s"
    zone: "main:11.%d"           # 10.0.11.1 … 10.0.11.4
    profile: "desktop"
    range: [1, 4]
    groups: ["zone-main"]
    features: ["nfs-client"]
    mac:                         # MAC by index
      1: "aa:bb:cc:dd:ee:21"
      2: "aa:bb:cc:dd:ee:22"
      3: "aa:bb:cc:dd:ee:23"
      4: "aa:bb:cc:dd:ee:24"

Per-index overrides

Under a range, hosts.<i> adds keys specific to the host at index i (only new keys are merged).

Key list

Key	Type	Role
hostname	text	DNS identifier (required); templates %s/%d/%'02s.
name	text	Readable name (required).
profile	text	Host profile (gateway, server, desktop, laptop, hcs…).
zone	text	Zone and IP (see below).
ipv4	map	External host: external (public IP) + internal (VPN IP).
users	list	Logins authorized to open a session.
groups	list	Host groups (add corresponding members).
tags	list	Colmena tags (just apply @tag).
features	list	Non-service flags (see below).
services	map	Enabled services (see below).
mac	text/map	Internal interface MAC (static), map by index (range).
aliases	list	Additional DNS names.
arch	text	Architecture (default x86_64-linux).
disko	map	Disk scheme (see below).
range	list	[start, end] for a range.
hosts	map	Members (collection) or per-index overrides (range).

Assigning a zone

The zone key sets the network membership and the IP address :

Form	Effect
zone: "main:1.2"	Fixed IP <ipPrefix>.1.2 (e.g. 10.1.1.2 in zone main in 10.1).
zone: "main:11.%d"	Fixed IP with range index (e.g. 10.1.11.1, 10.1.11.2…).
zone: "main"	Dynamic address (DHCP) in the zone.

An external host (the HCS) has no zone but an ipv4 block :

etc/config.yaml

  - hostname: "hcs"
    name: "Coordination"
    profile: "hcs"
    ipv4:
      external: "203.0.113.26"   # public IP (external zone)
      internal: "10.0.0.2"       # IP in the VPN

Zone assignment and physical location

Set zones consistently; the machine must belong to the physical network (local network) of the declared zone.

Assigning features

The features key enables specific behaviors or features. A :<zone> suffix targets a specific zone (otherwise the host’s zone is used). Examples:

# Machine under supervision (monitoring-node)
# and NFS client (a server must exist in the zone)
features: ["monitoring-node", "nfs-client"]

# Machine supervised by the "main" zone
features: ["monitoring-node:main"]

Available features:

• monitoring-node : the host exposes its metrics (node-exporter) to the zone’s monitoring.
• nfs-client : the host mounts shares from the zone’s nfs server (a server must exist in the zone).

Evolving list

A feature is a simple flag read by a module. The :<zone> suffix targets a zone other than the host’s.

Declaring services

The services key contains a collection of services to be automatically installed on the host. Values are optional and allow service customization.

Service type and node type

Most services can be installed on any node, but some may have constraints :

• Only one service per zone (e.g. adguardhome, ncps)
• Special out-of-zone service (e.g. headscale, turn)

Safeguards may prevent you from installing any service anywhere.

etc/config.yaml

    services:
      immich:
        title: "Photos"
        description: "My photos & videos"
        domain: "photos"          # sub-domain
        global: true              # → https://photos.domain.tld (public)
      nextcloud:
        domain: "cloud"           # → cloud.<zone>.domain.tld (non global)
      restic:                     # default values

Field	Role
(key)	Service to enable (e.g. immich).
title	Name displayed on the portal.
description	Subtitle on the portal.
domain	Sub-domain (default: service name).
global	Exposes publicly via the HCS: <domain>.domain.tld, without the zone.
icon	Portal icon.

Full service name

By default a service is at <domain>.<zone>.domain.tld ; with global: true, at <domain>.domain.tld. Catalog and details : Services.

Declaring partitioning

The disko key describes partitioning for automatic installation.

• profile designates a (usr|dnf)/hosts/disko/<profile>.nix file.
• devices maps the profile’s named disks to actual devices.

etc/config.yaml

    disko:
      profile: "btrfs-1-disk"
      devices:
        main: "/dev/nvme0n1"

Installation only

disko is only read during installation (just install formats the disks). Once the machine is installed, you can comment out the disko block for safety. An accidental trigger of the installation could order a disk reformat.

Reinstalling a machine

The major advantage of a declarative configuration is being able to reinstall a node with all its programs and configuration, either to change hardware or after a serious issue. A good declaration combined with a complete data backup allows a full reinstallation.

Useful links

For the full machine installation walkthrough, see Initial installation.