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

HOW_TO_VERIFY

Detta dokument verifierar att docker-ip-addr-manager fungerar säkert i ZimaOS.

1) Förutsättningar

• ZimaOS-host med minst ett interface (ex eth0).
• Docker körs på hosten.
• Appen är installerad och startad.
• Webb-UI/API nås på ${APP_PORT:-31810}.

Kontrollera att appen är uppe:

curl -fsS http://127.0.0.1:31810/healthz

Förväntat resultat:

• JSON med {"ok":true}.

2) Positiva testfall

Test A: Skapa och enable IP-post

Skapa post:

curl -fsS -X POST http://127.0.0.1:31810/api/entries \
  -H 'Content-Type: application/json' \
  -d '{"name":"lan-test","ip":"10.0.4.2","cidr":16,"device":"eth0"}'

Hämta id från svaret och enable:

ENTRY_ID="<id-fran-svaret>"
curl -fsS -X POST "http://127.0.0.1:31810/api/entries/${ENTRY_ID}/enable"

Verifiera på host:

ip -4 -o addr show dev eth0 | rg '10\.0\.4\.2/16'

Förväntat resultat:

• IP-adressen finns på eth0.

Test B: Used-detektion via Docker port binding

Starta testcontainer bunden till IP:n:

docker run -d --rm --name ip-verify-nginx -p 10.0.4.2:18080:80 nginx:1.27.5

Refresh appdata:

curl -fsS -X POST http://127.0.0.1:31810/api/refresh

Förväntat resultat:

• posten med 10.0.4.2 har used=true.
• containers innehåller ip-verify-nginx.

Test C: DNS create när posten är enabled + used

Förutsätter DNS config i appen, exempel för AdGuard:

• DNS_PROVIDER=adguard
• DNS_BASE_DOMAIN=home.arpa
• ADGUARD_URL=http://<adguard-ip>:3000
• ADGUARD_USERNAME=<user>
• ADGUARD_PASSWORD=<password>

Verifiera att record skapats:

dig +short lan-test.home.arpa @<adguard-ip>

Förväntat resultat:

• returnerar 10.0.4.2.

Test D: Disable/Delete efter frigöring

Stoppa testcontainer:

docker stop ip-verify-nginx

Disable posten:

curl -fsS -X POST "http://127.0.0.1:31810/api/entries/${ENTRY_ID}/disable"

Verifiera borttagen IP:

ip -4 -o addr show dev eth0 | rg '10\.0\.4\.2/16' || true

Förväntat resultat:

• ingen träff för 10.0.4.2/16.

Ta bort posten:

curl -fsS -X DELETE "http://127.0.0.1:31810/api/entries/${ENTRY_ID}"

Förväntat resultat:

• svar med {"deleted":true}.

3) Negativt / fail-closed testfall

Test E: Blockera disable när IP används

1. Skapa + enable som i Test A.
2. Starta container som i Test B.
3. Försök disable:

curl -sS -o /tmp/disable.out -w '%{http_code}\n' \
  -X POST "http://127.0.0.1:31810/api/entries/${ENTRY_ID}/disable"
cat /tmp/disable.out

Förväntat resultat:

• HTTP 409.
• feltext som anger att posten används av container.

Test F: Fail-closed vid DNS-fel

1. Se till att en post är enabled och used (Test A+B).
2. Sabotera DNS-auth tillfälligt, exempel:
   • ändra ADGUARD_PASSWORD till fel värde och starta om appen.
3. Försök disable/delete på posten.

curl -sS -o /tmp/dns-fail.out -w '%{http_code}\n' \
  -X POST "http://127.0.0.1:31810/api/entries/${ENTRY_ID}/disable"
cat /tmp/dns-fail.out

Förväntat resultat:

• HTTP 409 eller 503.
• feltext som indikerar DNS-synkfel.
• posten ska inte lämna systemet i delvis uppdaterat läge.

4) DNS / nät / TLS verifiering

DNS (om hostname används i LAN)

DNS_SERVER="<dns-server-ip>"
HOSTNAME_TO_TEST="lan-test.home.arpa"
dig +short "${HOSTNAME_TO_TEST}" @"${DNS_SERVER}"

Förväntat resultat:

• returnerar avsedd LAN-IP när posten är enabled && used.
• ingen träff när posten inte längre är used eller är disabled.

Nätverk (lyssning och routning)

ss -ltnp | rg ':31810'
ip route get 10.0.4.2

Förväntat resultat:

• appen lyssnar på 31810.
• route lookup fungerar mot rätt interface.

TLS

Appens UI/API i v1 kör HTTP, inte HTTPS.

Verifiera att HTTP fungerar:

curl -fsS http://127.0.0.1:31810/healthz

Verifiera att HTTPS mot app-porten inte ska användas:

curl -k https://127.0.0.1:31810/healthz || true

Förväntat resultat:

• HTTP fungerar.
• HTTPS-anrop misslyckas eller ger ogiltigt TLS-handslag.

5) Data att samla (för snabb felsökning)

• Versions-/buildinfo:
  • app-id: docker-ip-addr-manager
  • branch/commit eller zip + checksum.
• Relevant konfiguration (maska secrets):

docker inspect docker-ip-addr-manager | jq '.[0].Config.Env'

• Loggar från berörda containers:

docker logs --tail 200 docker-ip-addr-manager

docker logs --tail 200 docker-ip-addr-manager-proxy

• Konkreta felobservationer:
  • hostname/IP,
  • exakt tidpunkt,
  • förväntat beteende,
  • faktiskt beteende,
  • exakta kommandon som kördes.