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.
• DNS-livscykel (opt-in): skapar A-record när enabled=true och used=true, tar bort record när villkoret inte längre gäller.
• DNS-namn byggs från name + DNS_BASE_DOMAIN => <name>.<base-domain> (DNS-säkrad label).
• 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,
  • state-ändringar blockeras om nödvändig DNS-synk misslyckas.
• Startup reconcile: enabled-poster återappliceras vid appstart.
• DNS reconcile körs i bakgrunden med poll-interval.
• Manuell refresh-knapp för UI-status (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)
• DNS_PROVIDER (none, adguard, rfc2136; default none)
• DNS_BASE_DOMAIN (exempel: home.arpa)
• DNS_TTL_SECONDS (default 120)
• DNS_SYNC_INTERVAL_SECONDS (default 15)

AdGuard (DNS_PROVIDER=adguard):

• ADGUARD_URL (exempel: http://127.0.0.1:3000)
• ADGUARD_USERNAME
• ADGUARD_PASSWORD
• ADGUARD_API_TOKEN (framtida alternativ, inte aktiv auth-väg i v1)

RFC2136 (DNS_PROVIDER=rfc2136):

• RFC2136_SERVER
• RFC2136_ZONE
• RFC2136_PORT (default 53)
• RFC2136_TSIG_KEY_NAME (valfri om osignerade updates tillåts)
• RFC2136_TSIG_SECRET (base64, valfri utan TSIG)
• RFC2136_TSIG_ALGORITHM (default hmac-sha256)

DNS-beteende

• Villkor för record: endast när posten är enabled och used.
• När posten inte längre är used tas DNS-record bort i bakgrundsreconcile.
• Vid enable/disable/delete görs direkt DNS-synk och operationen failar vid synkfel (fail-closed).
• Om Docker usage-kontroll är okänd i bakgrundsloop görs inga DNS-mutationer i den cykeln.

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,
• DNS create/delete på enabled && used,
• fail-closed rollback vid DNS-synkfel.

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.
• Alternativ auth för AdGuard via API-token.