Operations¶

Service control¶

The RPM ships a systemd unit named pdns-pf-oxfeed-mirror.service, running as the pdns-oxfeed user. Everyday commands:

# Status and recent logs
systemctl status pdns-pf-oxfeed-mirror

# Follow the log stream
journalctl -u pdns-pf-oxfeed-mirror -f

# Restart after a config change
systemctl reload-or-restart pdns-pf-oxfeed-mirror

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

Config location¶

The RPM ships a commented template at /etc/pdns-pf/oxfeed-mirror.example.yml but does not install a ready-to-use config file, and the packaged systemd unit starts pdns-pf-oxfeed-mirror without passing -config. The service will start without a config and then exit because no upstreams are defined.

To wire up a config:

Copy the example to a path of your choice, for example /etc/pdns-pf/oxfeed-mirror.yml, and edit it.

Point the service at it by overriding ExecStart, e.g. via systemctl edit pdns-pf-oxfeed-mirror:

[Service]
ExecStart=
ExecStart=/usr/bin/pdns-pf-oxfeed-mirror -config /etc/pdns-pf/oxfeed-mirror.yml

systemctl daemon-reload and restart the service.

See Configuration for the full reference.

Command-line flags¶

Flag	Default	Purpose
`-config`	—	Path to the YAML config file. Required in practice.
`-expand-env`	`false`	Expand `${VAR}` references inside the YAML file.
`-basedir`	(config)	Override `basedir`.
`-http-addr`	(config)	Override `http.address`.
`-debug`	`false`	Shortcut for `-log-level=debug`.
`-once`	`false`	Exit after a single successful run. Equivalent to `run_once: true`.
`-timeout`	`0`	Exit with status 10 after the given duration. Useful with `-once` to bound a one-shot run.
`-log-level`	(config)	Override `log.level`.
`-log-format`	(config)	Override `log.format`.
`-log-timestamp`	(config)	Override `log.timestamp`.

HTTP endpoints¶

The HTTP server bound to http.address serves three endpoints. None of them serve the mirrored feed tree — front that with Caddy or nginx pointed at basedir.

Status page (/). HTML summary of every upstream: current message, fetcher status code, last UUID, last version, time since the last successful update.
Metrics (/metrics). Prometheus endpoint. See Metrics.
Healthz (/healthz). JSON response from the embedded go-healthz library.

Healthz checks¶

The service registers two named checks per running mirror, suffixed with the active basedir:

Check	Warn threshold	Error threshold	Meaning
`free_disk@<basedir>`	< 5 GiB free	< 1 GiB free	Disk free at `basedir`, sampled every 5 s.
`stale_data@<basedir>`	24 h since last successful upstream cycle	—	Latest successful `feed.json` write older than the threshold.

The disk thresholds are fixed; size basedir so a healthy mirror stays well above 5 GiB. A zVelo snapshot is roughly 1.4 GB, so a single upstream with three retained snapshots needs ~4–5 GB plus deltas plus working headroom.

Serving the mirrored tree¶

Filter nodes do not connect to the mirror's own HTTP server. They connect to a static HTTP server (typically Caddy or nginx) that exposes basedir over HTTP. The oxfeed-client configuration on each filter node points at that URL with the same path layout as the upstream feed: https://<mirror-host>/<subdir>/.

The HTTP server fronting basedir must support ETags. Clients refuse to load from servers that do not. HTTP Basic Auth in front of the feed tree is supported by the client.

Run-once mode¶

-once (or run_once: true) is intended for cron-style use or for a one-shot fill before bringing up clients. The process exits with status 0 if every upstream completes a clean run, and non-zero otherwise. Combine with -timeout to put an upper bound on the run.