Écrire une première configuration NixOS

Un fichier configuration.nix est une expression Nix qui déclare l’état complet d’un système NixOS. Vous ne lancez pas de commandes pour installer des paquets ou activer des services — vous décrivez ce que vous voulez, et nixos-rebuild switch calcule exactement ce qu’il faut faire. Maîtriser configuration.nix, c’est maîtriser la couche qui transforme le langage Nix (attrsets, fonctions, options) en système vivant. Ce guide montre comment franchir le saut entre « je connais les attrsets » et « j’ai une configuration système qui fonctionne ».

Ce que vous allez apprendre

• Lire la structure générale d’un fichier Nix : expression, arguments { config, pkgs, ... }:, bloc de sortie
• Comprendre l’anatomie d’un configuration.nix minimal section par section
• Distinguer un paquet (pkgs.xxx) d’une option NixOS (services.xxx.enable)
• Trouver la bonne option dans la documentation NixOS avec search.nixos.org et nixos-option
• Écrire une configuration concrète : paquets, SSH sécurisé, utilisateur admin
• Appliquer les changements avec nixos-rebuild switch sans interrompre le service
• Modulariser en fichiers séparés avec imports

Dans quel contexte ?

Dès que vous travaillez sur un système NixOS — en VM de test, en serveur de production ou en homelab — configuration.nix est le fichier central. Savoir le lire et le modifier devient indispensable pour :

• personnaliser un serveur NixOS installé depuis une image ou un template cloud,
• reproduire un environnement identique sur plusieurs machines depuis un dépôt Git,
• activer un service (SSH, Docker, Nginx) sans chercher la bonne commande d’installation,
• diagnostiquer pourquoi un service ne démarre pas après un rebuild,
• préparer la migration vers les flakes en comprenant d’abord la configuration de base.

Ce guide s’appuie sur les bases du langage Nix (attrsets, fonctions, let, with). Si ces notions ne sont pas encore familières, commencez par ce guide.

La forme générale d’un fichier Nix

Tout fichier .nix est une expression — une valeur calculée, pas un script. Un configuration.nix est une fonction qui reçoit des arguments et retourne un attrset d’options :

{ config, pkgs, ... }:
{
  # vos options ici
}

Les trois parties essentielles :

Partie	Rôle
{ config, pkgs, ... }:	Arguments que NixOS injecte à l’évaluation. config expose les valeurs de toute la config ; pkgs donne accès à nixpkgs. ... accepte d’autres arguments sans les nommer.
{ ... }	Le corps de la fonction : un attrset dont chaque attribut est une option NixOS (networking.hostName, services.openssh.enable, etc.).
;	Chaque option dans l’attrset se termine par un point-virgule — c’est la syntaxe Nix, pas du YAML.

Glissez pour voir

Pourquoi une fonction et pas juste un attrset ?

NixOS évalue votre fichier comme une fonction pour pouvoir passer des arguments contextuels : la liste des modules, le matériel détecté, les options d’autres modules. Cela permet à services.openssh.enable = true; d’installer automatiquement les paquets nécessaires, de créer la configuration /etc/ssh/, et de démarrer le service — tout ça déclenché par une seule option.

Anatomie d’un configuration.nix minimal

Voici le squelette complet d’une configuration de base, commenté section par section :

{ config, pkgs, ... }:

{
  # ── 1. Imports ──────────────────────────────────────────────────────────────
  imports = [
    ./hardware-configuration.nix   # généré automatiquement lors de l'installation
  ];

  # ── 2. Bootloader ───────────────────────────────────────────────────────────
  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  # ── 3. Réseau ───────────────────────────────────────────────────────────────
  networking.hostName = "monserveur";
  networking.networkmanager.enable = true;

  # ── 4. Locale et fuseau horaire ─────────────────────────────────────────────
  time.timeZone = "Europe/Paris";
  i18n.defaultLocale = "fr_FR.UTF-8";

  # ── 5. Paquets système ──────────────────────────────────────────────────────
  environment.systemPackages = with pkgs; [
    git
    vim
    curl
    wget
  ];

  # ── 6. Services ─────────────────────────────────────────────────────────────
  services.openssh.enable = true;

  # ── 7. Utilisateurs ─────────────────────────────────────────────────────────
  users.users.admin = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };

  # ── 8. Version d'état ───────────────────────────────────────────────────────
  system.stateVersion = "24.05";   # ← ne jamais modifier après l'installation
}

Section	Ce qu’elle contrôle	Remarque importante
imports	Fichiers .nix inclus dans l’évaluation	hardware-configuration.nix est généré par nixos-generate-config
boot.loader	GRUB ou systemd-boot, BIOS ou UEFI	Dépend du mode de démarrage de votre machine
networking.*	Nom d’hôte, interfaces, DNS, firewall	networkmanager pour les postes de travail, firewall pour les serveurs
time.timeZone	Fuseau horaire système	Format IANA : Europe/Paris, UTC, America/New_York
environment.systemPackages	Paquets disponibles pour tous les utilisateurs	with pkgs; importe le scope nixpkgs dans la liste
services.*	Activation et configuration des services	Un module NixOS par service
users.users.*	Déclaration des utilisateurs et groupes	Chaque utilisateur est un attrset de sa propre configuration
system.stateVersion	Version NixOS au moment de l’installation initiale	Ne jamais modifier — gère la compatibilité des données persistantes

Glissez pour voir

Paquets vs options : la distinction clé

C’est la source de confusion la plus fréquente pour les nouveaux utilisateurs NixOS.

	Paquet (pkgs.xxx)	Option service (services.xxx.enable)
Ce que c’est	Un logiciel à rendre disponible	Une déclaration de comportement système
Où on le place	Dans environment.systemPackages	Directement dans le corps de la config
Ce qu’il fait	Rend le binaire accessible dans PATH	Installe le paquet et configure et démarre le service
Exemple	pkgs.nginx (juste le binaire)	services.nginx.enable = true; (le tout)

Glissez pour voir

Règle pratique : si un service a un module NixOS (services.xxx), utilisez-le — il gère les paquets, la configuration et l’unité systemd. N’ajoutez pas nginx dans environment.systemPackages si vous utilisez services.nginx.enable = true;.

# ✅ Correct : le module NixOS gère tout
services.nginx.enable = true;

# ❌ Redondant et source de conflits
environment.systemPackages = with pkgs; [ nginx ];
services.nginx.enable = true;

Trouver la bonne option

1. search.nixos.org — le moteur officiel, le plus rapide :

https://search.nixos.org/options?query=openssh

2. nixos-option — interroge les options disponibles sur le système actif :

# Lister les sous-options d'un service
nixos-option services.openssh

# Obtenir valeur actuelle + description d'une option
nixos-option services.openssh.enable
# Value:       true
# Default:     false
# Description: Whether to enable the OpenSSH secure shell daemon.
# Declared by: <nixpkgs/nixos/modules/services/networking/ssh/sshd.nix>

3. nix repl avec nixpkgs chargé :

nix repl '<nixpkgs/nixos>'
# nix-repl> :t options.services.openssh
# nix-repl> options.services.openssh.enable

Premier cas pratique

Objectif

Configurer un serveur NixOS avec :

• git, vim, curl, htop disponibles en ligne de commande
• SSH activé avec authentification par mot de passe désactivée
• Un utilisateur admin dans le groupe wheel (accès sudo)
• Fuseau horaire Europe/Paris

La configuration complète

{ config, pkgs, ... }:

{
  imports = [
    ./hardware-configuration.nix
  ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  networking.hostName = "serveur-prod";
  networking.networkmanager.enable = true;

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

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

  services.openssh = {
    enable = true;
    settings = {
      PasswordAuthentication = false;
      PermitRootLogin = "no";
    };
  };

  users.users.admin = {
    isNormalUser = true;
    description = "Administrateur système";
    extraGroups = [ "wheel" ];
    openssh.authorizedKeys.keys = [
      "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... votre_cle_publique"
    ];
  };

  security.sudo.wheelNeedsPassword = false;

  system.stateVersion = "24.05";
}

Appliquer les changements

1. Éditer le fichier (en root ou via sudo)

   sudo vim /etc/nixos/configuration.nix

2. Valider la configuration sans l’appliquer

   sudo nixos-rebuild dry-build
   # Construire sans rien changer au système — sortie d'erreur si syntaxe incorrecte

3. Appliquer les changements

   sudo nixos-rebuild switch
   # Build + activation immédiate + entrée dans le bootloader

4. Vérifier le résultat

   # Paquets disponibles ?
   which git vim curl htop
   
   # SSH démarré ?
   systemctl status sshd
   
   # Utilisateur créé ?
   id admin

switch, boot, test : quelles différences ?

• switch — applique immédiatement les changements sur le système en cours d’exécution.
• boot — prépare le prochain démarrage sans toucher au système actuel.
• test — applique immédiatement mais sans créer d’entrée dans le bootloader (non persistant après reboot).
• dry-build — construit le tout sans rien appliquer — idéal pour valider avant d’aller plus loin.

Erreurs classiques et comment les éviter

Erreur	Symptôme	Solution
Oublier le ;	error: expected ';', got ...	Chaque option dans un attrset se termine par ;
Confondre [ ] et { }	Erreur de type lors du build	systemPackages attend une liste [ ], pas un attrset { }
Mettre un paquet là où une option est attendue	Le service ne démarre pas	services.nginx.enable = pkgs.nginx est faux — écrire = true
Modifier system.stateVersion	Comportement imprévisible sur les données existantes	Ne jamais changer after l’installation initiale
Oublier git add avant rebuild	Les nouveaux fichiers importés sont ignorés	git add . avant nixos-rebuild quand la config est dans un dépôt

Glissez pour voir

Lire un message d’erreur Nix

error: attribute 'gittt' missing
       at /etc/nixos/configuration.nix:12:5:
           11|   environment.systemPackages = with pkgs; [
           12|     gittt
               ^
           13|   ];

• attribute 'gittt' missing — le paquet n’existe pas dans nixpkgs, faute de frappe probable.
• at …:12:5 — ligne 12, colonne 5 — le curseur est précis.
• Correction : nix search nixpkgs git pour trouver le nom exact.

Première modularisation : diviser la configuration

Dès que configuration.nix dépasse une cinquantaine de lignes, découpez-le en fichiers thématiques.

Structure proposée

/etc/nixos/
├── configuration.nix         ← entrée principale + options globales
├── hardware-configuration.nix
├── users.nix                 ← déclaration des utilisateurs
└── services/
    └── ssh.nix               ← configuration SSH

users.nix

{ config, pkgs, ... }:

{
  users.users.admin = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
    openssh.authorizedKeys.keys = [
      "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
    ];
  };
}

services/ssh.nix

{ config, pkgs, ... }:

{
  services.openssh = {
    enable = true;
    settings = {
      PasswordAuthentication = false;
      PermitRootLogin = "no";
    };
  };
}

configuration.nix avec imports

{ config, pkgs, ... }:

{
  imports = [
    ./hardware-configuration.nix
    ./users.nix
    ./services/ssh.nix
  ];

  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  networking.hostName = "serveur-prod";
  time.timeZone = "Europe/Paris";

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

  system.stateVersion = "24.05";
}

nixos-rebuild switch évalue tous les fichiers listés dans imports comme s’ils n’en formaient qu’un seul. C’est simple et suffisant pour la majorité des configurations.

Import versus module NixOS

imports = [ ./users.nix ] inclut simplement le contenu du fichier dans la même évaluation. Ce n’est pas encore un module NixOS au sens strict (qui utilise options = {} et config = {} pour définir des options configurables depuis l’extérieur). La factorisation avancée avec modules est abordée dans le guide sur l’import et la factorisation.

Dépannage

Erreur	Cause probable	Vérification	Solution
error: syntax error	; manquant ou accolade non fermée	Ligne indiquée dans le message d’erreur	Vérifier ; en fin d’option, { } équilibrés
attribute 'xxx' missing	Paquet ou option inexistante	nix search nixpkgs xxx ou nixos-option xxx	Corriger le nom ou trouver l’option équivalente
nixos-rebuild switch bloque	Build de dépendances volumineux	journalctl -u nixos-rebuild en parallèle	Attendre — première activation peut être longue
Failed to start sshd.service	Configuration SSH invalide ou port déjà utilisé	systemctl status sshd + journalctl -u sshd	Vérifier services.openssh.settings, port 22 libre
Service absent après rebuild	Option enable = false ou non déclarée	nixos-option services.xxx.enable	Ajouter ou corriger l’option dans la config
file 'hardware-configuration.nix' not found	Fichier manquant dans le chemin importé	ls /etc/nixos/	Regénérer avec sudo nixos-generate-config

Glissez pour voir

À retenir

• configuration.nix est une fonction Nix — elle reçoit config et pkgs, et retourne un attrset d’options NixOS.
• Paquet (environment.systemPackages) et option service (services.xxx.enable) sont deux mécanismes distincts — les modules NixOS font les deux à la fois, ne doublez pas.
• Utilisez search.nixos.org/options ou nixos-option localement pour trouver la bonne option.
• nixos-rebuild dry-build valide sans appliquer — utilisez-le systématiquement avant switch.
• system.stateVersion ne se modifie jamais après l’installation initiale.
• La modularisation avec imports = [ ./fichier.nix ] est simple et efficace — découpez tôt.

Prochaines étapes

Environnements de développement reproductibles mkShell, Python, Node.js, Rust, direnv — créer des shell.nix pour vos projets

Import, factorisation et pinning Modulariser ses fichiers Nix, figer nixpkgs avec fetchTarball, modules paramétrisables

NixOS : installer et évaluer un premier système De la configuration au système complet : flakes, disko et première VM KVM

Bases du langage Nix Retour aux fondamentaux : types, attrsets, fonctions, let-in, with

×

📖 Voir la documentation →