docs: premiere creation de documentation

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

docs/exploitation/configuration.rst

@@ -0,0 +1,138 @@
+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
+``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.
+
+.. danger::
+
+   **L'API de l'agent n'a aucune authentification.** L'exemple livré écoute sur
+   ``0.0.0.0:8080`` : quiconque atteint ce port peut créer et détruire des VM et des réseaux sur
+   l'host KVM, c'est-à-dire en prendre le contrôle.
+
+   Sur tout déploiement réel : restreindre ``api.address`` à une adresse d'administration, ou
+   filtrer le port en amont (pare-feu, réseau dédié). Traiter l'ouverture de ce port comme une
+   décision d'architecture, pas comme un réglage.
+
+Base de données
+---------------
+
+.. code-block:: yaml
+
+   database:
+     path: "/var/lib/two/data/"
+
+Répertoire de la base clé-valeur Badger. **Un seul processus l'ouvre** : l'agent. Ni le serveur
+de metadata ni aucun autre outil ne doit être configuré pour ouvrir le même répertoire pendant
+que l'agent tourne.
+
+Serveurs
+--------
+
+.. code-block:: yaml
+
+   api:
+     address: "0.0.0.0"
+     port: 8080
+
+   prometheus:
+     address: "0.0.0.0"
+     port: 9090
+
+   admin:
+     enabled: false
+     address: "127.0.0.1"
+     port: 9091
+
+``admin`` expose une inspection en lecture seule de la base (``/db?prefix=…``). Elle est
+désactivée par défaut et prévue pour la boucle locale uniquement.
+
+.. warning::
+
+   Le contenu de la base inclut ``vm/<name>/password``, qui est un hash de mot de passe.
+   L'activation de l'API d'administration rend ces valeurs lisibles par tout ce qui atteint le
+   port. Ne pas l'exposer hors de la boucle locale.
+
+Exécution des commandes
+-----------------------
+
+.. code-block:: yaml
+
+   worker:
+     count: 4
+     buffer_size: 100
+
+   dispatcher:
+     timeout_seconds: 300
+     poll_seconds: 2
+
+``worker.count`` est le nombre de goroutines qui exécutent les commandes ; ``buffer_size`` le
+nombre de commandes en attente au-delà duquel ``Dispatch`` bloque.
+
+``dispatcher.timeout_seconds`` borne les opérations qui attendent une transition d'état, dont
+l'extinction d'une VM.
+
+.. warning::
+
+   À l'expiration de ce délai, une VM qui ne s'est pas éteinte reçoit un ``quit`` QMP — un arrêt
+   **brutal**. Pour des charges dont l'extinction est lente (bases de données, construction
+   d'images), une valeur confortable évite un système de fichiers invité incohérent.
+
+Correspondance des interfaces
+-----------------------------
+
+.. code-block:: yaml
+
+   default_interface: br-000000
+
+   interfaces:
+     vms: br-000000
+     internet: br-000000
+     admin: br-000000
+
+Traduit les clés logiques ``iface_type`` de l'API vers les bridges physiques de l'host. Une clé
+inconnue ou omise retombe silencieusement sur ``default_interface`` — ce n'est pas une erreur,
+mais c'est une source de subnets branchés au mauvais endroit sans le dire.
+
+Metadata et QEMU
+----------------
+
+.. code-block:: yaml
+
+   metadata:
+     run_dir: "/run/two/metadata"
+
+   qemu:
+     ovmf_code_path: "/usr/share/OVMF/OVMF_CODE.fd"
+     ovmf_vars_template: "/usr/share/OVMF/OVMF_VARS.fd"
+     uefi_vars_dir: "/run/two/vms/efi"
+     serial_dir: "/run/two/vms/serial"
+     monitor_dir: "/run/two/vms/monitor"
+     qmp_dir: "/run/two/vms/qmp"
+
+Les chemins OVMF sont nécessaires aux VM démarrées avec ``uefi: true`` (paquet ``ovmf`` sur
+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.
+
+Watchdog
+--------
+
+.. code-block:: yaml
+
+   watchdog:
+     enabled: true
+     interval_seconds: 60
+
+Vérification périodique **en lecture seule** — voir :doc:`/exploitation/observabilite`.
+
+Journalisation
+--------------
+
+.. code-block:: yaml
+
+   logger:
+     level: info   # debug, info, warn, error
+     debug: false  # force le niveau debug quel que soit level