docs: premiere creation de documentation

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

docs/exploitation/services.rst

@@ -0,0 +1,91 @@
+Services systemd
+================
+
+Trois units, installées sous ``/opt/two/bin`` par ``deploy.sh``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 32 40
+
+   * - Unit
+     - Instance ``%i``
+     - Rôle
+   * - ``agent.service``
+     - —
+     - processus principal : API, dispatcher, exécution, watchdog
+   * - ``dnsmasq@.service``
+     - ``<netns>_<bridge>``
+     - dnsmasq lancé dans le netns du VPC, un par subnet
+   * - ``metadata@.service``
+     - ``<nom de la VM>``
+     - serveur de metadata cloud-init, un par VM
+
+Les instances sont créées et pilotées par l'agent au fil des créations de subnets et de VM : il
+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 '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 :
+
+.. list-table::
+   :widths: 40 60
+
+   * - Configuration
+     - ``/etc/dnsmasq.d/<netns>_<bridge>.conf``
+   * - Baux
+     - ``/run/dnsmasq-<netns>_<bridge>.leases``
+   * - Journal
+     - ``/var/log/dnsmasq-<netns>_<bridge>.log``
+   * - PID
+     - ``/run/dnsmasq-<netns>_<bridge>.pid``
+
+Le fichier de baux et le journal sont les deux premiers endroits à regarder quand une VM n'obtient
+pas d'adresse.
+
+QEMU n'est pas une unit
+-----------------------
+
+Les processus QEMU sont lancés par ``systemd-run --scope``, **jamais** en unit transitoire. Un
+scope est exécuté par le processus appelant et hérite donc du network namespace posé par
+l'agent ; une unit transitoire, forkée par PID 1, démarrerait dans le netns racine et ne verrait
+pas le tap de la VM.
+
+Conséquence pratique : les VM n'apparaissent pas dans ``systemctl list-units`` mais dans
+``systemd-cgls``, et elles ne survivent pas à un ``systemctl stop agent`` suivi d'un
+redémarrage — l'agent ne réattache pas les VM existantes.
+
+Sockets par VM
+--------------
+
+.. code-block:: text
+
+   /run/two/vms/serial/<vm>.sock     console série
+   /run/two/vms/monitor/<vm>.sock    monitor QEMU
+   /run/two/vms/qmp/<vm>.sock        QMP (utilisé par l'agent)
+
+.. code-block:: bash
+
+   socat -,raw,echo=0 UNIX-CONNECT:/run/two/vms/serial/i-web.sock
+
+Arrêt de l'agent
+----------------
+
+L'ordre d'arrêt est imposé : serveurs HTTP, puis drainage des workers, puis fermeture de la base.
+Si le budget d'arrêt est dépassé, la base **n'est pas fermée** — fermer Badger sous un écrivain
+concurrent est pire qu'un rejeu du journal au démarrage suivant. Un message à ce sujet dans le
+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
+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.