The config.yaml file

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

Validate changes

After each modification, 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 are in camelCase (they become Nix attributes). The examples below are generic (domain.tld, 10.0/10.1 prefixes).

Section “network”

This optional section defines the global settings of our network.

etc/config.yaml

network:
  domain: "domain.tld"          # domaine DNS racine (services, VPN, certificats)
  default:
    locale: "fr_FR.UTF-8"       # locale par défaut de chaque hôte
    timezone: "Europe/Paris"    # fuseau par défaut
  coordination:
    enable: true                # active le maillage VPN (Headscale)
    hostname: "hcs"             # nom court de l'hôte de coordination
    domain: "headscale"         # sous-domaine → headscale.domain.tld

Choosing a domain

It is strongly recommended to use a real domain for network.domain. This makes it easier to access services from outside, as well as to set up the VPN network.

Moreover, these features require TLS to work. TLS certificate management for the network is automatic (acme, transfer to the zones) but requires the use of a real domain and proper DNS configuration.

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

The locale also sets the keyboard, in console as well as on the desktop: the one given by dnf/config/locales.json (en_GB.UTF-8: uk in console, gb under GNOME), otherwise the country code (ru_RU.UTF-8: ru).

Network without VPN

coordination.enable: false remains valid: you can define one or more zones and deploy locally. With multiple zones, however, a VPN makes it easier to administer remote nodes through secure direct access.

Section “zones”

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

etc/config.yaml

zones:
  main:
    description: "Réseau principal"
    locale: "fr_FR.UTF-8"        # optionnel (défaut : network.default.locale)
    timezone: "Europe/Paris"     # optionnel
    ipPrefix: "10.0"             # la zone utilise 10.0.0.0/16
    gateway:
      wan:
        interface: "enp1s0"      # interface vers Internet (requis)
      lan:
        interfaces: ["enp2s0"]   # interface(s) interne(s) (requis)
      vpn:
        ipv4: "100.64.0.1"       # IP tailnet de la passerelle (après enrôlement)

Key	Role
description	Zone label.
locale / timezone	Locale 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 the 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.6.x machines from other zones, passing through (reserved, computed),
• 10.0.11-99.x hosts within the range.

The gateway

Key	Role
wan.interface	Network interface to the Internet (required).
lan.interfaces	List of internal interfaces (required), joined into the lan0 bridge.
lan.dhcp-range	DHCP range (optional; default <préfixe>.3.200,<préfixe>.3.249,24h).
vpn.ipv4	Gateway tailnet IP, collected after just tailnet-enroll (details).

Automatic detection

The host whose IP ends with .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 on 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"   # IP publique (zone externe)
      internal: "10.0.0.2"       # IP dans le VPN

Zone assignment and physical location

Declare the zone where the machine usually resides. That’s where it carries its fixed address and where its simple name points.

It remains reachable elsewhere, provided it has a mac key : each zone then reserves a transit address for it. See Machines outside their 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 monitoring (monitoring-node)
# and NFS client (requires a server in the zone)
features: ["monitoring-node", "nfs-client"]

# Machine monitored 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 the nfs server shares of the zone (a server must exist in that zone).

Evolving list

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

nfs-client: server zone required

The :<zone> suffix of nfs-client must designate the zone of the nfs server, which currently means the host’s own zone: cross-zone NFS clients are not yet supported. A suffix pointing elsewhere no longer enables the mount — previously the host would still mount its own zone’s server, while its XDG links were not created.

Shares reserved for declared clients only

The NFS server exports one line per declared client address, never the zone prefix: a machine not listed in etc/config.yaml gets no mount. A client’s root account is overridden on all three shares (root_squash), so it has no more privileges than a regular user. Adding a machine requires declaring it, then reapplying the server configuration.

Declare services

The services key holds a collection of services to automatically install on the host. Values are optional and allow service customization.

Service and node type

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

• One service per zone (e.g. adguardhome, nix-cache)
• Special zone-less service (e.g. headscale, turn)

Guardrails may prevent you from installing any service anywhere.

etc/config.yaml

    services:
      immich:
        title: "Photos"
        description: "Mes photos & vidéos"
        domain: "photos"          # sous-domaine
        global: true              # → https://photos.domain.tld (public)
      nextcloud:
        domain: "cloud"           # → cloud.<zone>.domain.tld (non global)
      restic:                     # valeurs par défaut

Field	Role
(key)	Service to enable (e.g. immich).
title	Name displayed on the portal.
description	Subtitle on the portal.
domain	Subdomain (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 the partitioning

The disko key describes the partitioning for the automatic installation.

• profile refers to a usr/hosts/disko/<profile>.nix file, otherwise dnf/hosts/disko/<profile>.nix (the local profile overrides the framework’s).
• devices is required : one real device per disk named in the profile, no more, no less, otherwise just generate fails.

etc/config.yaml

    disko:
      profile: "btrfs-1-disk"
      devices:
        main: "/dev/disk/by-id/nvme-Samsung_SSD_990_PRO_2TB_S7DNNJ0W000000"

Prefer /dev/disk/by-id/

A /dev/sdX name can change from one boot to another (installation USB key plugged in, disk added) and point to the wrong disk. Get the stable identifier with ls -l /dev/disk/by-id/ from the ISO.

Useful for installation only

just generate combines the profile and devices into usr/machines/<hôte>/install/disko.nix, which just install freezes. The disko block then has no further effect and can be removed. See Machine directory.

Reinstalling a machine

The big 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 problem. A good declaration combined with a complete data backup allows a full reinstallation.

Useful links

For the full machine installation walkthrough, see Initial installation.