Operations¶

Service control¶

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

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

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

# Restart after a config change
systemctl restart pdns-pf-oxfeed-client

The service does not watch its config file for changes; restart it after editing oxfeed-client.yml.

Config location¶

The default config path is /etc/pdns-pf/oxfeed-client.yml. A commented template with every option is shipped alongside it as /etc/pdns-pf/oxfeed-client.example.yml. See Configuration for the full reference.

Command-line flags¶

Flag	Default	Purpose
`-config`	—	Path to the YAML config file.
`-expand-env`	off	Expand `$VAR` / `${VAR}` references from the environment inside the YAML before parsing. Use this to inject secrets such as feed passwords.
`-o`	—	Override `lmdb.dir_path` from the command line.
`-http-addr`	—	Override `http.address` from the command line (example: `:9210`).
`-debug`	off	Enable debug-level logging.
`-once`	off	Run a single update cycle and exit. Equivalent to `run_once: true` in the config.
`-timeout`	`0` (no timeout)	Exit after the given duration (example: `10s`). Useful together with `-once`.

Observability¶

All live-inspection surfaces are served by the HTTP server bound to http.address (see Configuration → http).

Status page. An HTML summary is served at /, showing the current version and update state of each configured feed.
Health check. /healthz returns a JSON health summary, including service version and hostname.
Prometheus metrics. Scraped at /metrics. See Metrics below.
pprof. Go net/http/pprof handlers under /debug/pprof/ for CPU, heap, goroutine, and block profiles.

Log verbosity is controlled by log.level in the config or the -debug flag. At debug level the client logs each feed poll cycle, download progress, and LMDB write operations.

Metrics¶

All metrics are exposed at /metrics in Prometheus exposition format.

Metric	Type	Labels	Description
`up`	Gauge	—	`1` while the service is running.
`oxfeed_client_feed_current_info`	Gauge	`feed`, `uuid`, `url`	Always `1`. Carries feed identity as labels for join queries.
`oxfeed_client_feed_current_version`	Gauge	`feed`	The version number currently stored in the LMDB for this feed.
`oxfeed_client_update_error_total`	Counter	`feed`	Total update errors for this feed since startup.
`oxfeed_client_update_error_message_total`	Counter	`feed`, `error`	Update errors broken down by error message. Useful for identifying recurring failure modes.
`oxfeed_client_update_time_seconds`	Summary	`feed`	Time spent on each update attempt, including download time and failed attempts.
`oxfeed_client_update_http_status_total`	Counter	`feed`, `code`	HTTP response status codes seen while fetching feed assets. A steady stream of `304` (Not Modified) responses indicates the client is polling and the feed is unchanged.

LMDB page and reader statistics are also exported via the standard LMDB Prometheus collector.

Warning

The oxfeed_client_update_error_message_total label error carries the raw error string. If errors are transient and varied (e.g. different network errors), the label cardinality can grow. Monitor the total number of distinct label value combinations in your Prometheus instance.

Companion tool: `pdns-pf-oxfeed-client-query`¶

pdns-pf-oxfeed-client-query reads the LMDB written by the client and lets you inspect feed state, look up entries, and browse update history. It requires either --config pointing to the client config or --lmdb-path pointing directly to the LMDB directory.

The user running the tool needs write access to lock.mdb in the LMDB directory to acquire a read lock. If this is not possible (e.g. in read-only diagnostic scenarios), use --lockless.

Global flags¶

Flag	Default	Purpose
`--config`	auto-discover	Path to the client YAML config. The tool also tries common paths automatically.
`--expand-env`	off	Expand environment variables in the config file.
`--lmdb-path`	—	Direct path to the LMDB directory (alternative to `--config`).
`--debug`	off	Enable debug logging.
`--lockless`	off	Open the LMDB without acquiring a read lock. Use only when the normal lock cannot be obtained.
`--lockless-timeout`	`8s`	Timeout for lockless reads. Kept below 10 seconds to avoid interfering with the client's read-lock rollover.

Subcommands¶

Subcommand	Description
`feeds`	List all feeds stored in the LMDB with their version numbers, UUIDs, and last-updated timestamps.
`codemaps`	Show the code maps (numeric code → category name) for all feeds.
`code <feed/code>`	Look up a single numeric code. Use a value from `codemaps` output.
`url <domain[/path]>`	Look up database entries for a domain or URL. Use `--sub` to include subdomains, `--paths` to include all URL paths.
`stats`	Print raw LMDB environment and database statistics.
`history`	List the update history stored in the metadata database.
`meta`	Show raw feed metadata.
`version`	Print the tool version.

Example session¶

# Show what feeds are loaded and at which version
pdns-pf-oxfeed-client-query --config /etc/pdns-pf/oxfeed-client.yml feeds

# Look up a domain and all its subdomains
pdns-pf-oxfeed-client-query --config /etc/pdns-pf/oxfeed-client.yml \
    url --sub twitter.com

# Show update history entries from the last 24 hours for the zvelo feed
pdns-pf-oxfeed-client-query --config /etc/pdns-pf/oxfeed-client.yml \
    history --namespace zvelo --past 24h