NixOS : comprendre et modifier la configuration

NixOS décrit l’intégralité du système dans un fichier configuration.nix. Modifier ce fichier et lancer nixos-rebuild switch suffit pour ajouter un paquet, activer un service ou créer un utilisateur — sans toucher à un gestionnaire de paquets impératif. Ce guide vous montre comment explorer les options disponibles, modifier la configuration avec confiance, et factoriser le tout en modules lisibles. À la fin, votre VM dispose de fail2ban, d’un firewall, d’un second utilisateur et d’une configuration découpée en fichiers thématiques.

Ce que vous allez apprendre

• Explorer les options NixOS avec nixos-option et search.nixos.org
• Ajouter et supprimer des paquets système (environment.systemPackages)
• Activer et configurer des services : fail2ban, firewall, OpenSSH
• Gérer les utilisateurs et les groupes déclarativement
• Factoriser la configuration en modules (network.nix, users.nix)
• Choisir entre nixos-rebuild switch, test et boot selon le contexte
• Lire le diff de génération avant d’appliquer un changement

Dans quel contexte ?

Ce lab correspond à la situation la plus courante sur NixOS : vous avez un système installé qui fonctionne, et vous voulez le faire évoluer.

• Vous venez d’installer NixOS (Lab 1 ou Lab 2) et vous voulez ajouter fail2ban pour protéger SSH
• Vous avez besoin d’un firewall qui n’autorise que le port 22
• Vous devez créer un second utilisateur pour un collègue ou un service
• Votre configuration.nix grossit et devient difficile à lire — il faut le découper en modules
• Vous voulez comprendre la différence entre switch, test et boot avant de toucher à un serveur

Prérequis

• Lab 1 ou Lab 2 terminé (VM NixOS fonctionnelle avec une flake)
• Familiarité avec le langage Nix (attrsets, listes, with)
• Notion de modules et imports

Anatomie de configuration.nix

Le fichier configuration.nix est une fonction Nix qui reçoit un ensemble d’arguments et retourne un attribute set décrivant le système.

{ config, pkgs, modulesPath, ... }:
{
  # 1. Imports : modules supplémentaires
  imports = [ ... ];

  # 2. Boot : chargeur de démarrage, modules noyau
  boot.loader.systemd-boot.enable = true;

  # 3. Réseau : hostname, firewall, interfaces
  networking.hostName = "nixos-lab";

  # 4. Services : SSH, fail2ban, etc.
  services.openssh.enable = true;

  # 5. Utilisateurs
  users.users.lab = { ... };

  # 6. Paquets système
  environment.systemPackages = with pkgs; [ vim git ];

  # 7. Options Nix
  nix.settings.experimental-features = [ "nix-command" "flakes" ];

  # 8. Version d'état
  system.stateVersion = "25.11";
}

Chaque ligne de ce fichier correspond à une option NixOS déclarée quelque part dans les modules de nixpkgs. Le système de modules fusionne automatiquement toutes les options de tous les fichiers importés.

Ne modifiez jamais system.stateVersion

system.stateVersion indique la version de NixOS lors de l’installation initiale. Il contrôle les valeurs par défaut de certaines options pour la rétrocompatibilité. Ne le changez jamais, même après une mise à jour du système.

Explorer les options disponibles

NixOS propose plus de 15 000 options documentées. Deux outils pour les découvrir :

nixos-option (en ligne de commande)

# Voir la valeur actuelle, le type et la description d'une option
nixos-option services.openssh.enable

Résultat :

Value:
  true

Default:
  false

Type:
  boolean

Description:
  Whether to enable the OpenSSH secure shell daemon, which
  allows secure remote logins.

Pour explorer les sous-options d’un service :

nixos-option services.fail2ban

This attribute set contains:
banaction
banaction-allports
bantime
daemonConfig
daemonSettings
enable
extraPackages
extraSettings
ignoreIP
jails
maxretry
package
packageFirewall

search.nixos.org (interface web)

Le site search.nixos.org/options propose une recherche full-text sur toutes les options NixOS. Tapez un mot-clé (ex : « fail2ban ») pour voir toutes les options associées, leur type, leur valeur par défaut et un lien vers le code source.

Réflexe avant chaque modification

Avant d’ajouter une option dans configuration.nix, vérifiez-la avec nixos-option ou sur search.nixos.org. Cela évite les fautes de frappe et vous montre les options connexes que vous pourriez vouloir configurer.

Ajouter et supprimer des paquets

Les paquets système se déclarent dans environment.systemPackages :

environment.systemPackages = with pkgs; [
  vim
  git
  htop
  curl
  tmux
];

Pour ajouter un paquet, ajoutez-le à la liste. Pour le supprimer, retirez-le. Après chaque modification :

sudo nixos-rebuild switch --flake .#nixos-lab

Le paquet est installé ou supprimé immédiatement dans le profil système.

Paquets système vs paquets utilisateur

environment.systemPackages installe les paquets pour tous les utilisateurs. Pour des paquets spécifiques à un utilisateur, utilisez users.users.<name>.packages :

users.users.lab = {
  packages = with pkgs; [ firefox ];
};

Rechercher un paquet

nix search nixpkgs fail2ban

Cette commande interroge le cache nixpkgs pour trouver les paquets correspondants.

Activer et configurer un service

Activer fail2ban

fail2ban surveille les logs d’authentification et bannit les IP qui échouent trop de fois. Sur NixOS, une seule section suffit :

services.fail2ban = {
  enable = true;
  maxretry = 5;
  bantime = "10m";
  ignoreIP = [ "127.0.0.1/8" "192.168.122.0/24" ];
};

• maxretry = 5 : bannir après 5 échecs
• bantime = "10m" : durée du bannissement
• ignoreIP : ne jamais bannir ces réseaux (votre réseau local)

Configurer le firewall

Le firewall NixOS est activé par défaut, mais bloquer explicitement tout sauf le nécessaire renforce la sécurité :

networking.firewall = {
  enable = true;
  allowedTCPPorts = [ 22 ];
};

Seul le port 22 (SSH) est ouvert. Toute connexion entrante sur un autre port est rejetée.

Appliquer et vérifier

cd /etc/nixos
git add -A && git commit -m "add fail2ban and firewall"
sudo nixos-rebuild switch --flake .#nixos-lab

Vérifications :

# fail2ban actif ?
systemctl is-active fail2ban
# active

# Règles firewall ?
sudo iptables -L nixos-fw -n
# Chain nixos-fw (1 references)
# target     prot opt source               destination
# nixos-fw-accept  tcp  --  0.0.0.0/0       0.0.0.0/0    tcp dpt:22
# nixos-fw-log-refuse  all  --  0.0.0.0/0   0.0.0.0/0

Ouvrir un port supplémentaire

Si vous activez un serveur web plus tard, ajoutez simplement le port :

networking.firewall.allowedTCPPorts = [ 22 80 443 ];

N’oubliez pas que certains services (comme OpenSSH) ouvrent leur port automatiquement via le module NixOS — vérifiez avec nixos-option.

Gérer les utilisateurs et les groupes

Créer un utilisateur

users.users.dev = {
  isNormalUser = true;
  description = "Développeur";
  extraGroups = [ "wheel" ];
  openssh.authorizedKeys.keys = [
    "ssh-ed25519 AAAA... votre-cle-publique"
  ];
};

• isNormalUser = true : crée un home directory et un shell standard
• extraGroups = [ "wheel" ] : accès sudo
• openssh.authorizedKeys.keys : connexion SSH par clé (pas de mot de passe)

Après nixos-rebuild switch, vérifiez :

# L'utilisateur existe ?
id dev
# uid=1001(dev) gid=100(users) groupes=100(users),1(wheel)

# Connexion SSH depuis l'hôte ?
ssh dev@192.168.122.104 whoami
# dev

Supprimer un utilisateur

Retirez simplement le bloc users.users.dev de la configuration et appliquez. NixOS désactive le compte, mais ne supprime pas le home directory par sécurité.

Utilisateurs déclaratifs = source unique de vérité

Sur NixOS, ne créez jamais un utilisateur avec useradd. Le prochain nixos-rebuild switch le supprimerait. Tout doit être déclaré dans configuration.nix (ou un module importé).

Comprendre switch, test et boot

nixos-rebuild propose trois modes d’application :

Commande	Effet immédiat	Boot suivant	Génération créée
switch	Oui — active immédiatement	Oui	Oui
test	Oui — active immédiatement	Non — revient à l’ancienne	Non
boot	Non — rien ne change	Oui — active au reboot	Oui

Glissez pour voir

Quand utiliser chacun

• test : vous voulez vérifier qu’un changement fonctionne avant de le rendre permanent. Si le système plante, un reboot revient à l’état précédent.
• switch : le cas standard — appliquer immédiatement et rendre permanent.
• boot : changement de noyau ou de bootloader — vous voulez que ça prenne effet au prochain reboot sans perturber le système en cours.

# Tester d'abord (recommandé pour les changements risqués)
sudo nixos-rebuild test --flake .#nixos-lab

# Si tout va bien, appliquer
sudo nixos-rebuild switch --flake .#nixos-lab

Réflexe sur un serveur

Sur un serveur de production, utilisez toujours test d’abord. Si le service fonctionne, enchaînez avec switch. Si quelque chose casse, un simple reboot restaure l’état stable.

Lire le diff de génération

Avant d’appliquer un changement, vous pouvez voir exactement ce qui va changer en termes de paquets :

nix profile diff-closures --profile /nix/var/nix/profiles/system

Résultat (extrait) :

Version 2 -> 3:
  fail2ban: ∅ → 1.1.0, +5144.9 KiB
  python3.13-pyinotify: ∅ → 0.9.6, +296.0 KiB
  python3.13-systemd-python: ∅ → 235, +403.1 KiB

Version 3 -> 4:
  NetworkManager: ∅ → ..., +X KiB
  dnsmasq: ∅ → 2.91, +623.2 KiB

Chaque transition montre les paquets ajoutés (∅ → version), supprimés (version → ∅) et mis à jour (ancienne → nouvelle). C’est l’équivalent d’un git diff pour votre système.

Lister les générations

sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

   1   2026-04-14 10:47:12
   2   2026-04-14 11:09:05
   3   2026-04-14 19:19:57
   4   2026-04-14 19:21:14   (current)

Chaque nixos-rebuild switch crée une nouvelle génération. Vous pouvez revenir à n’importe laquelle depuis le boot loader — c’est le sujet du Lab 9.

Organiser la configuration en modules

Quand configuration.nix grossit, découpez-le en fichiers thématiques. NixOS fusionne automatiquement tous les modules importés.

Créer network.nix

Extrayez tout ce qui concerne le réseau et la sécurité réseau :

/etc/nixos/network.nix

{ config, ... }:
{
  networking.hostName = "nixos-lab";
  networking.networkmanager.enable = true;

  networking.firewall = {
    enable = true;
    allowedTCPPorts = [ 22 ];
  };

  services.openssh = {
    enable = true;
    settings = {
      PermitRootLogin = "prohibit-password";
      PasswordAuthentication = false;
    };
  };

  services.fail2ban = {
    enable = true;
    maxretry = 5;
    bantime = "10m";
    ignoreIP = [ "127.0.0.1/8" "192.168.122.0/24" ];
  };
}

Créer users.nix

Extrayez la gestion des utilisateurs :

/etc/nixos/users.nix

{ config, ... }:
{
  users.users.lab = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
    openssh.authorizedKeys.keys = [
      "ssh-ed25519 AAAA... votre-cle-publique"
    ];
  };

  users.users.dev = {
    isNormalUser = true;
    description = "Développeur";
    extraGroups = [ "wheel" ];
    openssh.authorizedKeys.keys = [
      "ssh-ed25519 AAAA... votre-cle-publique"
    ];
  };

  security.sudo.wheelNeedsPassword = false;
}

Simplifier configuration.nix

Le fichier principal ne contient plus que le socle :

/etc/nixos/configuration.nix

{ config, pkgs, modulesPath, ... }:
{
  imports = [
    (modulesPath + "/profiles/qemu-guest.nix")
    ./network.nix
    ./users.nix
  ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;
  boot.initrd.availableKernelModules = [
    "virtio_pci" "virtio_blk" "virtio_scsi" "ahci" "sd_mod"
  ];
  boot.kernelModules = [ "virtio_net" ];

  time.timeZone = "Europe/Paris";
  i18n.defaultLocale = "fr_FR.UTF-8";
  console.keyMap = "fr";

  environment.systemPackages = with pkgs; [
    vim git htop curl tmux
  ];

  nix.settings.experimental-features = [ "nix-command" "flakes" ];

  nix.gc = {
    automatic = true;
    dates = "weekly";
    options = "--delete-older-than 30d";
  };

  system.stateVersion = "25.11";
}

Appliquez et vérifiez que tout fonctionne identiquement :

cd /etc/nixos
git add -A && git commit -m "refactor: split into network.nix and users.nix"
sudo nixos-rebuild switch --flake .#nixos-lab

NixOS fusionne les trois fichiers au moment de l’évaluation. Le résultat est strictement identique à un fichier monolithique — les services et utilisateurs sont préservés.

Quand découper en modules ?

Il n’y a pas de règle absolue. En pratique, découpez dès que configuration.nix dépasse 100 lignes ou quand un collègue a besoin de modifier une partie sans toucher au reste. Un module par responsabilité (réseau, utilisateurs, services applicatifs) est un bon point de départ.

hardware-configuration.nix : ce qu’il contient

Si vous avez suivi le Lab 2 (installation sans disko), vous avez un fichier hardware-configuration.nix généré par nixos-generate-config. Il contient :

• Les modules noyau nécessaires au matériel détecté (virtio, ahci, etc.)
• Les points de montage avec les UUID des partitions
• Le profil de virtualisation (qemu-guest.nix pour les VM KVM)

# Exemple généré
{ config, lib, pkgs, modulesPath, ... }:
{
  imports = [ (modulesPath + "/profiles/qemu-guest.nix") ];

  boot.initrd.availableKernelModules = [
    "ahci" "xhci_pci" "virtio_pci" "virtio_blk"
  ];

  fileSystems."/" = {
    device = "/dev/disk/by-uuid/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    fsType = "ext4";
  };

  fileSystems."/boot" = {
    device = "/dev/disk/by-uuid/XXXX-XXXX";
    fsType = "vfat";
  };
}

Ne modifiez pas hardware-configuration.nix à la main

Ce fichier est régénéré par nixos-generate-config. Si vous le modifiez manuellement, vos changements seront écrasés. Si vous avez besoin de forcer un module noyau, ajoutez-le dans configuration.nix à côté des autres options de boot.

Vérifications

1. fail2ban est actif

   systemctl is-active fail2ban
   # active

2. Le firewall n’autorise que le port 22

   sudo iptables -L nixos-fw -n
   # nixos-fw-accept  tcp  --  0.0.0.0/0  0.0.0.0/0  tcp dpt:22
   # nixos-fw-log-refuse  all  --  0.0.0.0/0  0.0.0.0/0

3. Le second utilisateur fonctionne

   id dev
   # uid=1001(dev) gid=100(users) groupes=100(users),1(wheel)
   ssh dev@192.168.122.104 whoami
   # dev

4. La factorisation en modules est transparente

   ls /etc/nixos/*.nix
   # configuration.nix  disko-config.nix  flake.nix  network.nix  users.nix
   sudo nixos-rebuild switch --flake .#nixos-lab
   # Done. The new configuration is /nix/store/...

5. Les générations sont visibles

   sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
   #    1   2026-04-14 10:47:12
   #    2   2026-04-14 11:09:05
   #    3   2026-04-14 19:19:57
   #    4   2026-04-14 19:21:14   (current)

6. Le diff de génération montre les changements

   nix profile diff-closures --profile /nix/var/nix/profiles/system
   # Version 2 -> 3:
   #   fail2ban: ∅ → 1.1.0, +5144.9 KiB

Dépannage

Symptôme	Cause probable	Solution
nixos-rebuild : « error: attribute ‘xxx’ missing »	Option mal orthographiée	Vérifier avec nixos-option ou search.nixos.org
Un service n’est pas actif après switch	L’option enable = true est absente	Ajouter services.<name>.enable = true
Firewall bloque un service légitime	Port non déclaré	Ajouter le port à networking.firewall.allowedTCPPorts
hardware-configuration.nix modifié par erreur	Modification manuelle	sudo nixos-generate-config pour régénérer
Conflit entre deux modules (même option)	Deux fichiers définissent la même option avec des valeurs incompatibles	Utiliser lib.mkForce ou lib.mkDefault pour la priorité, ou regrouper l’option dans un seul module
nixos-rebuild test fonctionne mais switch échoue	Problème d’écriture du bootloader	Vérifier que /boot est monté et que canTouchEfiVariables = true
Nouveau paquet absent du PATH	nix-rebuild switch pas exécuté	Relancer sudo nixos-rebuild switch --flake .#hostname

Glissez pour voir

À retenir

1. configuration.nix est une fonction Nix qui décrit l’état complet du système — chaque ligne correspond à une option NixOS documentée
2. nixos-option et search.nixos.org sont les deux outils de référence pour découvrir et comprendre les options disponibles
3. Ajouter un service = déclarer services.<name>.enable = true + les options souhaitées, puis nixos-rebuild switch
4. nixos-rebuild test applique sans rendre permanent — idéal pour valider un changement risqué avant switch
5. nix profile diff-closures montre exactement ce qui change entre deux générations — utilisez-le avant chaque switch important
6. Factorisez en modules dès que la configuration dépasse 100 lignes — NixOS fusionne automatiquement tous les imports
7. Ne créez jamais rien de façon impérative (useradd, apt install) — tout changement non déclaré sera perdu au prochain switch

Prochaines étapes

Lab 9 — Réparer : rollback, générations et rescue Quand une modification casse le système, comment revenir en arrière

Lab 2 — Installer avec une flake sans disko Comprendre le rôle de hardware-configuration.nix avec une installation manuelle

Import, factorisation et pinning Aller plus loin dans l'organisation modulaire de la configuration

Le langage Nix Maîtriser la syntaxe utilisée dans les fichiers de configuration

×

📖 Voir la documentation →