Configuration¶

The Settings Syncer reads its configuration from a single YAML file. The default path is /etc/pdns-pf/settingssyncer.yaml; a commented template with every option is shipped alongside it as /etc/pdns-pf/settingssyncer.example.yaml.

Environment variables are expanded in all values before parsing. Write password: "${REDIS_PASSWORD}" and set the variable in the unit's environment file to avoid storing secrets in the config file.

Top-level structure¶

Parameter	Type	Default	Description
`lmdb`	`LMDB`	—	LMDB database location and options. Required.
`redis`	`Redis`	—	Redis server connections and sync behaviour.
`http`	`HTTP`	—	HTTP server for Prometheus metrics and status page.
`log`	`Log`	—	Log output format and verbosity.

Deprecation policy¶

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

Full example config¶

Click to expand the shipped example config

# Example config file for the Settings Syncer client

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

  # 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: 20GB
  #  max_dbs: 20


redis:
  # Optional CG-NAT region for ip4 syncing.
  # region: "west"
  servers:
    - name: "ip-redis"
      address: "127.0.0.1:5379"
      # mode defines the operation mode of this server.
      # It is a required parameter and valid options are:
      # "ipmapper" for a server that handles ip mappings
      # "admin" for a server that handles settings
      # "single" for a single server handling both of the above
      mode: "ipmapper"

      # Before subscribing or starting a bulk load, check if redis replication is currently in progress.
      # If it is, wait 5 seconds and try again until the replication has finished.
      # If not enabled, subscriptions and bulk loads will start even if a redis replication is ongoing.
      # Default : true
      no_replication_check: false
      # If nothing has been received on the redis pub-sub channel during subscribe_timeout, it will
      # be interepreted as a silent connectivity issue and the channel will be closed and the normal
      # retry mechanism using restart_wait will initiate.
      subscribe_timeout: 10m
      # scan_count controls the max size of each HSCAN and ZSCAN iteration.
      # Default: 1000000
      scan_count: 1000000
      # Number of LMDB updates to batch together in one transaction.
      # Batching improves LMDB transaction efficiency. The worker does not
      # wait for a full batch, but very large batches can increase the time
      # spent processing an already queued burst.
      # Default: 10000
      batch_size: 10000
      # Username is only needed if ACL is used for AUTH (Redis 6+).
      # username: "user"
      # Password as sent in AUTH
      # password: "password"
    - name: "settings-redis"
      address: "127.0.0.1:5379"
      mode: "admin"

  # Time to wait before reconnecting to Redis after a connection failure.
  # Default: 5s
  restart_wait: 5s

  # If the service should automatically restart after a redis failure.
  # Default: true
  restart: true

  #no_subscribe: true


# The HTTP server exposes Prometheus /metrics and a status page
http:
  # Address to listen on. ":9168" listens on port 9168 on all interfaces.
  address: :9168

log:
  level: info      # options: debug, info, warning, error
  format: human    # options: human, json, logfmt

lmdb¶

Controls the LMDB database that stores the synced data.

lmdb.dir_path is required — the service refuses to start without it.

Fields¶

Parameter	Type	Default	Description
`dir_path`	`string`	—	Path to the directory holding `data.mdb`. Required.
`options`	`Options`	see below	Low-level LMDB environment tuning.
`scrape_smaps`	`boolean`	`true`	Read `/proc/self/smaps` to include LMDB memory in the metrics. Disable if smaps scanning causes measurable overhead.
`log_stats`	`boolean`	`false`	Log an LMDB stats line to the journal at each `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`.

lmdb options¶

Low-level LMDB environment parameters. The defaults suit most deployments; only change these if you know what the values mean.

Warning

dir_mask and file_mask must be written in octal notation (e.g. 0775, not 775). A decimal value larger than 0777 (decimal 511) is rejected at startup.

Parameter	Type	Default	Description
`dir_mask`	`int`	`0775`	Directory permission mask for the LMDB directory. Use octal.
`file_mask`	`int`	`0664`	File permission mask for `data.mdb`. Use octal.
`map_size`	`string`	`20GB`	Maximum LMDB map size. Accepts byte suffixes (`GB`, `MB`).
`max_dbs`	`int`	`20`	Maximum number of named databases in the environment.

redis¶

Controls which Redis servers to sync from and how the sync behaves.

Per-server mode and channel configuration¶

Each server entry must have either mode or channels set.

mode sets a named group of channels:

admin — subscribes to oid_user, user_settings, device_profile, settings, and the timestamp channel.
ipmapper — subscribes to ip4p (or ip4p:<region> if redis.region is set), ip6, and the timestamp channel.
single — subscribes to all admin and ipmapper channels and the timestamp channel.

channels accepts an explicit list of channel names. Use this only when the standard modes do not match your Redis layout. Explicit channels are incompatible with a non-empty top-level redis.region: if you need regional sync, use mode instead or configure each ip4p channel with the region appended.

mode and channels are mutually exclusive on a single server entry. The service refuses to start if both are omitted.

Overlapping channels¶

No two server entries may subscribe to the same channel. The service refuses to start if an overlap is detected.

Fields¶

Parameter	Type	Default	Description
`servers`	`[]Server`	—	List of Redis servers to sync from.
`region`	`string`	—	Optional CG-NAT region applied to `ipmapper` and `single` mode servers. Incompatible with servers that use an explicit `channels` list.
`no_bulk`	`boolean`	`false`	Skip the initial bulk load. For testing only.
`no_subscribe`	`boolean`	`false`	Skip pubsub subscription. For testing only.
`restart`	`boolean`	`true`	Reconnect and re-sync automatically after a Redis connection failure.
`restart_wait`	`go: Duration`	`5s`	How long to wait before reconnecting after a failure.

redis.servers¶

Each entry in redis.servers configures one Redis connection and its sync scope.

Parameter	Type	Default	Description
`name`	`string`	`default`	Identifier used in log output and metric labels.
`address`	`string`	—	Redis address in `host:port` form. Required.
`username`	`string`	—	AUTH username. Only needed when Redis ACL is enabled (Redis 6+).
`password`	`string`	—	AUTH password. Masked in log output.
`mode`	`string`	—	Channel group to sync: `admin`, `ipmapper`, or `single`. Mutually exclusive with `channels`.
`channels`	`[]string`	—	Explicit list of channel names to subscribe to. Mutually exclusive with `mode`, and incompatible with a non-empty top-level `redis.region`.
`scan_count`	`int`	`1000000`	Maximum number of entries returned per HSCAN/ZSCAN iteration during bulk load. Higher values reduce round-trips at the cost of larger individual responses.
`batch_size`	`int`	`10000`	Number of queued Redis updates to batch into a single LMDB transaction. Higher values improve LMDB write efficiency for bursts; the worker does not wait for a full batch.
`no_replication_check`	`boolean`	`false`	When `false` (the default), the syncer checks whether Redis replication is in progress before starting a bulk load or subscribing. If replication is ongoing it waits 5 seconds and checks again. Set to `true` to skip this check.
`subscribe_timeout`	`go: Duration`	`10m`	If no message is received on the pubsub connection within this window, the syncer treats the connection as silently broken and reconnects.
`tls`	`tlsconfig.Config`	`{}`	TLS settings for the Redis connection.

redis.tls¶

TLS configuration for a Redis server connection. Uses tlsconfig.Config.

Parameter	Type	Default	Description
`ca_file`	`string`	—	Path to a CA certificate file for server verification.
`cert_file`	`string`	—	Path to a client certificate file.
`key_file`	`string`	—	Path to the private key matching `cert_file`.
`insecure_skip_verify`	`boolean`	`false`	Disable server certificate verification.

To inject the Redis password from the environment:

redis:
  servers:
    - name: ip-redis
      address: "127.0.0.1:5379"
      mode: ipmapper
      password: "${REDIS_PASSWORD}"

http¶

The HTTP server exposes Prometheus metrics and a status page. Omit address to disable the HTTP server entirely.

Parameter	Type	Default	Description
`address`	`string`	—	Listen address in `host:port` form (e.g. `:9168`).

log¶

Parameter	Type	Default	Description
`level`	`string`	`info`	Log verbosity. One of `debug`, `info`, `warn`, `error`.
`format`	`string`	`human`	Log format. One of `human` (coloured, human-readable), `logfmt`, `json`.
`utc`	`boolean`	`true`	Log timestamps in UTC.