Skip to content

Organization Manager

The PowerDNS Platform Filter Organization Manager (pdns-pf-orgmanager) is the REST API in front of the per-organisation IP allocations that drive Platform Filter's IP-to-subscriber mapping. Operators and customer integrations create organisations, attach IP CIDR prefixes to them, and post overrides that pin attributes (username, location, deviceid, opaque meta) onto specific sub-CIDRs. The service stores the result in PostgreSQL, denormalises overlapping allocations into non-overlapping ranges, and publishes the resulting sessions to the IP Mapper over NATS so the rest of the platform can resolve a query's IP back to a user.

What it does

  • Owns the per-organisation allocation tree. Organisations have one or more prefixes; overrides live inside (or on top of) prefixes and can nest. The most specific override wins for any given IP.
  • Validates allocations. Cross-organisation prefix overlap is refused. Overrides that fall outside the organisation's prefixes are stored with status outside-prefixes and held in reserve until a covering prefix is added.
  • Denormalises the tree to flat ranges. Overlapping CIDRs are collapsed into non-overlapping ranges with most-specific-wins semantics. There is no attribute inheritance — each range carries the attributes of exactly one source override.
  • Publishes sessions to the IP Mapper. Each unique combination of CIDR plus attributes is one session; orgmanager publishes the diff against the previously deployed state, so quiet writes do not produce NATS traffic.
  • Heals out-of-band drift. A periodic version scan detects organisations whose org_version was changed elsewhere (typically by the Django admin portal that shares the same database) and redeploys them. An optional periodic full-redeploy resends every cached organisation as a safety net.
  • Surfaces health. A built-in status page, /health endpoint, and a Prometheus /metrics endpoint cover routine operational questions.

Where to look next

  • Architecture: role in Platform Filter, the vocabulary used by the rest of the docs, the PostgreSQL concurrency model, and the IP Mapper integration.
  • REST API: full reference for the endpoints the service serves.
  • Configuration: YAML reference for every config field, with PostgreSQL DSN examples for the common deployments.
  • Operations: systemd, CLI flags, status page, metrics, the stress companion, and grounded troubleshooting.