router/tools/ipadm/README.md

ipadm

Kleines Go-CLI-Tool zur Verwaltung statischer Hosts (DHCP-Reservierung + DNS-Eintrag) und WAN→LAN-Port-Forwards für den dnsmasq/nftables-Router auf narcissus. Ersetzt/lehnt sich an das Original-Tool ipadm (dhcp/bind management, mwx'2021) an, arbeitet aber gegen unseren dnsmasq/nftables-Stack statt isc-dhcp-server/bind9 (siehe ../../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, und /etc/ipadm/portforwards (wanport<TAB>proto<TAB>host<TAB>lanport) für Port-Forwards. Ein Port-Forward referenziert einen Hostnamen aus der Host-Datenbank statt einer festen IP, damit er automatisch der aktuellen IP des Hosts folgt.

• ipadm -u generiert daraus zwei Dateien und reloadet die zugehörigen Dienste:

  • /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 mit dnsmasq --test, danach systemctl reload dnsmasq.
  • /etc/nftables.d/portforward.conf (eine eigene table inet portforward mit einer dnat-Regel pro Port-Forward, referenzierte Host-IP wird zum Generierungszeitpunkt aus der Host-DB aufgelöst), validiert mit nft -c -f /etc/nftables.conf (dafür bindet /etc/nftables.conf bereits include "/etc/nftables.d/*.conf" ein), danach systemctl reload nftables.

  Schlägt die jeweilige Validierung fehl, wird die vorherige generierte Datei automatisch wiederhergestellt und der betroffene Dienst nicht neu geladen. Referenziert ein Port-Forward einen mittlerweile gelöschten Host, wird er beim Generieren übersprungen und als Warnung ausgegeben, statt den ganzen Lauf abzubrechen.

• 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).

• Port-Forwards werden über (wan-port, protokoll) eindeutig identifiziert; both (= tcp+udp in einer Regel via meta l4proto { tcp, udp }) kollidiert dabei mit einem einzelnen tcp- oder udp-Eintrag auf demselben Port.

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 -pa [-f] <hostname> <wan-port> [lan-port] [tcp|udp|both]
                                                       add port-forward zu bekanntem Host
ipadm -pl                                              list port-forwards
ipadm -pd <wan-port> [tcp|udp|both]                    delete port-forward
ipadm -u                                              update (dnsmasq+nftables-Config regenerieren + reload)
ipadm -h                                              this help

Beispiel:

ipadm -a webserver 10.0.0.10          # Host anlegen (falls noch nicht vorhanden)
ipadm -pa webserver 443 tcp           # WAN-Port 443/tcp -> webserver:443
ipadm -pa webserver 8080 80 tcp       # WAN-Port 8080/tcp -> webserver:80
ipadm -u                              # anwenden (dnsmasq + nftables)

lan-port und Protokoll bei -pa sind optional und in beliebiger Reihenfolge angebbar (Default lan-port = wan-port, Default Protokoll tcp) — das Tool erkennt selbst, ob ein Token eine Portnummer oder tcp/udp/both ist.

Nach jeder Änderung an der Host- oder Port-Forward-DB (-a, -c, -i, -m, -r, -d, -pa, -pd, interaktiv) muss ipadm -u ausgeführt werden, damit dnsmasq/nftables die Änderung tatsächlich übernehmen — das Tool weist nach jeder Änderung selbst darauf hin.

Bauen / Installieren

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:

export IPADM_DB=/tmp/test-hosts
export IPADM_PORTFWD_DB=/tmp/test-portforwards
export IPADM_DNSMASQ_HOSTS=/tmp/test-hosts.conf
export IPADM_NFT_PORTFWD=/tmp/test-portforward.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
export IPADM_WAN_IFACE=enp3s0
./ipadm -a testhost 10.0.0.50 aa:bb:cc:dd:ee:ff
./ipadm -l

Achtung: ipadm -u ruft trotzdem dnsmasq --test bzw. nft -c -f /etc/nftables.conf auf (prüft die echte System-Konfiguration) und bei Erfolg systemctl reload dnsmasq/systemctl reload nftables, auch im Testmodus — das ist beabsichtigt (validiert, dass die generierte Datei mit der echten Umgebung zusammenspielt), aber es reloadet die echten laufenden Dienste. IPADM_NFT_PORTFWD nur auf einen Pfad außerhalb von /etc/nftables.d/ zeigen lassen, sonst landet die Testdatei im echten Include und wird real aktiv.