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/services.rst

@@ -1,7 +1,8 @@
 Services systemd
 ================
 
-Trois units, installées sous ``/opt/two/bin`` par ``deploy.sh``.
+Quatre units, installées sous ``/opt/two/bin`` par ``deploy.sh``. Les deux units DHCP
+s'excluent : celle qui tourne dépend de ``dhcp.backend`` (voir :doc:`configuration`).
 
 .. list-table::
    :header-rows: 1
@@ -15,7 +16,10 @@ Trois units, installées sous ``/opt/two/bin`` par ``deploy.sh``.
      - processus principal : API, dispatcher, exécution, watchdog
    * - ``dnsmasq@.service``
      - ``<netns>_<bridge>``
-     - dnsmasq lancé dans le netns du VPC, un par subnet
+     - dnsmasq lancé dans le netns du VPC, un par subnet — backend ``dnsmasq``
+   * - ``dhcp@.service``
+     - ``<netns>_<bridge>``
+     - serveur DHCP intégré, un par subnet — backend ``two``
    * - ``metadata@.service``
      - ``<nom de la VM>``
      - serveur de metadata cloud-init, un par VM
@@ -26,14 +30,15 @@ n'y a pas à les démarrer à la main en fonctionnement normal.
 .. code-block:: bash
 
    systemctl status agent
-   systemctl status 'dnsmasq@vp-admin_br-sn000001'
+   systemctl status 'dnsmasq@vp-admin_br-sn000001'   # backend dnsmasq
+   systemctl status 'dhcp@vp-admin_br-sn000001'      # backend two
    systemctl status 'metadata@i-web'
 
 dnsmasq
 -------
 
-Le script ``run-dnsmasq-in-netns.sh`` entre dans le netns puis exécute dnsmasq avec un fichier
-de configuration par subnet, généré par l'agent :
+Backend historique. Le script ``run-dnsmasq-in-netns.sh`` entre dans le netns puis exécute dnsmasq
+avec un fichier de configuration par subnet, généré par l'agent :
 
 .. list-table::
    :widths: 40 60
@@ -50,6 +55,42 @@ de configuration par subnet, généré par l'agent :
 Le fichier de baux et le journal sont les deux premiers endroits à regarder quand une VM n'obtient
 pas d'adresse.
 
+Serveur DHCP intégré
+--------------------
+
+Backend ``two``. Le script ``run-dhcp-in-netns.sh`` entre dans le netns puis exécute le binaire
+``dhcp``, à qui il passe le bridge à servir et ses deux chemins de fichiers — il ne déduit rien et
+ignore le netns dans lequel il tourne :
+
+.. code-block:: bash
+
+   /opt/two/bin/dhcp -conf /etc/two/agent.yml \
+     -interface br-sn000001 \
+     -state /run/two/dhcp/vp-admin_br-sn000001.state \
+     -socket /run/two/dhcp/vp-admin_br-sn000001.sock
+
+.. list-table::
+   :widths: 40 60
+
+   * - Socket de contrôle
+     - ``/run/two/dhcp/<netns>_<bridge>.sock``
+   * - État
+     - ``/run/two/dhcp/<netns>_<bridge>.state``
+   * - Journal
+     - ``journalctl -u 'dhcp@<netns>_<bridge>'``
+
+Il n'y a **ni fichier de configuration ni fichier de baux**. L'agent pousse l'état désiré sur la
+socket de contrôle : la configuration du subnet à sa création, une réservation par interface à
+chaque création ou suppression de VM. Les réservations sont statiques — une MAC inconnue n'obtient
+rien, et le serveur reste silencieux plutôt que de répondre par un refus.
+
+Le fichier d'état **appartient au processus**, qui l'écrit et le relit à son démarrage. L'agent ne
+l'écrit jamais ; il le supprime seulement, à la création du subnet pour écarter un résidu et à sa
+suppression après avoir arrêté l'unit. Il vit dans ``/run`` parce qu'il n'a aucun sens sans le
+netns, qui ne survit pas au redémarrage de l'host.
+
+Diagnostic : voir :doc:`diagnostic`, qui montre comment interroger la socket.
+
 QEMU n'est pas une unit
 -----------------------
 
@@ -86,6 +127,6 @@ journal au moment d'un ``stop`` n'est donc pas une anomalie.
 Mise à jour
 -----------
 
-``deploy.sh`` relève les instances ``dnsmasq@`` et ``metadata@`` actives **avant** d'arrêter les
+``deploy.sh`` relève les instances ``dnsmasq@``, ``dhcp@`` et ``metadata@`` actives **avant** d'arrêter les
 services, et les redémarre ensuite : c'est la seule façon de savoir lesquelles relancer. Arrêter
 les services à la main avant de lancer le script fait perdre cette liste.