f-46: doc: document the dhcp backend and its switch procedure #46

Note de version 0.2.0 (Bael), et reprise des huit pages de docs/ qui parlaient
de dnsmasq ou du DHCP.

Ajouts de fond : la section Backend DHCP de la page de configuration, avec la
procédure de bascule manuelle et l'avertissement qu'elle ne migre rien ; la
section du serveur intégré dans les services ; et dans la page de diagnostic
comment interroger la socket de contrôle, probe étant le point de départ le plus
rapide quand une VM n'obtient pas d'adresse.

Le nom de version se déduit du rang, pas du numéro : deuxième release, deuxième
nom de codenames.md.

Construit avec sphinx-build -W --keep-going, sans avertissement.

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

docs/exploitation/configuration.rst

@@ -1,12 +1,19 @@
 Configuration
 =============
 
-Un seul fichier, ``/etc/two/agent.yml``, partagé par les trois binaires : ``agent -config``,
-``metadata -conf`` et ``db -conf``. Le fichier de référence commenté est
+Un seul fichier, ``/etc/two/agent.yml``, partagé par les quatre binaires : ``agent -config``,
+``metadata -conf``, ``db -conf`` et ``dhcp -conf``. Le fichier de référence commenté est
 ``conf/agent/config.exemple.yml`` dans le dépôt.
 
 Le chargement se fait par **viper** : les clés sont celles ci-dessous, en YAML.
 
+.. warning::
+
+   Un fichier **absent** est toléré : toutes les valeurs par défaut s'appliquent. Un fichier
+   **présent mais invalide** fait en revanche échouer le démarrage, volontairement — jusqu'à
+   la version 0.1.0 il était ignoré en silence, et l'agent tournait alors entièrement sur les
+   défauts sans le dire. Une tabulation d'indentation ou un ``--`` égaré suffisent.
+
 .. danger::
 
    **L'API de l'agent n'a aucune authentification.** L'exemple livré écoute sur
@@ -117,6 +124,71 @@ Les chemins OVMF sont nécessaires aux VM démarrées avec ``uefi: true`` (paque
 Debian et Ubuntu). ``uefi_vars_dir`` reçoit une copie inscriptible des variables UEFI par VM,
 créée au démarrage et supprimée à l'arrêt.
 
+Backend DHCP
+------------
+
+.. code-block:: yaml
+
+   dhcp:
+     backend: dnsmasq   # ou two
+
+Choisit qui sert le DHCP des subnets **créés par cet agent** :
+
+.. list-table::
+   :header-rows: 1
+   :widths: 14 44 42
+
+   * - Valeur
+     - Serveur
+     - Unit
+   * - ``dnsmasq``
+     - dnsmasq, configuré par fichiers dans ``/etc/dnsmasq.d``
+     - ``dnsmasq@<netns>_<bridge>``
+   * - ``two``
+     - le binaire ``dhcp``, piloté par socket Unix
+     - ``dhcp@<netns>_<bridge>``
+
+Le défaut est ``dnsmasq`` : un fichier de configuration de la 0.1.0, non modifié, se comporte
+exactement comme avant. Toute autre valeur que ``dnsmasq`` ou ``two`` fait échouer le démarrage.
+
+Le répertoire d'exécution du backend ``two`` — ``/run/two/dhcp`` — **n'est pas configurable** :
+le script d'enrobage le code en dur, une clé que lui ignorerait serait un mensonge.
+
+Ce que le backend ``two`` apporte : la configuration DHCP devient modifiable par VM et non plus
+seulement par subnet, ce qui permet de n'annoncer la route par défaut que sur **une** interface
+d'une VM multi-réseaux. Le watchdog peut en outre interroger le serveur et comparer ce qu'il sert
+à ce que la base dit — voir :doc:`diagnostic`.
+
+Bascule d'un backend à l'autre
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+   L'option ne décide que du backend des **nouveaux** subnets. Elle ne migre rien : un subnet
+   déjà créé continue d'être servi par le serveur qui l'a été. Changer la valeur sans vider
+   l'hyperviseur laisse l'agent parler à un serveur qui ne tourne pas — les VM existantes
+   continuent, les nouvelles n'obtiennent pas d'adresse.
+
+La bascule est **manuelle** et suppose un hyperviseur vide :
+
+1. Supprimer toutes les VM, puis tous les subnets, puis les VPC.
+2. Vérifier qu'il ne reste aucune unit DHCP active et aucun résidu :
+
+   .. code-block:: bash
+
+      systemctl list-units 'dnsmasq@*' 'dhcp@*'
+      ls /etc/dnsmasq.d/ /run/two/dhcp/
+
+3. Modifier ``dhcp.backend`` dans ``/etc/two/agent.yml``.
+4. ``systemctl restart agent`` — la valeur est lue au démarrage, pas à chaque commande.
+5. Recréer VPC, subnets et VM.
+6. Sur la première VM, vérifier l'adresse **et les trois routes** : la route par défaut, la
+   route vers le CIDR du VPC, et la route ``/32`` vers ``169.254.169.254``. C'est cette
+   dernière qui conditionne le provisionnement cloud-init.
+
+Le retour arrière suit la même procédure. Il n'y a pas de bascule à chaud, dans un sens ni dans
+l'autre.
+
 Watchdog
 --------