Specifications

Goals

This nixos configuration enables a full local network with ready-to-use configurations and profiles:

• User profiles contains features and configurations for users (employes, developers, administrators, kids…).
• Host profiles cover standard use cases: workstations, servers, network node (gateway).

Universal settings

Configurations are designed to be fully functional, clean, consistent, easy to use, and require no extensive customization.

Use cases

For example, this configuration can be used for:

• Work: A network with a gateway, servers, and workstations.
• Family: Gateway with adguard and host profiles tailored for parents and kids.
• Projects: Servers and workstations designed to meet your specific needs.

Implemented features

This section includes everything that is currently implemented and functional.

The generator

Its role is to generate a pure static configuration from a definition of machines (hosts), users, and groups from various sources (static declarations, LDAP, etc. configured in usr/config.yaml. The generated Nix configuration is integrated into the repository to be fixed and used by the flake.

Usage:

# Generate, fix, format, check
just clean

A just clean:

❯ just clean
-> Fixing source code with statix...
-> Checking nix files with deadnix...
-> generating dnf/modules/nix default.nix...
-> generating usr/modules/nix default.nix...
-> generating dnf/modules/home default.nix...
-> generating usr/modules/home default.nix...
-> generating users in var/generated/users.nix...
-> generating hosts in var/generated/hosts.nix...
-> generating network in var/generated/network.nix...
-> Formatting nix files with nixfmt...

The generated files

• var/generated/hosts.nix The host collection
• var/generated/users.nix The explicitly created user collection
• var/generated/network.nix The network configuration

The configuration file

The usr/config.yaml file contains declarations of users, hosts, network config and providers. The generator reads this file to create a static pure nix configuration.

Users - groups - hosts

You can link users and hosts either directly or through a group list, which is declared in the users and/or groups items.

Content accessible in your nix configuration:

• network attrSet contains useful content to build a gateway and more.
• users attrSet is a full list of users.
• hosts list is a full list of hosts.
• host contains the current host informations.

Tip

The framework repository contains an example:

• usr/config.yaml 🡕 main config file generates…
• var/generated/users.nix 🡕 attrSet (accessible through users) and…
• var/generated/hosts.nix 🡕 list (accessible through hosts and host) and…
• var/generated/network.nix 🡕 attrSet (accessible through network).

Usage examples:

• service/dnsmasq.nix 🡕 module uses network to create a full-featured gateway.
• user/build.nix 🡕 module creates some users with users and current host.
• service/ncps.nix 🡕 module uses host and network to declare server and clients.

Network declaration example

Minimal network:

usr/config.yaml

# Global network configuration is converted in lists / attSets to be used in
# your nix configuration through "network" special arg.
network:
  domain: "darkone.lan"
  gateway:
    hostname: "gateway"
    wan:
      interface: "eth0"
    lan:
      interfaces: ["enu1u4"]

Example with more options:

usr/config.yaml

network:
  domain: "darkone.lan"
  timezone: "America/Miquelon"
  locale: "fr_FR.UTF-8"
  gateway:
    hostname: "gateway"
    wan:
      interface: "eth0"
    lan:
      interfaces: ["enu1u4", "wlan0"]
      ip: "192.168.1.1"
      prefixLength: 24
      dhcp-range:
        - "192.168.1.100,192.168.1.230,24h"
      dhcp-extra-option:
        - "option:ntp-server,191.168.1.1"
  extraHosts:
    "192.168.0.1": ["box"]

Users’ declaration example

usr/config.yaml

# Static users
# -> profile is the HomeManager profile
# -> groups is used to select related hosts
users:

  # A nix administrator
  nixos:
    uid: 1000
    name: "An admin user"
    profile: "admin"
    groups: ["admin"]

  # A real user with its own profile "darkone"
  darkone:
    uid: 1001
    name: "Darkone Linux"
    email: "darkone@darkone.yt"
    profile: "darkone"
    groups: ["admin", "media", "common"]

  # A student with specific profile "student"
  ethan:
    uid: 1002
    name: "Ethan"
    profile: "student"
    groups: ["sn", "tsn"]

  # A child of my home network
  esteban:
    uid: 1003
    name: "Esteban"
    profile: "teenager"
    groups: [ "kids", "common" ]

Hosts’ declaration example

usr/config.yaml

# Hosts declaration
# -> name: human readable name or description
# -> profile: the host profile related to this host
# -> users: a list of existing user logins
# -> groups: used to select related users
# -> tags: added to colmena tags for deployment filtering.
# -> local: true is only for the local (master) machine.
hosts:

  # Static hosts
  static:

    # The gateway
    - hostname: "gateway"
      name: "Local Gateway"
      arch: "aarch64-linux"
      profile: "gateway"
      groups: ["admin"]
      aliases: ["gateway", "passerelle"]

    # A laptop
    - hostname: "my-laptop"
      name: "My Laptop"
      profile: "laptop"
      users: ["nixos"]
      groups: ["admin", "common"]
      tags: ["laptops", "admin"]
      aliases: ["my-laptop", "darkone"] # Host name aliases
      interfaces:
        - mac: "e8:ff:1e:d0:44:82"
          ip: "192.168.1.2"
        - mac: "e8:ff:1e:d0:44:83"
          ip: "192.168.1.82"

  # Host groups by range (generated from min to max)
  range:

    # 12 workstations based on the profile "workstation"
    - hostname: "pc%'02s"
      name: "Workstation %d"
      profile: "workstation"
      range: [1, 4]
      groups: ["tsn", "sn"]
      hosts:
        1:
          interfaces:
            - mac: "08:00:27:03:BB:20"
              ip: "192.168.1.101"
        2:
          interfaces:
            - mac: "08:00:27:AE:49:7F"
              ip: "192.168.1.102"
        3:
          interfaces:
            - mac: "08:00:27:EA:85:CB"
              ip: "192.168.1.103"
        4:
          interfaces:
            - mac: "08:00:27:A4:B1:36"
              ip: "192.168.1.104"

  # List of similar hosts (each item is a host)
  list:

    # 3 similar hosts (for the default network)
    - hostname: "laptop-%s"
      name: "Laptop %s"
      profile: "home-laptop"
      groups: ["common"]
      users: ["darkone"]
      hosts:
        kids:
          name: "Kids"
          interfaces:
            - mac: "f0:1f:af:13:61:c6"
              ip: "192.168.1.20"
        family:
          name: "Kids"
          interfaces:
            - mac: "f0:1f:af:13:61:c7"
              ip: "192.168.1.21"

Create a host profile (example)

How to create your own host profile for your local network, based on “desktop” host profile from DNF.

1. Configuring a module for a ready-to-use “workstation” template

   usr/modules/host/workstation.nix

   { lib, config, ... }:
   let
     cfg = config.darkone.host.workstation;
   in
   {
     # A simple .enable declaration for my module
     options = {
       darkone.host.workstation.enable = lib.mkEnableOption "Local workstation host profile";
     };
   
     # If this module is enabled
     config = lib.mkIf cfg.enable {
   
       # Activate all the necessary to have an office PC
       darkone.host.desktop.enable = true;
   
       # Activate the "office" theme with related softwares
       darkone.theme.office.enable = true;
   
       # Add obsidian to the previous configuration
       darkone.graphic.obsidian.enable = true;
     };
   }

   Note

   • There are also pre-configured host profiles in dnf/modules/host.
   • Users linked to the host are declared via users and/or groups.
   • Users and groups can be declared in the configuration or in LDAP.

2. Now, let’s create a workstation host

   usr/config.yaml

   hosts:
     static:
       - hostname: "my-pc"
         name: "A PC"
         profile: workstation
         users: [ "darkone" "john" ]

Tip

To install a new machine, the easiest way is to generate an image:

# A minimal ISO image
nix build .#start-img-iso

# A minimal VM image
nix build .#start-img-vbox

Then, apply the new host:

# Creation or update
just apply pc01

# With an IP if `pc01` is not in your DNS server
just apply pc01 <ip-address>

# Applying all hosts with the tag "desktop"
just apply @desktop

# Applying all hosts used by the user "darkone"
just apply @user-darkone

Create a user profile (example)

Each user have a profile declaration in the nix configuration and a home profile used by home manager. For example:

• dnf/homes/admin.nix contains the users.users. declaration.
• dnf/homes/admin/ contains home manager files for this profile.

1. User creation in the nix general configuration

   usr/homes/sn-user.nix

   # A student for the network "sn"
   { pkgs, lib, config, ... }:
   { initialPassword = "sn2025"; }
   // import ./../../dnf/homes/student.nix { inherit pkgs lib config; }

2. Home manager profile

   usr/homes/sn-user/default.nix

   { pkgs, ... }:
   {
     imports = [ ./../../../dnf/homes/student ];
     home.packages = with pkgs; [
       hunspell
       hunspellDicts.fr-moderne
       libreoffice-fresh
       obsidian
     ];
     home.stateVersion = "25.05";
   }

Work in progress features

Caution

These examples are not yet fully functional and may differ in the future stable version of the project.

LLDAP Users provider

Note

Light LDAP (lldap) 🡕 is a lightweight authentication server that provides an opinionated, simplified LDAP interface for authentication. It integrates with many backends, from KeyCloak to Authelia to Nextcloud and more 🡕.

usr/config.yaml

hostProvider:
  lldap:

    # Use nsswitch to login users, otherwise user configurations are
    # generated in the nix configuration
    nss: true
    url: "ldap://localhost:3890"
    bind:
      user: "admin"
      passwordFile: "lldap" # located in usr/secrets

In reflexion

Danger

Not yet functional at this time.

K8S installation

Master (minimal working configuration) :

{
  # Host k8s-master
  darkone.k8s.master = {
    enable = true;
    modules = {
      nextcloud.enable = true;
      forgejo.enable = true;
    };
  };
}

Slave (known and authorized because declared in the same DNF configuration):

{
  # Host k8s-slave-01
  darkone.k8s.slave = {
    enable = true;
    master.hostname = "k8s-master";
  };
}

Master with options:

{
  # Host k8s-master
  darkone.k8s.master = {
    enable = true;
    modules = {
      nextcloud.enable = true;
      forgejo.enable = true;
    };
    preemtibleSlaves = {
      hosts = [ "k8s-node-01" "k8s-node-02" ];
      xen.hypervisors = [
        {
          dom0 = "xenserver-01";
          vmTemplate = "k8s-node";
          minStatic = 3;
          maxPreemptible = 20;
        }
      ];
    };
  };
}

Introspection commands

# Host list with resume for each
just host

# Host details : settings, activated modules, user list...
just host my-pc

# User list with resume (name, mail, host count)
just user

# User details : content, feature list, host list...
just user darkone