zima-apps/Apps/docker-ip-addr-manager/README.md

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:

./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.