Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/spatiumddi/spatiumddi

Open-source DDI platform — unified DNS, DHCP, and IP Address Management. Runs its own BIND9 + Kea service containers, with a FastAPI control plane and React UI. Alpha.
https://github.com/spatiumddi/spatiumddi

bind9 ddi dhcp dns dns-management docker fastapi infrastructure ip-address-management ipam kubernetes netops network-automation open-source react self-hosted

Last synced: 2 months ago
JSON representation

Open-source DDI platform — unified DNS, DHCP, and IP Address Management. Runs its own BIND9 + Kea service containers, with a FastAPI control plane and React UI. Alpha.

Awesome Lists containing this project

README 

          


  SpatiumDDI Logo




SpatiumDDI





  Self-hosted DNS, DHCP, and IPAM — one control plane, real servers underneath.


  A modern, open-source alternative to commercial DDI platforms.






  License

  Issues

  Docs

  Status

  Python

  React




---



> ⚠️ **Alpha software.** SpatiumDDI is under active development and has not yet been battle-tested in production. Expect rough edges, breaking schema changes between releases (Phase 1), and features listed in the roadmap that are still in flight. Run it in a lab, file bugs, and please don't put it in front of DHCP clients you care about until Phase 2 is complete. Early adopter feedback is very welcome — open an issue or start a discussion on GitHub.



---



## Why SpatiumDDI



**It runs DNS and DHCP — not just configures them.** A modern alternative to Infoblox and EfficientIP: most open-source IPAM tools are pretty dashboards over someone else's `/etc/bind/named.conf`. SpatiumDDI bundles BIND9 and Kea as first-class service containers; the control plane owns their config, they auto-register, and they keep serving if the control plane is down.



**One platform, three surfaces.** IPAM tree, DNS zones, DHCP scopes — one UI, one REST API, one source of truth. Hostname changes in IPAM propagate to DNS; reservations propagate to DHCP. No more three-tab reconciliation.



**Bring your own servers — or ours.** Use the bundled Kea and BIND9, or point SpatiumDDI at your existing Windows DCs and DHCP servers via WinRM. Agentless in both directions — nothing installed on the Windows side.



**Built for delegation.** Group-based RBAC with LDAP, OIDC, SAML, RADIUS, and TACACS+ (with backup-server failover). Hand a subnet or a zone to a department without handing over root.



**API-first.** Every UI action is a REST call. Terraform, Ansible, and ad-hoc scripts all speak the same surface. If you can click it, you can automate it.



## What's in the box



- 🗂 **Hierarchical IP management** — spaces, blocks, subnets, addresses in a visual tree; IPv4 + full IPv6 auto-allocation (EUI-64 + random /128 + sequential)

- 🌐 **Built-in DNS server** — BIND9 container that auto-registers, syncs via RFC 2136, and reports per-server zone serial drift

- 🔄 **DHCP server management** — Kea container + agent with lease tracking; group-centric HA (hot-standby + load-balancing) with live state reporting, self-healing peer-IP drift, and supervised daemons for crash-loop-safe restarts

- 🪟 **Windows Server DNS + DHCP** — agentless management of existing Windows DCs (RFC 2136 + WinRM for DNS; near-real-time WinRM lease-mirroring for DHCP). No software installed on the Windows side.

- 🧩 **Read-only integrations** — auto-mirror **Kubernetes** clusters (CIDRs, nodes, LoadBalancer VIPs, Ingress → DNS), **Docker** hosts (networks, optional container IPs), and **Proxmox VE** endpoints (bridges, SDN VNets + subnets, VMs, LXC guests — runtime IPs via QEMU guest-agent, one row per cluster) into IPAM with one-click setup guides. Opt-in VNet-CIDR inference from guest NICs for SDN deployments where PVE is L2-only. Per-endpoint "Discovery" modal shows which VMs aren't reporting IPs + why, with copy-ready fix hints. Settings toggle gates each; per-target sync interval + on-demand Sync Now. Supernet auto-creation for RFC 1918 / CGNAT ranges keeps the tree tidy.

- 🎨 **Dashboard-at-a-glance** — platform health card (API / Postgres / Redis / workers / beat), live DNS query rate + DHCP traffic charts (BIND9 statistics-channels + Kea `statistic-get-all`, self-contained — no Prometheus needed), subnet utilization heatmap, and live activity feed

- 🔒 **Group-based RBAC + external identity** — LDAP, OIDC, SAML, RADIUS, TACACS+ with backup-server failover; delegate IP ranges and zones by role; API tokens with auto-expiry

- 🔔 **Alerts + audit forwarding** — rule-based alerts framework (subnet utilization, server unreachable) + multi-target syslog (UDP / TCP / TLS) + HTTP webhook forwarding with pluggable wire formats (RFC 5424 JSON / CEF / LEEF / RFC 3164 / JSON lines) and per-target filters

- 🔐 **ACME DNS-01 provider** — `acme-dns`-compatible HTTP surface so certbot / lego / acme.sh can issue public certs (wildcards included) for names delegated to a SpatiumDDI-managed zone

- 🏷 **IEEE OUI vendor lookup** — opt-in display of MAC vendor names in IP tables and DHCP leases, with filter-by-vendor support

- 📋 **Full audit trail** — every mutation logged, append-only, viewable in the UI with per-column filters

- 🚀 **Flexible deployment** — Docker Compose, Kubernetes (Helm umbrella chart + OCI publishing), bare metal, or OS appliance



---



## Screenshots



_Click any image to open the full-size version._



| [Dashboard](docs/assets/screenshots/dashboard.png) | [IPAM](docs/assets/screenshots/ipam.png) |

| :---: | :---: |

| [Dashboard](docs/assets/screenshots/dashboard.png) | [IPAM](docs/assets/screenshots/ipam.png) |

| Utilisation, VLAN, DNS & DHCP status at a glance | Hierarchical space / block / subnet tree with per-IP DNS sync |



| [DNS](docs/assets/screenshots/dns.png) | [DHCP](docs/assets/screenshots/dhcp.png) | [VLANs](docs/assets/screenshots/vlans.png) |

| :---: | :---: | :---: |

| [DNS](docs/assets/screenshots/dns.png) | [DHCP](docs/assets/screenshots/dhcp.png) | [VLANs](docs/assets/screenshots/vlans.png) |

| Zones, records, server groups | Scopes, pools, static reservations | Routers & VLANs linked to subnets |



---



## Architecture





  SpatiumDDI architecture




**Control plane** — FastAPI + PostgreSQL + Redis + Celery. Single source of truth for everything (IPAM tree, DNS records, auth, audit log). Exposes a REST API; the web UI and any Terraform / Ansible / CLI integration all speak the same API.



**Data plane — two shapes:**



- **Agented** (BIND9, Kea) — one container per service. Each bakes in a sidecar agent (`spatium-dns-agent` / `spatium-dhcp-agent`) that (1) bootstraps with a PSK → rotating JWT, (2) long-polls `/config` with an ETag, (3) caches the last-known-good bundle on disk so the service keeps serving if the control plane is unreachable, (4) drains record / config ops over loopback (nsupdate + TSIG for BIND9; Kea Control Agent API for Kea). Structural changes reload named / kea-dhcp4; record changes do not.



- **Agentless** (Windows DNS, Windows DHCP) — no software on the Windows side. The control plane speaks directly: RFC 2136 over UDP/TCP 53 (DNS record writes + AXFR), WinRM + PowerShell over 5985/5986 (DNS zone CRUD, DHCP lease / scope reads). Credentials are Fernet-encrypted on the server row.



The driver abstraction is backend-neutral — services speak to `DNSDriver` / `DHCPDriver`, never to BIND9 / Kea / PowerShell specifics.



**Tech stack**: Python 3.12 · FastAPI · SQLAlchemy 2.x (async) · PostgreSQL 16 · Redis 7 · Celery · React 18 · TypeScript · Tailwind · shadcn/ui · pywinrm · dnspython · Docker · Kubernetes + Helm



---



## Getting Started



> ⚠️ SpatiumDDI is **alpha** (first release: `2026.04.16-1`). Commands and APIs may still shift between releases.



> 📘 For the full setup order (servers → zones/scopes → subnets → addresses) see **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)**. For Windows DC integration see **[docs/deployment/WINDOWS.md](docs/deployment/WINDOWS.md)**.



### Quick start with Docker Compose



```bash

git clone https://github.com/spatiumddi/spatiumddi.git

cd spatiumddi

cp .env.example .env

# Required env vars in .env:

#   POSTGRES_PASSWORD=

#   SECRET_KEY=$(openssl rand -hex 32)

#   DNS_AGENT_KEY=$(openssl rand -hex 32)   # needed if running the DNS container

docker compose build

docker compose run --rm migrate

docker compose up -d

```



Open `http://localhost:8077` and log in with `admin` / `admin` (you're forced to change the password on first login).



### Running the built-in BIND9 / Kea containers



The managed-service containers ship under Compose profiles — opt in when you want them:



```bash

docker compose --profile dns up -d                 # DNS only

docker compose --profile dns --profile dhcp up -d  # DNS + DHCP

```



Or set `COMPOSE_PROFILES=dns,dhcp` in your `.env` so plain `docker compose up -d` enables both automatically.



That starts `dns-bind9` bound to host port `5353` (udp + tcp). The agent registers with the control plane automatically using `DNS_AGENT_KEY` from your `.env` and appears in the UI under **DNS → Server Groups → default**.



Create a zone + record in the UI, then verify with `dig`:



```bash

dig @127.0.0.1 -p 5353 . A +short

dig @127.0.0.1 -p 5353 -x  +short    # reverse (PTR)

```



Record changes propagate to BIND9 via RFC 2136 — typically sub-second, no daemon restart. Zone / ACL / view changes trigger a config reload.



**Production**: point the agent at your real control plane, expose `53/udp` + `53/tcp`, and run one container per DNS server you want in the cluster. All servers in a group share the same TSIG key for dynamic updates.



### API & interactive docs



The FastAPI backend auto-generates OpenAPI / Swagger:



| Path | What |

|---|---|

| `http://localhost:8077/api/docs` | Swagger UI — try endpoints directly from the browser |

| `http://localhost:8077/api/redoc` | ReDoc — cleaner reference layout |

| `http://localhost:8077/api/openapi.json` | Raw OpenAPI 3 spec (for code generators) |



Every UI action is a REST call, so anything you do in the UI you can do via `curl`, Terraform, or your own client. Log in to the UI first to obtain a bearer token, then use `Authorization: Bearer `.



### Reset the admin password



```bash

docker compose exec api python - <<'EOF'

import asyncio

from sqlalchemy import update

from app.core.security import hash_password

from app.db import AsyncSessionLocal

from app.models.auth import User



async def reset():

    async with AsyncSessionLocal() as db:

        await db.execute(update(User).where(User.username == "admin")

            .values(hashed_password=hash_password("NewPass!"), force_password_change=True))

        await db.commit()



asyncio.run(reset())

EOF

```



### Requirements



- Docker 24+ and Docker Compose v2, **or**

- Kubernetes 1.27+ with Helm 3, **or**

- Ubuntu 22.04 / Debian 12 / Alpine 3.20+ for bare metal



---



## Deployment Options



| Method | Use case | Status |

|---|---|---|

| **Docker Compose** | Dev, small single-host production | ✅ Supported |

| **Kubernetes + Helm** | Multi-node production, scalable | ✅ Umbrella chart (`charts/spatiumddi`, published OCI to `ghcr.io/spatiumddi/charts/spatiumddi`) |

| **Bare metal / VM (Ansible)** | On-prem without containers | 📋 Planned |

| **OS Appliance (ISO / qcow2)** | Air-gapped, zero-dependency | 📋 Planned |



---



## Documentation



Full docs at **[spatiumddi.github.io](https://spatiumddi.github.io)** (coming soon).



| Document | Description |

|---|---|

| [Getting Started](docs/GETTING_STARTED.md) | Recommended setup order — from server groups down to allocating an IP |

| [IPAM Features](docs/features/IPAM.md) | IP space, block, subnet, address management |

| [DHCP Features](docs/features/DHCP.md) | DHCP server management — Kea, Windows DHCP |

| [DNS Features](docs/features/DNS.md) | DNS zones, views, server groups, blocking lists, Windows DNS |

| [Auth & Permissions](docs/features/AUTH.md) | LDAP, OIDC, SAML, RADIUS, TACACS+, roles, scoped permissions |

| [System Admin](docs/features/SYSTEM_ADMIN.md) | Health dashboard, backup, notifications |

| [Observability](docs/OBSERVABILITY.md) | Logging, metrics, alerting |

| [Windows Server Setup](docs/deployment/WINDOWS.md) | WinRM, service accounts, firewall — Windows-side checklist |

| [DNS Agent Design](docs/deployment/DNS_AGENT.md) | Agent protocol, auto-registration, config sync |

| [DNS Driver Spec](docs/drivers/DNS_DRIVERS.md) | BIND9 + Windows DNS driver internals |

| [DHCP Driver Spec](docs/drivers/DHCP_DRIVERS.md) | Kea + Windows DHCP driver internals |

| [Appliance Deployment](docs/deployment/APPLIANCE.md) | OS image build and licensing |



---



## Project Status



| Phase | Focus | Status |

|---|---|---|

| Phase 1 | Core IPAM, auth, user management, audit log, Docker Compose | ✅ Done — LDAP/OIDC/SAML + RADIUS/TACACS+, group-based RBAC, bulk-edit, inheritance, mobile-responsive UI, and full IPv6 `/next-address` (EUI-64 + random /128 + sequential) all shipped |

| Phase 2 | DHCP (Kea), DNS (BIND9), DDNS, zone/subnet tree UI | ✅ Done — DNS, Kea DHCPv4, subnet-level DDNS, agent-side Kea DDNS, block/space DDNS inheritance, per-server zone serial reporting all shipped |

| Phase 3 | DNS views, server groups, blocking lists, VLAN/VXLAN, system admin, Kea HA | 🔄 DNS features + health dashboard + alerts framework + group-centric Kea HA (self-healing peer-IP drift + supervised daemons) landed; DNS Views end-to-end + HA state-transition actions still pending |

| Phase 4 | OS appliance, Terraform provider, SAML, backup/restore, ACME | 🔄 SAML landed; appliance + providers + backup + ACME (DNS-01 provider + embedded client) pending |

| Phase 5 | Multi-tenancy, IP request workflows, advanced reporting | 📋 Planned |



See [CHANGELOG.md](CHANGELOG.md) for the per-release feature list and

[CLAUDE.md](CLAUDE.md) for the authoritative spec.



---



## Contributing



Contributions are welcome.



- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR

- Good first tasks are tagged on the [issue tracker](https://github.com/spatiumddi/spatiumddi/issues)

- Design discussion happens in [GitHub Discussions](https://github.com/spatiumddi/spatiumddi/discussions)



---



## License



Released under the [Apache 2.0 License](LICENSE).



Bundled components (BIND9, ISC Kea) are distributed under their own licenses. See [NOTICE](NOTICE) for the full list.



---





  Built with ❤️ by the SpatiumDDI community · spatiumddi.github.io