karldns.de/README.md

# router-dyndns

A small self-hosted DynDNS service for FRITZ!Box and compatible routers.

It gives users FRITZ!Box-ready DynDNS settings without requiring a full account for provider-owned hostnames. For custom domains, users verify domain ownership with a DNS TXT challenge before creating hostnames.

## Features

- FastAPI app with `/docs`, `/redoc`, and `/openapi.json`.
- Anonymous magic URLs for provider-owned hostnames.
- Optional user sessions for custom-domain verification and hostname quotas.
- FRITZ!Box-compatible update URLs.
- SQLite persistence with WAL mode.
- SQLite-backed rate limiting for public creation and update endpoints.
- Cloudflare DNS publishing.
- RFC 2136 DNS publishing.
- DNS publish-before-store update behavior.
- Per-host update locking inside one server process.
- Custom-domain TXT verification.
- Trusted proxy configuration for `X-Forwarded-For`.
- Docker and Caddy examples.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Run quality checks:

```bash
ruff check router_dyndns tests
pytest
```

## Run Locally

```bash
export DDNS_ADMIN_PASSWORD='long-random-admin-password'
export DDNS_SESSION_SECRET='another-long-random-secret'
export DDNS_PUBLIC_BASE_URL='https://ddns.example.net'
export DDNS_HOSTNAME_SUFFIX='ddns.example.net'
export DDNS_DATABASE='./ddns.sqlite3'
export DDNS_DNS_PROVIDER='cloudflare'
export DDNS_DNS_ZONES='ddns.example.net'
export DDNS_REQUIRE_DNS_PROVIDER=1
export DDNS_CLOUDFLARE_API_TOKEN='cloudflare-api-token'
export DDNS_CLOUDFLARE_ZONE_ID='cloudflare-zone-id'
export DDNS_TRUSTED_PROXY_IPS='127.0.0.1,::1'

router-dyndns serve --host 0.0.0.0 --port 8080
```

Open:

- Customer UI: `https://ddns.example.net/`
- Admin UI: `https://ddns.example.net/admin`
- Swagger UI: `https://ddns.example.net/docs`
- ReDoc: `https://ddns.example.net/redoc`

Admin auth uses HTTP Basic auth. Use any username and `DDNS_ADMIN_PASSWORD` as the password.

## FRITZ!Box Setup

Users receive these fields:

- `Update-URL`
- `Domainnamen`
- `Benutzername`
- `Kennwort`

The generated update URL uses FRITZ!Box placeholders:

```text
/u/<random-update-slug>?myip=<ipaddr>&myipv6=<ip6addr>
```

The compatibility endpoint is also available:

```text
/nic/update?hostname=<domain>&myip=<ipaddr>&myipv6=<ip6addr>&username=<username>&password=<pass>
```

The `/u/<slug>` endpoint is safer for public service use because the user cannot alter the hostname in the router request.

## HTTP API

The API is versioned under `/api/v1`.

Core endpoints:

- `POST /api/v1/hostnames/magic`: create a provider-owned random hostname.
- `GET /api/v1/management/{management_slug}`: inspect a hostname by private management link.
- `DELETE /api/v1/management/{management_slug}`: delete a hostname and DNS records.
- `POST /api/v1/domains/challenges`: create a TXT challenge. Requires login.
- `POST /api/v1/domains/verify`: verify a TXT challenge. Requires login.
- `POST /api/v1/hostnames/custom`: create a custom hostname below a verified and publishable domain. Requires login.
- `GET /api/v1/updates/{update_slug}`: JSON update endpoint.

Example:

```bash
curl -sS https://ddns.example.net/api/v1/hostnames/magic \
  -H 'content-type: application/json' \
  -d '{"username":"home-router"}'
```

## DNS Publishing

For public service use, configure a real DNS backend and set:

```bash
export DDNS_REQUIRE_DNS_PROVIDER=1
```

Cloudflare:

```bash
export DDNS_DNS_PROVIDER=cloudflare
export DDNS_DNS_ZONES=ddns.example.net
export DDNS_CLOUDFLARE_API_TOKEN='cloudflare-api-token'
export DDNS_CLOUDFLARE_ZONE_ID='cloudflare-zone-id'
export DDNS_TTL=60
```

RFC 2136:

```bash
export DDNS_DNS_PROVIDER=rfc2136
export DDNS_DNS_ZONES=ddns.example.net
export DDNS_RFC2136_SERVER=127.0.0.1
export DDNS_RFC2136_ZONE=ddns.example.net
export DDNS_RFC2136_KEY_NAME=ddns-key
export DDNS_RFC2136_KEY_SECRET='base64-tsig-secret'
export DDNS_TTL=60
```

`DDNS_DNS_ZONES` defines which DNS zones this service may publish. A user proving TXT control of a domain is not enough; the hostname must also be inside a zone your DNS backend can update.

## Docker

```bash
docker compose up -d --build
```

Copy `.env.example` to `.env` and set real secrets first.

## Operations

- Run behind HTTPS.
- Use long random values for `DDNS_ADMIN_PASSWORD` and `DDNS_SESSION_SECRET`.
- Configure `DDNS_TRUSTED_PROXY_IPS` only for reverse proxies that strip user-supplied forwarding headers.
- Back up the SQLite database.
- Run one Uvicorn worker with SQLite. The per-host update lock is process-local.

SQLite backup example:

```bash
sqlite3 /data/ddns.sqlite3 ".backup '/backups/router-dyndns.sqlite3'"
```