|
Xdev Host Manager
authored
2 days ago
|
1
|
# Host Manager MVP
|
|
|
2
|
|
|
|
3
|
Host Manager este o aplicație web locală, Perl-only, pentru registrul de hosturi Madagascar. Nu folosește npm, pip sau pachete CPAN instalate direct pe host.
|
|
|
4
|
|
|
|
5
|
## Politica de dependențe
|
|
|
6
|
|
|
|
7
|
Perl-ul livrat de distribuție este acceptat ca bază de runtime. Modulele Perl incluse în distribuție sau în core pot fi folosite direct.
|
|
|
8
|
|
|
|
9
|
Pachetele CPAN nu se instalează direct pe host cu `cpan`, `cpanm` sau mecanisme similare. Dacă aplicația are nevoie de un modul CPAN, modulul trebuie făcut disponibil prin repo-ul local după audit. Este acceptabilă o versiune mai veche/stabilă din repo-ul local; nu urmărim neapărat ultima versiune upstream.
|
|
|
10
|
|
|
|
11
|
MVP-ul curent nu are dependențe CPAN externe.
|
|
|
12
|
|
|
|
13
|
## Rol
|
|
|
14
|
|
|
|
15
|
`config/hosts.yaml` este registrul editabil și trebuie menținut în git. Aplicația îl expune read-only pentru servicii și, cu autentificare OTP, permite modificări controlate în working tree.
|
|
|
16
|
|
|
|
17
|
Git rămâne mecanismul de audit, istoric și rollback. Aplicația nu înlocuiește repo-ul și nu devine o bază de date separată.
|
|
|
18
|
|
|
|
19
|
Endpoint-uri publice read-only:
|
|
|
20
|
|
|
|
21
|
- `/download/hosts.yaml` — registrul complet
|
|
|
22
|
- `/download/local-hosts.tsv` — manifest DNS local derivat
|
|
|
23
|
- `/download/monitoring.json` — listă pentru monitorizare
|
|
|
24
|
- `/api/hosts` — JSON cu hosturi și probleme detectate
|
|
|
25
|
|
|
|
26
|
Endpoint-uri cu OTP:
|
|
|
27
|
|
|
|
28
|
- `POST /api/hosts/upsert`
|
|
|
29
|
- `POST /api/hosts/delete`
|
|
|
30
|
- `POST /api/render/local-hosts-tsv`
|
|
|
31
|
|
|
|
32
|
## Pornire locală
|
|
|
33
|
|
|
|
34
|
```bash
|
|
|
35
|
HOST_MANAGER_TOTP_SECRET="BASE32_SECRET_AICI" \
|
|
|
36
|
perl scripts/host_manager.pl --bind 127.0.0.1 --port 8088
|
|
|
37
|
```
|
|
|
38
|
|
|
|
39
|
Deschide:
|
|
|
40
|
|
|
|
41
|
```text
|
|
|
42
|
http://127.0.0.1:8088/
|
|
|
43
|
```
|
|
|
44
|
|
|
|
45
|
Implicit serverul ascultă doar pe loopback. Pe jumper, publicarea se face prin nginx, ca vhost separat, cu proxy către `127.0.0.1:8088`.
|
|
|
46
|
|
|
|
47
|
Vhost-ul implicit propus este:
|
|
|
48
|
|
|
|
49
|
```text
|
|
|
50
|
hosts.madagascar.xdev.ro
|
|
|
51
|
```
|
|
|
52
|
|
|
|
53
|
Configurațiile de deployment sunt în `deploy/jumper/`.
|
|
|
54
|
|
|
|
55
|
Instanța de pe jumper este instalată în `/usr/local/xdev-host-manager` și publicată prin:
|
|
|
56
|
|
|
|
57
|
```text
|
|
|
58
|
http://hosts.madagascar.xdev.ro/
|
|
|
59
|
```
|
|
|
60
|
|
|
|
61
|
Secretul TOTP nu este în repo. Pentru bootstrap, citește URI-ul root-only de pe jumper:
|
|
|
62
|
|
|
|
63
|
```bash
|
|
|
64
|
ssh is-vpn-gw 'cat /etc/xdev/host-manager.totp-uri'
|
|
|
65
|
```
|
|
|
66
|
|
|
|
67
|
## OTP
|
|
|
68
|
|
|
|
69
|
`HOST_MANAGER_TOTP_SECRET` trebuie să fie un secret Base32 compatibil TOTP. Fără această variabilă, download-urile read-only funcționează, dar login-ul și scrierile nu.
|
|
|
70
|
|
|
|
71
|
Secretul nu se comite în repo. Dacă avem nevoie de integrare cu un manager de secrete sau systemd environment file, se definește separat pe host.
|
|
|
72
|
|
|
|
73
|
## Flux
|
|
|
74
|
|
|
|
75
|
1. Hosturile se editează în aplicație sau direct în `config/hosts.yaml`.
|
|
|
76
|
2. Serviciile externe descarcă `/download/hosts.yaml`, `/download/local-hosts.tsv` sau `/download/monitoring.json`.
|
|
|
77
|
3. Pentru DNS local, butonul `Write local-hosts.tsv` regenerează `config/local-hosts.tsv`.
|
|
|
78
|
4. Sincronizarea efectivă către is-vpn-gw și as01 rămâne:
|
|
|
79
|
|
|
|
80
|
```bash
|
|
|
81
|
./scripts/sync_local_hosts.sh --apply --verify
|
|
|
82
|
```
|
|
|
83
|
|
|
|
84
|
## Git și managementul cheilor
|
|
|
85
|
|
|
|
86
|
Varianta preferată pentru servicii automate este să citească `config/hosts.yaml` din git, nu să depindă direct de sesiunea web. Serviciile care sincronizează DNS, monitorizare sau inventare primesc chei dedicate, cu acces minim.
|
|
|
87
|
|
|
|
88
|
Reguli:
|
|
|
89
|
|
|
|
90
|
- Fiecare host/serviciu automat are propria cheie SSH, fără reutilizare între roluri.
|
|
|
91
|
- Cheile de consum sunt read-only pentru repo.
|
|
|
92
|
- Cheile care pot scrie în repo sunt rare, separate și folosite doar de componenta de management.
|
|
|
93
|
- Cheile nu se comit în repo și nu se pun în `hosts.yaml`.
|
|
|
94
|
- Pentru deployment pe hosturi, se preferă chei restrânse la comanda necesară sau deploy keys read-only unde platforma git permite.
|
|
|
95
|
- Pull-ul automat trebuie să valideze fișierele înainte de aplicare; de exemplu `perl -c scripts/host_manager.pl` și `./scripts/sync_local_hosts.sh --verify` după generarea DNS.
|
|
|
96
|
|
|
|
97
|
Modelul recomandat:
|
|
|
98
|
|
|
|
99
|
```text
|
|
|
100
|
git repo
|
|
|
101
|
config/hosts.yaml sursă versionată
|
|
|
102
|
config/local-hosts.tsv manifest generat/versionat pentru DNS local
|
|
|
103
|
|
|
|
104
|
jumper
|
|
|
105
|
host-manager editează working tree cu OTP
|
|
|
106
|
sync_local_hosts.sh aplică DNS după review/verificare
|
|
|
107
|
|
|
|
108
|
servicii consumatoare
|
|
|
109
|
git pull read-only citesc hosts.yaml/monitoring.json/local-hosts.tsv
|
|
|
110
|
```
|
|
|
111
|
|
|
|
112
|
Pentru etapa MVP, aplicația nu face commit/push automat. După o modificare, schimbarea rămâne vizibilă în working tree și se comite explicit după review. Automatizarea commit/push poate fi adăugată ulterior, dar numai cu cheie separată și reguli clare de semnare/audit.
|
|
|
113
|
|
|
|
114
|
## Limitări MVP
|
|
|
115
|
|
|
|
116
|
- Parserul YAML acceptă schema strictă generată de aplicație, nu YAML arbitrar.
|
|
|
117
|
- Conflict engine-ul verifică doar consistența locală din `hosts.yaml`.
|
|
|
118
|
- DHCP, mDNS, `hosts-local.yaml` și `madagascar.json` sunt încă surse pentru audit manual sau pentru următorul collector.
|