# Adăugare hosturi locale — madagascar network

Rețeaua madagascar folosește un **DNS intern dual**: jumper (192.168.2.100) ca resolver principal și as01 (192.168.2.2) ca fallback. Un hostname nou trebuie adăugat în **ambele locuri**.

Numele vechi `is-vpn-gw` este deprecated. Folosește `jumper` sau `jumper.madagascar.xdev.ro` în scripturi și documentație.

Regula importantă: local nu se folosește wildcard pentru `*.madagascar.xdev.ro`. Doar hostname-urile cunoscute din `config/local-hosts.tsv` se rezolvă local; orice nume necunoscut, inclusiv typo-uri precum `nohost.madagascar.xdev.ro`, trebuie să întoarcă `NXDOMAIN`.

Domeniul vechi `.vad.is.xdev.ro` este deprecated. Nu se adaugă intrări noi pentru el și nu se păstrează aliasuri locale pentru acest namespace.

## De ce dual?

Jumper este sus pe "lista de sacrificiu" la power outage — poate fi oprit deliberat. Fără intrările de pe as01, clienții nu pot rezolva hostname-urile interne când jumper e oprit.

## Unde se adaugă

| Loc | Fișier | Rol |
|-----|--------|-----|
| jumper `/etc/hosts` | resolver principal, precedență maximă față de dnscrypt-proxy | Funcționează și când dnscrypt-proxy e down |
| jumper `/etc/dnscrypt-proxy/cloaking-rules.txt` | servit clienților LAN prin dnscrypt-proxy | Clienții care cer DNS la 192.168.2.100 primesc IP-ul intern |
| as01 `/ip dns static` (MikroTik) | fallback când jumper e oprit | as01 servește direct din cache static propriu |

Zona publică poate avea nume Madagascar care ajung la IP-ul public `89.32.222.226`. Pentru LAN, fiecare nume real care există și local trebuie să aibă override exact în ambele resolvere, altfel va cădea în DNS public și va ajunge greșit la `.226`.

Implementarea versionată este:

| Fișier | Rol |
|--------|-----|
| `var/host-manager.sqlite` | sursa de adevăr runtime pentru registry și Work Orders |
| `config/hosts.yaml` | seed/snapshot export pentru hosturi și FQDN-uri canonice |
| `config/local-hosts.tsv` | export DNS generat din registry-ul SQLite, cu A records pentru hosturi/aliasuri de host și CNAME records pentru vhosturi |
| `scripts/sync_local_hosts.sh` | citește manifestul DNS din SQLite-ul runtime de pe jumper și sincronizează `/etc/hosts`, `cloaking-rules.txt` și `/ip dns static` |

`madagascar.xdev.ro` este domeniul implicit. Pentru orice host real `*.madagascar.xdev.ro`, aliasul scurt este derivat automat. De exemplu, `autonas01.madagascar.xdev.ro` publică și `autonas01`. Vhosturile, de exemplu `pmx.baobab.madagascar.xdev.ro`, se publică drept CNAME către hostul care le servește; aliasul scurt derivat, de exemplu `pmx.baobab`, este tot CNAME. Aliasurile derivate nu se declară separat în registry.

## Ierarhia surselor

Când inventarele se contrazic, ordinea de încredere este:

1. DHCP lease/reservation pe router (`admin@192.168.2.1`) — autoritatea pentru alocarea IP-urilor pe LAN. Configurațiile statice locale nu au voie să mute un IP peste DHCP; cel mult semnalează o rezervare lipsă sau o intrare veche.
2. `cluster/cluster-context/madagascar.json` — autoritatea pentru roluri, topologie și IP-uri de serviciu. Pentru nodurile Proxmox, DNS-ul de serviciu poate folosi interfața `thunderbridge` (`192.168.10.x`) chiar dacă management/WAN este `192.168.2.x`.
3. `var/host-manager.sqlite` — registry-ul operațional aprobat, editat prin Madagascar Local Authority.
4. `config/local-hosts.tsv` — manifestul DNS local publicat pe jumper și as01. Acesta este un export al registry-ului SQLite și nu sursa primară pentru sync; sincronizarea citește manifestul runtime de pe jumper.
5. `hosts-local.yaml` — inventar SSH: aliasuri, utilizatori, entrypoint-uri și căi de acces. IP-urile de aici sunt utile pentru audit, dar pot fi stale dacă DHCP spune altceva.
6. mDNS (`*.local`) — sursă observată de descoperire și validare. Confirmă prezența unui host sau propune aliasuri, dar nu creează automat intrări `madagascar.xdev.ro`.
7. DNS public — folosit doar pentru acces extern. Local, numele interne trebuie shadow-uite exact sau lăsate nerezolvate; wildcard-ul public nu este autoritate pentru LAN.

Reguli de împăcare:

- Pentru un IP de LAN, DHCP câștigă în fața oricărei valori hardcodate în inventare.
- Pentru un IP de serviciu non-LAN, `madagascar.json` câștigă dacă explică explicit interfața sau rolul.
- Pentru VM-uri, regula `vmid -> 192.168.2.vmid` este convenție de propunere și audit, nu autoritate. Rezervarea DHCP finală decide.
- Prefixele istorice `is-`, `vad-` și `b-` se elimină la normalizarea numelor. `.vad.is.xdev.ro` rămâne deprecated și nu se reactivează prin aliasuri.
- Dacă o sursă observată există doar în mDNS sau doar în lease-uri dinamice, se raportează ca propunere, nu se sincronizează automat în DNS.

## Listener mDNS

`scripts/mdns_host_seed.pl` ascultă multicast mDNS pe `224.0.0.251:5353`, colectează recorduri `A` pentru nume `*.local` din intervale private/link-local și seeduiește baza runtime SQLite.

Locația implicită:

```text
var/host-manager.sqlite#mdns_observations
```

Regulă importantă: listenerul mDNS scrie doar în tabelul `mdns_observations`; nu modifică registry-ul de hosturi, `config/hosts.yaml` sau `config/local-hosts.tsv`. Seed-ul mDNS rămâne observație separată până la review.

Rulare manuală pentru test:

```bash
perl scripts/mdns_host_seed.pl --verbose --once --timeout 120
```

Dry-run:

```bash
perl scripts/mdns_host_seed.pl --dry-run --verbose --timeout 30
```

Pe jumper, listenerul poate rula ca serviciu separat:

```bash
sudo install -m 0644 deploy/jumper/host-manager-mdns.service /etc/systemd/system/host-manager-mdns.service
sudo systemctl daemon-reload
sudo systemctl enable --now host-manager-mdns
```

Pe jumper, LAN-ul trebuie servit direct de `dnscrypt-proxy` pe `192.168.2.100:53`. `systemd-resolved` rămâne doar stub local și trebuie să aibă `ReadEtcHosts=no` plus upstream unic `DNS=127.0.0.1:5300`. Altfel fie publică intrările din `/etc/hosts` către clienții LAN, fie ocolește cloaking-rules și întreabă DNS public direct. Scriptul de sync verifică și aplică aceste setări.

`dnscrypt-proxy` folosește blocklist; `google.com` și `www.google.com` sunt allowlist-uite explicit ca să nu fie întoarse ca `0.0.0.0`.

## Colector DHCP

Routerul DHCP `192.168.2.1` împinge evenimente de lease către Madagascar Local Authority prin:

```text
POST https://192.168.2.100/api/collect/dhcp-leases
X-DHCP-Push-Token: <HOST_MANAGER_DHCP_PUSH_TOKEN>
```

Endpoint-ul scrie doar în `dhcp_leases` și actualizează `data_workers.last_run_at`; nu modifică automat registry-ul de hosturi, `config/hosts.yaml` sau `config/local-hosts.tsv`.

Scriptul RouterOS versionat este:

```text
deploy/mikrotik/dhcp-lease-push.rsc
```

Înainte de import, setează tokenul real în `/etc/xdev/host-manager.env` pe jumper și în variabila `hostManagerDhcpPushToken` din scriptul RouterOS. Scriptul setează `lease-script` pe serverele DHCP existente; dacă routerul are deja un `lease-script`, codul trebuie îmbinat manual ca să nu se piardă logica existentă.

Rulează întâi dry-run:

```bash
./scripts/sync_local_hosts.sh
```

Aplică și verifică:

```bash
./scripts/sync_local_hosts.sh --apply --verify
```

## Pași pentru un hostname nou

```bash
# 1. Adaugă hostul în Madagascar Local Authority.
# Aplicația păstrează registry-ul în var/host-manager.sqlite.

# 2. Aplică pe ambele resolvere
./scripts/sync_local_hosts.sh --apply --verify

# 3. Verificare manuală, dacă e nevoie
dig @192.168.2.100 host.madagascar.xdev.ro +short   # via jumper
dig @192.168.2.2   host.madagascar.xdev.ro +short   # via as01

# 4. Verificare negativă: numele inexistente nu trebuie să se rezolve
dig @192.168.2.100 nohost.madagascar.xdev.ro +short
dig @192.168.2.2   nohost.madagascar.xdev.ro +short
```

Comenzile negative de mai sus trebuie să întoarcă output gol, iar cu `+comments` statusul trebuie să fie `NXDOMAIN`.

## Politica de adresare

Registry-ul de cluster publică un singur IP rutabil pentru fiecare host. Micromanagement-ul local, inclusiv orice intrări `127.0.0.1 localhost localhost.localdomain` sau override-uri locale pe host, nu se administrează din Madagascar Local Authority.

## Hosturi speciale — excepții

| Hostname | /etc/hosts pe jumper | cloaking-rules | Motiv |
|----------|------------------------|----------------|-------|
| `mazeri.madagascar.xdev.ro` | 192.168.2.102 | 192.168.2.102 | Mașina Debian la .102, separată de jumper chiar dacă Exim folosește acest hostname |
| `jumper.madagascar.xdev.ro` | 192.168.2.100 | 192.168.2.100 | Registry-ul publică doar adresa rutabilă; orice comportament local special rămâne responsabilitatea hostului |

## Hosturi existente

| Hostname | IP |
|----------|----|
| `baobab.madagascar.xdev.ro` | 192.168.10.91 |
| `mazeri.madagascar.xdev.ro` | 192.168.2.102 |
| `jumper.madagascar.xdev.ro` | 192.168.2.100 |
| `hosts.madagascar.xdev.ro` | 192.168.2.100 (vhost nginx pe jumper) |
| `zabbix.madagascar.xdev.ro` | 192.168.2.107 |
| `toltec.madagascar.xdev.ro` | 192.168.2.103 |
| `ebony.madagascar.xdev.ro` | 192.168.10.92 |
| `tapia.madagascar.xdev.ro` | 192.168.10.93 |
| `autonas01.madagascar.xdev.ro` | 192.168.10.21 |
| `autonas02.madagascar.xdev.ro` | 192.168.10.22 |
| `anjothibe.madagascar.xdev.ro` | 192.168.2.95 |
| `andrafiabe.madagascar.xdev.ro` | 192.168.2.96 |
| `pmx.baobab.madagascar.xdev.ro` | 192.168.10.91 |
| `pmx.ebony.madagascar.xdev.ro` | 192.168.10.92 |
| `pmx.tapia.madagascar.xdev.ro` | 192.168.10.93 |
| `pbs.anjothibe.madagascar.xdev.ro` | 192.168.2.95 |
| `pbs.andrafiabe.madagascar.xdev.ro` | 192.168.2.96 |

## Verificări obligatorii după modificări

```bash
# Host real: trebuie să întoarcă IP intern pe ambele resolvere
dig @192.168.2.100 baobab.madagascar.xdev.ro +short
dig @192.168.2.2   baobab.madagascar.xdev.ro +short

# Host inexistent: trebuie să rămână nerezolvat local
dig @192.168.2.100 nohost.madagascar.xdev.ro +noall +comments
dig @192.168.2.2   nohost.madagascar.xdev.ro +noall +comments
```

## DNS public (zones/xdev.ro.zone)

Hostname-urile interne **nu se adaugă** în zona publică. Excepție: dacă un hostname intern are și un port forward public, se adaugă în zona publică numai pentru acces extern și trebuie shadow-uit local prin override exact.

> RFC 2181: un MX record nu poate pointa la un CNAME. Dacă adaugi un hostname care va primi MX, trebuie să fie A record în zona publică — vezi cazul `mazeri`.
