jfriberg
1b35702b1b
Co-authored-by: Joachim Friberg <joachim.friberg@ip-solutions.se> Reviewed-on: phirna/zima-apps#6
139 lines
4.8 KiB
Markdown
139 lines
4.8 KiB
Markdown
# 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.
|