Configuration¶

The OX Feed Client reads its configuration from a YAML file. The default 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.

The -expand-env CLI flag causes the service to expand $VAR and ${VAR} references from its environment before parsing the YAML. This is the recommended way to inject credentials such as feeds[].password from a systemd drop-in rather than storing them in the file.

Top-level structure¶

Parameter	Type	Default	Description
`run_once`	`boolean`	`false`	Exit after a single successful update cycle. Useful for scripted or one-shot runs.
`lmdb`	`LMDB`	—	Path and tuning for the local LMDB database. Required.
`feeds`	`[]Feed`	—	One or more feeds to keep in sync. At least one is required.
`http`	`HTTP`	`{}`	Status page and Prometheus metrics server.
`log`	`Log`	—	Log output format and verbosity.
`default_poll_interval`	`go: Duration`	`5s`	How often to poll `feed.json` for a new version, used for feeds that do not override `poll_interval`.
`default_codes_poll_interval`	`go: Duration`	`1m`	How often to poll `feed-codes.json` for updated category names, used for feeds that do not override `codes_poll_interval`.

Deprecation policy¶

No fields have been deprecated or removed as of the current release.

Full example config¶

The file below is the example-client.yml shipped with the source tree and installed as /etc/pdns-pf/oxfeed-client.example.yml. It exercises every option with explanatory comments. The per-section reference below is authoritative; this block is for orientation.

Click to expand the shipped example config

# Example config file for the zvelo and oxfeed clients

lmdb:
  # Path to LMDB database dir (the one with data.mdb inside)
  dir_path: tmp/example-lmdb

  # Whether to scrape /proc/self/smaps to calculate LMDB memory statistics.
  # This defaults to true. Disable if you find this causes performance issues.
  #scrape_smaps: true

  # By default LMDB stats are logged every minute. You can disable this here,
  # or change the interval.
  #log_stats: true
  #log_stats_interval: 1m

  # These options allow overriding some LMDB parameters.
  # The defaults usually work fine, so only change this if you know what you
  # are doing.
  #options:
  #  dir_mask: 0775  # make sure to use octal
  #  file_mask: 0664
  #  map_size: 50GB
  #  max_dbs: 20

# The zvelo client only supports a single feed.
# The oxfeed client supports multiple feeds.
feeds:
- url: http://localhost:2015/zvelo-feed/ # Base url (without feed.json)
  namespace: zvelo                  # Local namespace, must not change
  # In the oxfeed case, at most one feed can have the load_first property.
  # If the database is empty, this feed will be run first.
  #load_first: true
  # Optional HTTP Basic Auth
  #username: ""
  #password: ""
  # Optional Proxy
  #proxy:
  #  url: http://user:password@localhost:9040
  # Optional TLS
  #tls:
    #ca_file: ca.pem
    #cert_file: cert.pem
    #key_file: key.pem
    #add_system_ca_pool: true
  # Optionally delay updates for this feed.
  # Can be used for canary instances of feeds in multi userplane installations.
  #delay_updates_by: 8h
  # You can override poll intervals per feed.
  #poll_interval: 5s
  #codes_poll_interval: 1m
  # Downgrade after 5 minutes if the upstream version disappears.
  #downgrade_after: 5m
  # Conservative protection against a stuck download (default 4h).
  #fetch_timeout: 4h

# Default poll intervals used when no per-feed intervals are configured.
#default_poll_interval: 5s
#default_codes_poll_interval: 1m

# The HTTP server exposes Prometheus /metrics and a status page
http:
  address: :8911

log:
  level: info       # options: trace, debug, info, warning, error, fatal
  format: human     # options: human, logfmt, json
  timestamp: short  # options: short, full, disable

`lmdb`¶

Controls where and how the LMDB database is stored on disk. The LMDB holds both the URL categorization data and a metadata database with feed state and update history.

LMDB file permissions¶

Note

dir_mask and file_mask must be written as YAML integers in octal notation, for example 0775 or 0664. Writing them as plain decimal integers (e.g. 509) causes the service to refuse to start with an error naming the field.

Parameter	Type	Default	Description
`dir_path`	`string`	—	Directory that contains `data.mdb`. Required. The directory must exist and be writable by the `pdns-oxfeed` user.
`scrape_smaps`	`boolean`	`true`	Read `/proc/self/smaps` to calculate LMDB resident-set statistics for Prometheus. Disable if this causes performance issues on your kernel.
`log_stats`	`boolean`	`true`	Log LMDB page statistics to the journal at `log_stats_interval`.
`log_stats_interval`	`go: Duration`	`1m`	How often to log LMDB stats when `log_stats` is enabled. Must be at least `100ms`.
`history_retention`	`uint`	`20000`	Maximum number of update history entries to retain in the metadata database. The actual count may slightly exceed this between compaction runs. Set to `0` to stop writing new history entries (existing history is not removed).
`options`	`Options`	—	Low-level LMDB parameters. The defaults work for most deployments; change only when you have a specific reason.

`lmdb.options`¶

Parameter	Type	Default	Description
`dir_mask`	`int` (octal)	`0775`	Permission bits for the LMDB directory, in octal.
`file_mask`	`int` (octal)	`0664`	Permission bits for the LMDB data files, in octal.
`map_size`	`ByteSize`	`20GB`	LMDB memory-map size. The map must be larger than the database on disk. A database with the full zVelo feed is roughly 2–4 GB; the default leaves significant headroom. Increase before the database approaches the limit.
`max_dbs`	`int`	`20`	Maximum number of named databases the LMDB environment can hold. The client opens two (data and metadata) regardless of how many feeds are configured — feed namespaces are key prefixes inside those databases, not separate databases. The default leaves ample headroom.

`feeds`¶

Each entry describes one feed to keep in sync. At least one entry is required. Each feed is identified by its namespace, which must be unique within a single client config.

Authentication¶

Both username and password support environment variable expansion (when -expand-env is set). Passwords are masked to (omitted) in log output.

feeds:
  - url: https://feed.example.com/zvelo/
    namespace: zvelo
    username: "${OXFEED_USERNAME}"
    password: "${OXFEED_PASSWORD}"

Fetch timeout¶

The fetch_timeout is a safety valve against a hung download. In normal operation it is never reached: Go's TCP stack uses keepalives to detect broken connections. The value must be high enough to accommodate a full snapshot download over a slow link. At the default of 4 hours and a snapshot size of 1.4 GB, it assumes a sustained download speed of at least 100 kB/s. When many clients fetch a large snapshot simultaneously, the per-client average speed drops; account for this when tuning the timeout.

Canary deployment¶

Note

Enable delay_updates_by on a clean LMDB when possible. If the database already contains snapshots or deltas newer than the delay cutoff, the client may trigger a downgrade immediately after the delay window opens. The upstream feed server must retain snapshots for at least as long as the configured delay.

`load_first`¶

When the LMDB is empty, at most one feed may set load_first: true. That feed is loaded before all others. This is useful when one feed provides the bulk of the data (e.g. the primary zVelo feed) and others are smaller overlays — starting with the primary reduces the window during which the filter engine has incomplete data.

Parameter	Type	Default	Description
`url`	`string`	—	Base URL of the feed server (no trailing path like `/feed.json`). Must use `http://` or `https://`. Required.
`namespace`	`string`	—	Unique label stored in the LMDB alongside the data. Must not change after the first write. Required.
`username`	`string`	—	HTTP Basic Auth username. Optional.
`password`	`string`	—	HTTP Basic Auth password. Masked in log output. Optional.
`load_first`	`boolean`	`false`	Load this feed before all others when the database is empty. At most one feed per config may set this.
`reset_snap`	`boolean`	`false`	Force a full snapshot reload on the next startup, discarding any locally stored delta state.
`tls`	`tlsconfig.Config`	—	TLS settings for the feed server connection. Optional.
`poll_interval`	`go: Duration`	`default_poll_interval`	How often to poll `feed.json` for a new version.
`codes_poll_interval`	`go: Duration`	`default_codes_poll_interval`	How often to poll `feed-codes.json` for updated category codes.
`fetch_timeout`	`go: Duration`	`4h`	Maximum time allowed for a single file download. See Fetch timeout above.
`downgrade_after`	`go: Duration`	`5m`	How long to wait before triggering a full snapshot reload when the upstream version disappears. Set to `999999h` to effectively disable. See Architecture → Downgrade.
`proxy`	`ProxyConfig`	—	HTTP proxy for this feed. Falls back to `HTTP_PROXY` / `HTTPS_PROXY` environment variables if not set.
`delay_updates_by`	`go: Duration`	—	Hold back updates by this duration. Intended for canary deployments. See Architecture → Canary deployments.

`feeds[].tls`¶

TLS configuration for the connection to the feed server. Provided by tlsconfig.Config.

Parameter	Type	Default	Description
`ca_file`	`string`	—	Path to a PEM file containing additional CA certificates to trust.
`cert_file`	`string`	—	Path to the client certificate PEM file. Required when the feed server requires mutual TLS.
`key_file`	`string`	—	Path to the client private key PEM file. Required with `cert_file`.
`add_system_ca_pool`	`boolean`	`false`	Include the system CA pool alongside any CAs from `ca_file`.
`insecure_skip_verify`	`boolean`	`false`	Disable server certificate verification. Do not use in production.

`feeds[].proxy`¶

Parameter	Type	Default	Description
`url`	`string`	—	Proxy URL, for example `http://user:password@proxy.example.com:3128`. Falls back to `HTTP_PROXY` / `HTTPS_PROXY` environment variables when not set.

`http`¶

The HTTP section enables the status page, Prometheus metrics endpoint, and pprof handlers. Omit address (or the entire http section) to disable the HTTP server.

Parameter	Type	Default	Description
`address`	`string`	—	Address to listen on, for example `:8911` or `127.0.0.1:8911`. Required to enable the HTTP server.

`log`¶

Controls log output format and verbosity.

Parameter	Type	Default	Description
`level`	`string`	`info`	Log level. One of: `trace`, `debug`, `info`, `warning`, `error`, `fatal`.
`format`	`string`	`human`	Log format. One of: `human` (coloured, for terminals), `logfmt`, `json`.
`timestamp`	`string`	`short`	Timestamp format. One of: `short`, `full`, `disable`.
`utc`	`boolean`	`true`	Log timestamps in UTC.

Configuration¶

Top-level structure¶

Deprecation policy¶

Full example config¶

lmdb¶

LMDB file permissions¶

lmdb.options¶

feeds¶