Add docker-ip-addr-manager initial app

2026-03-18 21:43:59 +01:00
parent 2fddde0129
commit 69011271fc
19 changed files with 1920 additions and 0 deletions
@@ -0,0 +1,105 @@
+# Docker IP Addr Manager
+
+Docker IP Addr Manager ger ett enkelt GUI i ZimaOS för att hantera host-IP-aliaser som används i portbindings (`IP:PORT`).
+
+Exempel: istället för att köra `ip addr add 10.0.4.2/16 dev eth0` via SSH, kan du skapa en post i GUI och aktivera den.
+
+## Funktioner (v1)
+
+- CRUD för IP-poster: `name`, `ip`, `cidr`, `device`.
+- Enable/disable per post:
+  - enable => `ip addr add <ip>/<cidr> dev <device>`
+  - disable => `ip addr del <ip>/<cidr> dev <device>`
+- Sorterbar tabell: namn, IP-adress, used/unused, containernamn, device, enable/disable.
+- Used/unused-kontroll via Docker API (`NetworkSettings.Ports`) med exakt `HostIp`-match.
+- Include stopped containers i used-kontroll.
+- Fail-closed:
+  - disable blockeras om IP används av minst en container,
+  - delete blockeras om posten är enabled eller used,
+  - disable/delete blockeras om Docker-usage inte kan verifieras.
+- Startup reconcile: enabled-poster återappliceras vid appstart.
+- Manuell refresh-knapp (ingen websocket i v1).
+
+## Portar
+
+- `${APP_PORT:-31810}`: webbgränssnitt/API.
+- `127.0.0.1:2375` (socket-proxy, valfritt): lokal Docker TCP proxy för alternativ endpoint.
+
+## Volymer
+
+- `/DATA/AppData/$AppID/data:/data`
+  - persistent lagring av IP-poster.
+- `/var/run/docker.sock:/var/run/docker.sock:ro`
+  - Docker metadata för used/unused-kontroll.
+
+## Privilegier
+
+- `network_mode: host`
+- `cap_add: [NET_ADMIN]`
+- `security_opt: ["no-new-privileges:true"]`
+
+## Säkerhetsavvikelser
+
+Denna app använder högrisk-inställningar och de är avsiktliga:
+
+- `network_mode: host`
+- mount av `/var/run/docker.sock`
+
+### Varför det behövs
+
+- `ip addr add/del` måste köras i hostens nätverksnamespace för att påverka hostens interface (ex. `eth0`).
+- Used/unused-status behöver läsas från Docker container metadata.
+
+### Alternativ som utvärderats
+
+- **Extern host-agent utanför Docker**: bättre isolering men kräver separat installation utanför appstore.
+- **nsenter-helper**: mer komplex driftsmodell och högre implementationsoverhead för v1.
+- **Endast Docker TCP endpoint utan socket**: stöds, men default är unix-socket för enklare baseline i ZimaOS.
+
+### Risker
+
+- Host network + `NET_ADMIN` kan påverka hostens nätverk direkt vid felaktig konfiguration.
+- Docker socket-access innebär insyn i container-metadata och behöver hanteras med strikt kontroll.
+
+### Riskreducering
+
+- Minsta capability för nätverksoperationer (`NET_ADMIN`), inte `privileged: true`.
+- `no-new-privileges:true`.
+- Fail-closed blockering vid osäker Docker-usage.
+- Valbar socket-proxy med read-only Docker socket och endpoint-begränsning.
+
+## Konfiguration
+
+Viktiga environment-variabler:
+
+- `APP_PORT` (default `31810`)
+- `DOCKER_API_URL` (default `unix:///var/run/docker.sock`)
+  - alternativt `http://127.0.0.1:2375` för socket-proxy.
+- `DOCKER_TIMEOUT_SECONDS` (default `3`)
+- `STATE_FILE` (default `/data/entries.json`)
+
+## Integrationstester
+
+Kör:
+
+```bash
+./Apps/docker-ip-addr-manager/tests/run_integration_tests.sh
+```
+
+Testerna mockar Docker API och `ip`-kommandoflöde och verifierar:
+
+- exakt `HostIp`-matchning,
+- fail-closed disable/delete,
+- blockering vid enabled/used,
+- startup reconcile av enabled-poster.
+
+## Auth-notis
+
+Ingen auth ingår i v1.
+
+Auth/autorisering ska implementeras i en senare version och är en uttalad roadmap-punkt.
+
+## Roadmap (ej v1)
+
+- WebSocket-baserad live-uppdatering av used-status.
+- DNS-integration (Cloudflare/lokal DNS) kopplat till IP-poster och hostnamn.