# 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:

```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,
- 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.