Operations

Service control

The RPM ships a systemd template unit named pdns-pf-oxfeed-rpz-downloader@.service, running as the pdns-oxfeed user. One instance is started per upstream zone.

To add an instance called spamhaus:

# 1. Drop a config file for this instance.
cp /etc/pdns-pf/oxfeed-rpz-downloader/example.yml \
   /etc/pdns-pf/oxfeed-rpz-downloader/spamhaus.yml
$EDITOR /etc/pdns-pf/oxfeed-rpz-downloader/spamhaus.yml

# 2. Enable an instance of the template unit.
ln -s /lib/systemd/system/pdns-pf-oxfeed-rpz-downloader@.service \
      /etc/systemd/system/pdns-pf-oxfeed-rpz-downloader@spamhaus.service

# 3. Bring it up.
systemctl daemon-reload
systemctl enable --now pdns-pf-oxfeed-rpz-downloader@spamhaus

Everyday commands for an existing instance:

# Status and recent logs
systemctl status pdns-pf-oxfeed-rpz-downloader@spamhaus

# Follow the log stream
journalctl -u pdns-pf-oxfeed-rpz-downloader@spamhaus -f

# Restart after a config change
systemctl restart pdns-pf-oxfeed-rpz-downloader@spamhaus

The service does not watch its config file for changes; restart the instance after editing.

Config location

Each instance reads /etc/pdns-pf/oxfeed-rpz-downloader/<instance>.yml. The RPM ships a commented template at /etc/pdns-pf/oxfeed-rpz-downloader/example.yml but does not install a ready-to-use per-instance config. See Configuration for the full reference.

Command-line flags

CLI flags override the matching YAML fields when set. A blank value leaves the YAML value alone.

Flag	Default	Purpose
--config	—	Path to the YAML config file. The packaged unit passes the per-instance file.
--expand-env	false	Expand $VAR / ${VAR} references inside the YAML file. Required to use shell-style env interpolation for credentials such as tsig_secret.
--oxfeed-path	—	Override feed.root with a filesystem path or simpleblob:// URI.
--address	—	Override feed.rpz_downloader.address.
--zone	—	Override feed.rpz_downloader.zone.
--interval	—	Override feed.rpz_downloader.interval.
--axfr-interval	—	Override feed.rpz_downloader.axfr_interval.
--http-address	—	Override http.address.
--tsig-secret	—	Override feed.rpz_downloader.tsig_secret.
--tsig-algo	—	Override feed.rpz_downloader.tsig_algo.
--tsig-fudge	—	Override feed.rpz_downloader.tsig_fudge.
--version	—	Print version and exit.

The shared --log-level, --log-format, and --log-timestamp flags behave the same as on the other OX Feed services.

Deprecated flags

The following flags accept the same values as their Python predecessor to ease drop-in replacement. New deployments should use the modern flags listed above.

Deprecated flag	Replacement
--rpz-zone NAME	--zone NAME
--rpz-master HOST	host portion of --address HOST:PORT
--rpz-master-port PORT	port portion of --address HOST:PORT
--httpd-address HOST	host portion of --http-address HOST:PORT
--httpd-port PORT	port portion of --http-address HOST:PORT
--rpz-lmdb-path PATH	accepted and ignored
--logtimestamp	accepted and ignored

HTTP endpoints

The HTTP server bound to http.address exposes:

• Status page (/). HTML summary: service version, uptime, memory usage, healthz status, feed UUID, total feed size, and the per-snapshot / per-delta tables.
• Metrics (/metrics). Prometheus endpoint. See Metrics.
• Healthz (/healthz). JSON response from the embedded go-healthz library. See Healthz checks below.
• pprof (/debug/pprof/...). Go net/http/pprof handlers for CPU, heap, goroutine, and block profiles.
• Feed tree (/feed). Only when http.serve_feed is set. Intended for development and testing only.

Healthz checks

The service registers five checks. The first three are shared with the OX Feed Command Source and start passive: they return OK until the first successful update lands, then switch to reflecting the real feed state.

Check	Type	Warn / errors when
feed_size	Warning	The published feed contains no data.
feed_version	Error	No feed version exists (snapshots and deltas both empty).
feed_source_version	Error	The last accepted source version is empty.
rpz_recent_xfr_success	Warning	More than warn_no_xfr_interval has elapsed since the last successful XFR. A startup grace period prevents this from firing during warm-up.
rpz_network_error	Warning	The most recent fetch attempt finished with a network error. Clears on the next successful XFR.

The "passive until first update" behaviour on the feed checks means a freshly started instance does not page during warm-up. The rpz_* checks fill the gap by paging on connectivity problems even before the first XFR has succeeded.

TSIG operating notes

• Store the base64 secret in a systemd environment file and reference it as ${RPZ_TSIG_SECRET} from tsig_secret, with --expand-env on the command line. The YAML file is world-readable on most deployments; the env file is not.
• tsig_fudge is rounded to whole seconds. The maximum accepted value is 65535s.
• The service refuses to start when tsig_secret is set together with hmac-md5 or any other unsupported algorithm.
• tsig_secret is masked to (omitted) whenever the resolved config is logged (for example at startup).

Profiling

Live profiling is available via the pprof endpoints under /debug/pprof/ on the status server. For example:

go tool pprof http://127.0.0.1:9605/debug/pprof/heap