Skip to content

Device Register

The PowerDNS Platform Filter Device Register (pdns-pf-device-register) is the service that turns "Recursor just saw a device it does not know about" notifications into registered devices in the rest of the platform. For every DNS query from an unknown device, the filtering Recursor (or dnsdist in front of it) emits a short UDP "new device" message; this service collects those messages, deduplicates them, rate-limits abusive users, and writes each new device into Redis, Postgres, and (optionally) a Kafka topic or a dstore_alert fan-out.

What it does

  • Deduplicates bursts of register messages — many Recursors can simultaneously notice the same new device, and the service absorbs those duplicates.
  • Rate-limits and blocks per user. A user who tries to register too many devices in too short a window is blocked from registration for a cool-off period. DNS queries from their devices keep working, but the devices will not appear in the portal UI during the block.
  • Writes to Postgres so the portal UI sees the device.
  • Writes to Redis so the filtering Recursors converge on the new device via their local LMDB sync and stop re-sending the notification.
  • Optionally forwards to Kafka instead of Postgres, if an external system owns the database side.
  • Optionally forwards to dstore_alert as protobuf over TCP.

It also tracks a rough last-seen timestamp and records the DHCP name, if the Recursor had one.

Modes of operation

The service runs in one of three modes, selected by whether NATS is configured and which NATS role is enabled:

Combined mode (the original)

One process does everything: it opens the UDP listener, processes register messages, and writes to Redis / Postgres / Kafka / dstore directly. This is the simplest setup and is fine for single-site deployments where the Recursor and the device-register instance sit on the same trusted network.

Nothing in the nats: section of the config is set.

NATS split-producer mode

A lightweight front-end. It opens the UDP listener, performs local rate limiting and deduplication, and then forwards each new device to NATS. It does not touch Redis, Postgres, or Kafka at all. Use this on the User Plane side of a multi-site deployment where UDP register traffic arrives.

nats.split-mode-producer: true picks this mode.

NATS split-consumer mode

The back-end. It does not listen on UDP; it subscribes to NATS, runs a second, global round of rate limiting across the aggregated stream, and then writes the results into Redis / Postgres / Kafka / dstore_alert. Use this on the Control Plane side of a multi-site deployment.

nats.split-mode-consumer: true picks this mode. Setting both producer and consumer at once is refused at startup.

When to use the split mode

The split mode exists because the combined mode does not work well across data-centre boundaries:

  • The Lua platform settings need a stable IP to identify the Recursor, which is awkward in deployments where infrastructure hands out IPs dynamically on every restart.
  • Customers prefer to avoid unencrypted traffic between data-centre boundaries, and the combined mode has no authenticated transport to offer.
  • UDP is harder to proxy through a load balancer than TCP.

Running a split-producer on the User Plane next to the Recursor, and a split-consumer on the Control Plane next to Redis/Postgres, keeps the UDP on a local segment and turns the cross-boundary leg into authenticated NATS traffic. See Architecture → Split mode flow for the full picture.

Who this documentation is for

This site is for operators diving into a running deployment — the service has already been installed by Ansible (or equivalent tooling), and you need to understand how it behaves and what each YAML knob does. There is no installation walkthrough here.

Next steps

  • Architecture: how the service fits into Platform Filter, the three flows, the storage backends, and the blocklist semantics.
  • Configuration: full YAML reference, one section at a time.
  • Operations: systemd, CLI flags, metrics, the udp-linecat helper, and common troubleshooting.