Skip to content

OX Feed Command Source

The PowerDNS Platform Filter OX Feed Command Source (pdns-pf-oxfeed-commandsource) runs an external command on an interval, reads the feed CSV and codes file the command produces, and publishes the result as a versioned OX Feed on disk (or any other simpleblob backend). Each update is written as a snapshot or delta referenced by a single feed.json manifest, so downstream consumers see atomic transitions between versions.

The service is shipped as a systemd template unit (pdns-pf-oxfeed-commandsource@<instance>.service). One instance is configured per logical feed — for example one for admin-managed domain lists and another for admin category overrides — by copying the example config and symlinking the template unit.

What it does

  • Runs command_source.command under /bin/sh -c every command_source.interval.
  • Reads the CSV feed and feed-codes.json paths the command prints in a single-line OXFEED_GENERATOR_RESULT: { ... } JSON record on stdout, and removes those files after use.
  • Diffs the new content against the in-memory snapshot of the last feed version and writes a delta only when the content actually changed (hash-based, so identical reruns produce no churn).
  • Forces a fresh snapshot every feed.snap_interval to keep delta chains short for newly connecting clients.
  • Expires old snapshots and deltas according to the feed.expiry rules, while always preserving the deltas on the upgrade path from the latest snapshot to the latest delta.
  • Optionally serves the feed tree on /feed/ for development. The shipped status server only exposes /, /metrics, /healthz, and pprof.

Where it fits in Platform Filter

The command source sits at the producer end of the OX Feed pipeline. Operators feed it a script that knows how to dump a feed, the feed tree it writes is then served to downstream clients by a static HTTP server (Caddy or nginx), optionally through an OX Feed Mirror for bandwidth fan-out, and consumed by OX Feed Client instances on the filter nodes.

See Architecture for the command contract and the update lifecycle.

Next steps

  • Architecture: the command contract, what the service does on each tick, and how snapshots and deltas are written.
  • Configuration: full YAML reference for a per-instance config file.
  • Operations: the systemd template unit, CLI flags, HTTP server, and healthz checks.
  • Metrics: Prometheus metric reference.