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