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