Add ipadm: Go-Tool zur Verwaltung statischer DHCP/DNS-Hosts

2026-08-18 11:17:16 +02:00
parent dc1d490e26
commit 49bad1fec1
8 changed files with 818 additions and 0 deletions
@@ -0,0 +1,73 @@
+# ipadm
+
+Kleines Go-CLI-Tool zur Verwaltung statischer Hosts (DHCP-Reservierung +
+DNS-Eintrag) für den dnsmasq-Router auf narcissus. Ersetzt/lehnt sich an das
+Original-Tool `ipadm` (dhcp/bind management, mwx'2021) an, arbeitet aber
+gegen unseren dnsmasq-Stack statt isc-dhcp-server/bind9 (siehe
+[../../README.md](../../README.md)).
+
+Installiert auf dem Server unter `/usr/local/bin/ipadm`.
+
+## Funktionsweise
+
+- Pflegt eine flache Textdatei `/etc/ipadm/hosts` (eine Zeile pro Host:
+  `name<TAB>ip<TAB>mac<TAB>comment`, `mac` ist `-` wenn nicht gesetzt) als
+  Datenbank für statische Hosts.
+- `ipadm -u` generiert daraus `/etc/dnsmasq.d/hosts.conf` (pro Host ein
+  `host-record=` für DNS, plus `dhcp-host=` für Hosts mit MAC-Adresse für die
+  DHCP-Reservierung), validiert die komplette dnsmasq-Konfiguration
+  (`dnsmasq --test`) und lädt dnsmasq bei Erfolg neu
+  (`systemctl reload dnsmasq`). Schlägt die Validierung fehl, wird die
+  vorherige `hosts.conf` automatisch wiederhergestellt und dnsmasq **nicht**
+  neu geladen.
+- IP-Adressen werden bei `-a`/`-i`/im interaktiven Modus geprüft: müssen in
+  `10.0.0.0/24` liegen und **außerhalb** des dynamischen DHCP-Pools
+  `10.0.0.100–10.0.0.200` (verhindert Kollisionen mit dynamisch vergebenen
+  Adressen).
+
+## Usage
+
+```
+ipadm <hostname>                                     add/edit host (interaktiv)
+ipadm -l                                              list hosts
+ipadm -a [-f] <hostname> <ip address> [mac address]   add host
+ipadm -c <hostname> <comment>                         set comment
+ipadm -i <hostname> <ip address>                      change ip address
+ipadm -m <hostname> <mac address>                     change mac address
+ipadm -r <old hostname> <new hostname>                rename host
+ipadm -d <hostname>                                   delete host
+ipadm -u                                              update (dnsmasq-Config regenerieren + reload)
+ipadm -h                                              this help
+```
+
+Nach jeder Änderung an der Host-DB (`-a`, `-c`, `-i`, `-m`, `-r`, `-d`,
+interaktiv) muss `ipadm -u` ausgeführt werden, damit dnsmasq die Änderung
+tatsächlich übernimmt — das Tool weist nach jeder Änderung selbst darauf hin.
+
+## Bauen / Installieren
+
+```sh
+cd tools/ipadm
+go build -o ipadm .
+install -m 0755 -o root -g root ipadm /usr/local/bin/ipadm
+```
+
+## Testen ohne die echte Server-Konfiguration anzufassen
+
+Alle Pfade sind über Umgebungsvariablen überschreibbar:
+
+```sh
+export IPADM_DB=/tmp/test-hosts
+export IPADM_DNSMASQ_HOSTS=/tmp/test-hosts.conf
+export IPADM_LAN_CIDR=10.0.0.0/24
+export IPADM_POOL_START=10.0.0.100
+export IPADM_POOL_END=10.0.0.200
+./ipadm -a testhost 10.0.0.50 aa:bb:cc:dd:ee:ff
+./ipadm -l
+```
+
+Achtung: `ipadm -u` ruft trotzdem `dnsmasq --test` (prüft die echte
+System-Konfiguration in `/etc/dnsmasq.conf` + `/etc/dnsmasq.d/`) und bei
+Erfolg `systemctl reload dnsmasq` auf, auch im Testmodus — das ist
+beabsichtigt (validiert, dass die generierte Datei mit der echten
+Umgebung zusammenspielt), aber es reloadet den echten laufenden Dienst.