f-86: doc: DNS et NTP des VM, two-hostsvc, notes 0.3.0 #86

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
GnomeZworc 2026-10-25 21:11:20 +01:00
commit 46653c9f62
Signed by: nicolas.boufideline
GPG key ID: 4406BBBF8845D632
10 changed files with 224 additions and 8 deletions

85
docs/concepts/dns-ntp.rst Normal file
View file

@ -0,0 +1,85 @@
DNS et NTP des VM
=================
Les VM résolvent les noms et lisent l'heure par leur gateway : le DHCP annonce l'``interface_ip``
du subnet comme serveur DNS (option 6) et NTP (option 42), dans les deux backends. Un relais
unique par hyperviseur, ``two-hostsvc``, répond derrière cette adresse dans le netns de chaque
VPC. Une VM sans sortie Internet garde ainsi DNS et NTP, et aucune route n'est ouverte entre la
VRF du VPC et l'hôte.
Chemin d'une requête
--------------------
.. mermaid::
graph LR
V["VM<br/>vers interface_ip:53 ou :123"] --> N["netns du VPC<br/>chaîne TWO-HOSTSVC<br/>DNAT vers 169.254.169.253"]
N --> H["two-hostsvc<br/>socket dans le netns<br/>169.254.169.253 sur la dummy hostsvc"]
H -->|"depuis l'hôte"| U["serveurs amont<br/>puis résolveur ou horloge de l'hôte"]
À la création d'un VPC sur l'hyperviseur, l'agent pose dans son netns :
* une interface ``dummy`` ``hostsvc`` portant ``169.254.169.253/32`` ;
* une chaîne iptables ``TWO-HOSTSVC`` (table ``nat``), appelée depuis ``PREROUTING`` pour le seul
trafic à destination d'une adresse locale du netns (``addrtype LOCAL`` : les gateways des
subnets, anycast compris). Elle renvoie d'abord ce qui arrive par ``br-public`` (le segment
public de l'hôte) et par ``l3-+`` (le lien vers la VRF), puis redirige 53 en UDP et TCP et 123
en UDP vers ``169.254.169.253`` ;
puis demande à ``two-hostsvc`` d'ouvrir ses sockets dans ce netns. La réponse repart par
conntrack, avec l'adresse de la gateway pour source. Une VM qui interroge un résolveur extérieur
(par une passerelle NAT) n'est pas redirigée : seules les adresses locales du netns le sont.
À la suppression du VPC, l'agent demande la fermeture des sockets ; la ``dummy`` et la chaîne
disparaissent avec le netns.
**Si ``two-hostsvc`` ne répond pas, la création du VPC échoue** (``error``) plutôt que de créer
un VPC sans DNS ni NTP ; la suppression échoue de même si la fermeture échoue, et se relance
depuis ``error``. ``two-hostsvc`` doit donc tourner sur tout hyperviseur avant la création d'un
VPC.
Le relais
---------
``two-hostsvc`` est un seul processus par hyperviseur (``two-hostsvc.service``). Il entre dans le
netns de chaque VPC le temps d'y ouvrir trois sockets sur ``169.254.169.253`` (53/UDP, 53/TCP,
123/UDP), qui restent attachées à ce netns ; les requêtes vers l'amont partent de l'espace
réseau de l'hôte.
DNS
La requête est transmise telle quelle aux serveurs de ``hostsvc.dns_upstream``, puis à ceux de
``/etc/resolv.conf`` de l'hôte. Seule une question standard est acceptée ; une réponse amont
dont l'identifiant ne correspond pas est ignorée. Pas de cache : rien de ce qu'un locataire
demande n'est gardé pour un autre.
NTP
La requête est relayée aux serveurs de ``hostsvc.ntp_upstream`` ; une réponse dont
l'horodatage d'origine ne correspond pas est ignorée. Sans serveur amont, ou sans réponse,
``two-hostsvc`` répond depuis l'horloge de l'hôte (SNTP, stratum 3) ; si l'hôte n'est pas
synchronisé, la réponse porte l'indicateur d'alarme (LI = 3, stratum 16) et les clients
l'ignorent.
Limite de débit
``hostsvc.rate_limit_per_vpc`` requêtes par seconde, DNS et NTP confondus, par VPC ; au-delà,
les requêtes sont abandonnées. Au plus 16 connexions TCP simultanées par VPC.
Le relais garde la liste des VPC servis dans ``/run/two/hostsvc/hostsvc.state`` : à son
redémarrage, il rouvre seul les sockets des VPC dont le netns existe encore. Sa socket de
contrôle, ``/run/two/hostsvc/hostsvc.sock`` (mode 600), n'est utilisée que par l'agent.
Isolation
---------
* Le relais n'écoute que sur une adresse link-local, et seulement dans les netns des VPC ; il ne
crée aucune route.
* Une réponse ne repart que vers l'adresse qui a posé la question, par la socket du VPC.
* Le trafic du segment public (``br-public``) et du lien vers la VRF n'atteint pas le relais.
* L'unité systemd ne garde que trois capacités : ``CAP_SYS_ADMIN`` (entrer dans un netns),
``CAP_NET_BIND_SERVICE`` (ports 53 et 123) et ``CAP_DAC_READ_SEARCH`` (les fichiers de
``/run/netns`` sont en mode 000). Le système de fichiers lui est en lecture seule, hors
``/run/two/hostsvc``.
* Les netns créés après le démarrage du service ne lui sont visibles que si ``/`` est en
propagation ``shared``, le réglage par défaut de systemd.
Si ``two-hostsvc`` s'arrête, DNS et NTP s'arrêtent pour tous les VPC de l'hyperviseur ;
systemd le relance (``Restart=on-failure``) et le watchdog le signale.

View file

@ -12,3 +12,4 @@ fonctionnent entre eux. Le contrat HTTP correspondant est dans
modes-reseau
cycle-de-vie
metadata-cloud-init
dns-ntp

View file

@ -25,6 +25,11 @@ public est celui de ``interfaces.internet``, ``br-public`` si la clé est absent
accroche ``vxlan-public``, le VXLAN du segment public partagé avec les bordures
(:doc:`/demarrage/installation`) ; sans ce bridge, toute création de VPC échoue.
Dans le netns, l'agent pose aussi la ``dummy`` ``hostsvc`` (``169.254.169.253/32``) et la chaîne
iptables ``TWO-HOSTSVC``, puis demande à ``two-hostsvc`` de servir le VPC : c'est le chemin du
DNS et du NTP des VM (voir :doc:`dns-ntp`). Si ``two-hostsvc`` ne répond pas, la création du VPC
échoue.
Un VPC ne peut être supprimé que si tous ses subnets le sont déjà — sinon 409.
Routage entre hyperviseurs : ``l3vni``

View file

@ -165,11 +165,12 @@ Vérifier l'installation
.. code-block:: bash
systemctl status agent
systemctl status two-hostsvc agent
curl -s http://127.0.0.1:8080/vpcs
Une liste JSON — vide au premier démarrage — signifie que l'API répond. Passez à
:doc:`/demarrage/premier-vpc`.
Une liste JSON — vide au premier démarrage — signifie que l'API répond. ``two-hostsvc``, le relais
DNS et NTP des VM, doit être actif : sans lui, la création d'un VPC échoue (voir
:doc:`/concepts/dns-ntp`). Passez à :doc:`/demarrage/premier-vpc`.
.. important::

View file

@ -145,11 +145,13 @@ hyperviseurs : les adresses et les taps de l'underlay ne changent pas, ceux du s
sont renumérotés.
**Tester l'arbre courant plutôt que la release.** ``test/e2e/build.sh`` compile ``agent``,
``dhcp`` et ``metadata`` pour linux/amd64 dans ``test/e2e/topologies/bin/`` (ignoré par git),
que les hyperviseurs reçoivent par ``files: {bin: bin}``. Après ``deploy.sh``,
``dhcp``, ``metadata`` et ``two-hostsvc`` pour linux/amd64 dans ``test/e2e/topologies/bin/``
(ignoré par git), et y copie l'unit ``two-hostsvc.service``, absente de la release 0.2.0 ; les
hyperviseurs reçoivent le répertoire par ``files: {bin: bin}``. Après ``deploy.sh``,
``hypervisor.sh`` installe chaque binaire présent dans ``/opt/two/local/bin/`` et y fait pointer
``/opt/two/bin/<nom>`` ; le reste (units, scripts) vient de la release. ``build.sh --clean`` vide
le répertoire : le lab suivant teste la release seule.
``/opt/two/bin/<nom>``, puis installe, active et redémarre chaque unit ``*.service`` présente ; le
reste (units, scripts) vient de la release. ``build.sh --clean`` vide le répertoire : le lab
suivant teste la release seule.
.. code-block:: text

View file

@ -282,6 +282,31 @@ La bascule est **manuelle** et suppose un hyperviseur vide :
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.
Relais DNS et NTP
-----------------
.. code-block:: yaml
hostsvc:
dns_upstream: []
ntp_upstream: []
rate_limit_per_vpc: 100
Lue par ``two-hostsvc`` (voir :doc:`../concepts/dns-ntp`), au démarrage du service.
``dns_upstream``
résolveurs interrogés en premier, sous la forme ``ip`` ou ``ip:port`` (port 53 par défaut).
Ceux de ``/etc/resolv.conf`` de l'hôte viennent ensuite ; liste vide : l'hôte seul.
``ntp_upstream``
serveurs NTP relayés en premier, ``ip`` ou ``ip:port`` (port 123 par défaut). Sans serveur ou
sans réponse, l'horloge de l'hôte répond.
``rate_limit_per_vpc``
requêtes par seconde, DNS et NTP confondus, pour chaque VPC.
Un nom d'hôte, un port hors de 1–65535 ou une limite nulle ou négative font échouer le
démarrage de l'agent comme de ``two-hostsvc``, qui lisent le même fichier. Une modification prend
effet au redémarrage de ``two-hostsvc``.
Watchdog
--------

View file

@ -163,6 +163,41 @@ réellement écrit :
Un base64 invalide, lui, aurait été rejeté en 400 à la création.
La VM ne résout pas les noms ou n'a pas l'heure
-----------------------------------------------
La VM interroge sa gateway (``interface_ip``), que le DHCP annonce en DNS et en NTP ; la requête
est redirigée vers ``two-hostsvc`` dans le netns du VPC (voir :doc:`../concepts/dns-ntp`).
.. code-block:: bash
# Dans la VM : DNS et NTP annoncés par le bail (systemd-networkd)
sudo cat /run/systemd/netif/leases/$(cat /sys/class/net/ens3/ifindex) | grep -E '^(DNS|NTP)='
# Sur l'hyperviseur
systemctl status two-hostsvc
cat /run/two/hostsvc/hostsvc.state # le VPC doit y figurer
ip -n <vpc> -4 addr show dev hostsvc # 169.254.169.253/32
ip netns exec <vpc> iptables -t nat -S TWO-HOSTSVC # 2 RETURN puis 3 DNAT
ip netns exec <vpc> iptables -t nat -L TWO-HOSTSVC -v -n # compteurs des redirections
ip netns exec <vpc> ss -lntu | grep 169.254.169.253 # 53/udp, 53/tcp, 123/udp
journalctl -u two-hostsvc -n 50
Causes rencontrées :
* ``two-hostsvc`` arrêté : plus de DNS ni de NTP pour aucun VPC de l'hyperviseur, et un VPC créé
pendant ce temps part en ``error`` ;
* adresse ``169.254.169.253`` ou règle de la chaîne retirée à la main : la requête n'arrive plus
au relais ; le watchdog le signale ;
* VPC créé par une version antérieure à la 0.3.0 : ni ``dummy`` ni chaîne ni socket. Le recréer ;
* ``open`` refusé par ``two-hostsvc`` avec ``permission denied`` ou ``invalid argument`` sur
``/var/run/netns/<vpc>`` : l'unit n'a pas ``CAP_DAC_READ_SEARCH``, ou le netns, créé après le
démarrage du service, ne lui est pas visible parce que ``/`` n'est pas en propagation
``shared`` (``findmnt -no PROPAGATION /``). Rencontré en conteneur, pas sur un hyperviseur.
Sans serveur ``ntp_upstream`` qui réponde, l'heure vient de l'horloge de l'hyperviseur : si
celle-ci n'est pas synchronisée, la réponse porte l'indicateur d'alarme et la VM l'ignore.
La VM ne démarre pas (UEFI)
---------------------------

View file

@ -42,6 +42,16 @@ public (``interfaces.internet``) doit exister, être actif et porter un port VXL
(``vxlan-public``), sinon les VPC de l'hôte n'ont pas de segment public. Il ne vérifie pas le
numéro du VNI.
Dès qu'un VPC est ``running`` sur l'hyperviseur, il contrôle aussi le relais DNS et NTP (voir
:doc:`../concepts/dns-ntp`) :
* ``two-hostsvc`` injoignable sur sa socket de contrôle : une notification, aucun VPC de
l'hyperviseur n'a plus de DNS ni de NTP ;
* pour chaque VPC ``running`` : VPC absent de la liste servie par ``two-hostsvc``,
``169.254.169.253`` absente de la ``dummy`` ``hostsvc``, ou chaîne ``TWO-HOSTSVC`` absente ou
incomplète dans son netns. Un VPC créé par une version antérieure à la 0.3.0 n'a rien de tout
cela : il est signalé à chaque tick jusqu'à sa recréation.
Avec une section ``bgp`` dans la configuration, il contrôle aussi le plan de contrôle :
* **Sessions BGP** : une notification par route reflector dont la session n'est pas

View file

@ -1,7 +1,7 @@
Services systemd
================
Quatre units, installées dans ``/etc/systemd/system`` par ``deploy.sh`` ; les binaires et scripts
Cinq units, installées dans ``/etc/systemd/system`` par ``deploy.sh`` ; les binaires et scripts
qu'elles lancent sont sous ``/opt/two/bin``. Les deux units DHCP
s'excluent : celle qui tourne dépend de ``dhcp.backend`` (voir :doc:`configuration`).
@ -24,6 +24,10 @@ s'excluent : celle qui tourne dépend de ``dhcp.backend`` (voir :doc:`configurat
* - ``metadata@.service``
- ``<nom de la VM>``
- serveur de metadata cloud-init, un par VM
* - ``two-hostsvc.service``
- —
- relais DNS et NTP des VM, un par hyperviseur, démarré avant l'agent (voir
:doc:`../concepts/dns-ntp`)
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.
@ -34,6 +38,7 @@ n'y a pas à les démarrer à la main en fonctionnement normal.
systemctl status 'dnsmasq@vp-admin_br-000001' # backend dnsmasq
systemctl status 'dhcp@vp-admin_br-000001' # backend two
systemctl status 'metadata@i-web'
systemctl status two-hostsvc
dnsmasq
-------
@ -96,6 +101,27 @@ processus serait mort sans nettoyer (``SIGKILL``, plantage).
Diagnostic : voir :doc:`diagnostic`, qui montre comment interroger la socket.
Relais DNS et NTP
-----------------
``two-hostsvc.service`` lance ``/opt/two/bin/two-hostsvc``, un seul processus par hyperviseur,
qui sert DNS et NTP aux VM de tous les VPC (voir :doc:`../concepts/dns-ntp`). Il lit la section
``hostsvc`` de ``/etc/two/agent.yml`` (voir :doc:`configuration`).
.. list-table::
:widths: 40 60
* - Socket de contrôle
- ``/run/two/hostsvc/hostsvc.sock``
* - État
- ``/run/two/hostsvc/hostsvc.state`` (VPC servis)
* - Journal
- ``journalctl -u two-hostsvc``
L'unit démarre avant ``agent.service`` et se relance en cas d'échec. Son répertoire
``/run/two/hostsvc`` survit à un redémarrage du service : le processus y relit la liste des VPC
servis et rouvre leurs sockets. Un VPC ne peut pas être créé tant que le service ne répond pas.
QEMU n'est pas une unit
-----------------------

View file

@ -14,6 +14,23 @@
quand ses VM sont en `deleting`, et attend leur suppression jusqu'à `timeout_subnet_stop`. Le
409 reste pour une VM ni supprimée ni en `deleting`
**DNS et NTP des VM par l'hyperviseur : `two-hostsvc` (#86)**
- Nouveau service `two-hostsvc.service`, un par hyperviseur, démarré avant l'agent : il relaie
DNS (UDP et TCP) et NTP pour les VM de tous les VPC, depuis l'adresse `169.254.169.253` posée
dans le netns de chaque VPC. Une VM sans sortie Internet garde DNS et NTP, sans route entre la
VRF du VPC et l'hôte
- **Le DHCP annonce l'`interface_ip` du subnet comme DNS (option 6) et NTP (option 42)**, dans les
deux backends ; `1.1.1.1` et `8.8.8.8` ne sont plus annoncés. Les requêtes des VM vers leur
gateway sur 53 et 123 sont redirigées vers `two-hostsvc` ; celles vers un résolveur extérieur
ne le sont pas
- Nouvelle section `hostsvc` de la configuration : `dns_upstream` et `ntp_upstream` (serveurs
interrogés en premier ; à défaut, le résolveur et l'horloge de l'hôte) et `rate_limit_per_vpc`
(100 requêtes par seconde par défaut, DNS et NTP confondus)
- **La création d'un VPC échoue si `two-hostsvc` ne répond pas**, plutôt que de créer un VPC sans
DNS ni NTP. Le watchdog signale un `two-hostsvc` injoignable et, pour chaque VPC, un élément
manquant (adresse, redirection, VPC non servi)
**Filtrage au port de chaque VM (#76)**
- Chaque interface de VM ne peut émettre que depuis sa propre MAC et sa propre IP. Sont rejetés
@ -94,3 +111,12 @@
et les valeurs par défaut de `times` s'appliquent. Une valeur personnalisée de
`dispatcher.timeout_seconds` est à reporter dans `times.timeout_vms_stop` (et dans les délais
qui en dépendent)
- **DNS et NTP (#86) : vider l'hyperviseur avant la mise à jour, puis recréer les VPC.** Les VPC
créés par la 0.2.0 n'ont ni l'adresse `169.254.169.253`, ni la redirection, ni de place dans
`two-hostsvc`, et l'agent ne les reprend pas au démarrage. Or le serveur DHCP intégré (backend
`two`) annonce la gateway comme DNS dès son redémarrage par `deploy.sh` : au renouvellement
de leur bail (au plus 6 h), les VM de ces VPC perdraient leur DNS. Avec dnsmasq, le fichier de
configuration n'est pas régénéré et les VM gardent `1.1.1.1`. Dans les deux cas, le watchdog
signale ces VPC à chaque tick. Procédure : supprimer VM, subnets et VPC de l'hyperviseur,
mettre à jour avec `deploy.sh` (qui installe et démarre `two-hostsvc`), vérifier
`systemctl status two-hostsvc`, puis recréer VPC, subnets et VM