Configuration¶

The IP Mapper reads its configuration from a YAML file. The default path is /etc/pdns-pf/ipmapper.yaml; a commented example with every option is shipped alongside it as /etc/pdns-pf/ipmapper.example.yaml.

Environment variables are expanded in all values before parsing, so you can write password: "${REDIS_PASSWORD}" and set the variable in the unit's environment file.

Top-level structure¶

Parameter	Type	Default	Description
`http`	`HTTP`	—	HTTP status/metrics server and optional session API.
`redis`	`Redis`	—	Redis persistence backend.
`resp`	`RESP`	—	RESP (Redis protocol) listener.
`nats`	`NATS`	—	NATS micro-service interface.
`options`	`Options`	—	Session lifecycle tuning.
`log`	`Log`	—	Log output format.

All sections are optional. Omitting a section's address field disables that interface. Omitting redis.address disables Redis persistence.

Deprecation policy¶

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

Full example config¶

Click to expand the shipped example config

http:
    address: ":5556"
    tls: {}
    # Optional session-management HTTP API, disabled by default.
    api:
        enabled: false
        # max_body_size: 8MB
        # Shared secret for the X-API-Key header. Requires http.tls.
        # auth_token: "${PDNS_PF_IPMAPPER_API_TOKEN}"
redis:
    address: "${PDNS_PF_REDIS_HOST}:6379"
    tls: {}
    # Optional Redis-backed lock for active/passive HA deployments.
    lock:
        enabled: true
        #expiry: 5m
        #extend_interval: 10s
    #batch_size: 100
    #work_queue_size: 1000000
    #inflight_max_size: 10000
    #send_queue_size: 1000
    #result_queue_size: 1000
resp:
    address: ":5555"
    tls: {}

nats:
    # As defined by: https://github.com/PowerDNS/itsy
    itsy:
        url: "nats://localhost:4222"
        # Optional prefix, if not set it will default to svc meaning
        # subjects will look like svc.ipmapper.abc
        prefix: "pdnspf"
        topologies: []
        meta: {}
        tls: {}

options:
    # Query Redis for static opaqueID to username mappings when using NATS
    # Default: false
    query_static_mappings: true
    # Initial allocations for ipmapper state
    # Default: 10_000_000  (10 million)
    initial_allocation: 100000

log: 
    format: "logfmt"

`http`¶

The HTTP section enables the status page, Prometheus metrics endpoint, pprof handlers, and — optionally — the session API. Omit address to disable the HTTP server entirely.

Parameter	Type	Default	Description
`address`	`string`	—	Bind address in `host:port` form (e.g. `:5556`). Required to enable HTTP.
`tls`	`tlsconfig.Config`	`{}`	TLS settings for the HTTP listener. A server certificate (`cert_file`/`key_file`) makes the listener serve HTTPS; adding a client CA (`ca_file`) with `require_client_cert: true` enables mTLS.
`api`	`HTTPAPI`	—	Session-management HTTP API. Disabled by default.

`http.api`¶

The HTTP API exposes the same four session operations as the NATS interface (set-session, set-session-batch, get-sessions, clean-sessions) as JSON POST endpoints under /api/v1/sessions. See Architecture → HTTP for the endpoint and request/response reference.

Parameter	Type	Default	Description
`enabled`	`boolean`	`false`	Enable the session API endpoints. Requires `http.address` to be set.
`max_body_size`	`datasize.ByteSize`	`8MB`	Maximum accepted request body. Larger requests get `413 Request Entity Too Large`. Accepts unit suffixes such as `10MB`; must be greater than `0`.
`auth_token`	`string`	—	Shared secret required in the `X-API-Key` header on every request. When unset, the API is open. Requires `http.tls` — the service refuses to start with a token but no TLS, since the token would otherwise be sent in clear text. Supports `${ENV_VAR}` expansion and is masked when the config is logged.

Warning

The session API has no authentication beyond the optional shared token. Run it over TLS (or mTLS) and, in production, set auth_token or restrict access at the network layer. A token configured without TLS is rejected at startup.

Example:

http:
    address: ":5556"
    tls:
        cert_file: /etc/pdns-pf/tls/ipmapper.crt
        key_file: /etc/pdns-pf/tls/ipmapper.key
        # For mTLS, also require a client certificate signed by this CA:
        # ca_file: /etc/pdns-pf/tls/client-ca.crt
        # require_client_cert: true
    api:
        enabled: true
        max_body_size: 8MB
        auth_token: "${PDNS_PF_IPMAPPER_API_TOKEN}"

`redis`¶

The Redis section controls the persistence backend. Omit address (or pass --no-redis on the command line) to run without persistence — all state is then lost on restart.

Connectivity¶

Parameter	Type	Default	Description
`address`	`string`	—	Redis server address in `host:port` form. Required to enable persistence.
`username`	`string`	—	Username for Redis 6+ ACL authentication.
`password`	`string`	—	Password. Supports `${ENV_VAR}` expansion.
`tls`	`tlsconfig.Config`	`{}`	TLS settings for the Redis connection.

Example with environment variable expansion:

redis:
    address: "${PDNS_PF_REDIS_HOST}:6379"
    password: "${REDIS_PASSWORD}"

`redis.conn_pool`¶

Connection pool settings. The defaults are well-considered; change them only if you are seeing pool exhaustion in the metrics or logs.

Parameter	Type	Default	Description
`max_idle`	`int`	`10`	Maximum number of idle connections kept open.
`max_active`	`int`	`10`	Maximum number of active connections.
`idle_timeout`	`go: Duration`	`240s`	Close connections idle longer than this duration.

`redis.lock`¶

Optional Redis-backed distributed lock for active/passive high-availability deployments. See Architecture → High availability for the failover model.

When enabled, the IP Mapper acquires a named mutex in Redis on startup and only opens its NATS, RESP, and HTTP interfaces once it holds the lock. The active instance refreshes the lock at extend_interval; passive instances poll for the lock once a second and take over when the active instance releases it or fails to refresh it within expiry.

Parameter	Type	Default	Description
`enabled`	`boolean`	`false`	Enable the Redis-backed HA lock. When unset or `false`, every instance is active.
`expiry`	`go: Duration`	`5m`	Lock TTL in Redis. If the active instance fails to refresh within this window, the lock expires and a passive instance takes over.
`extend_interval`	`go: Duration`	`10s`	Interval at which the active instance refreshes the lock. Must be well below `expiry`; the active process exits if extension keeps failing and the elapsed failure time exceeds 70% of `expiry`.
`retry_interval`	`go: Duration`	`1s`	Interval at which passive instances retry acquiring the lock.
`mutex_name`	`string`	`pdns-ipmapper-global-mutex`	Redis key used for the mutex. All instances that should coordinate as one HA group must use the same value.

Example:

redis:
    address: "${PDNS_PF_REDIS_HOST}:6379"
    lock:
        enabled: true
        expiry: 5m
        extend_interval: 10s

The lock is held in the same Redis instance configured by redis.address under the key set by mutex_name (default pdns-ipmapper-global-mutex).

Performance knobs¶

These control the internal Redis sync pipeline. The defaults are sized for several hundred thousand session updates per second on typical hardware.

Warning

Change these only if you understand the trade-offs. Setting work_queue_size too low causes the service to stop accepting updates when Redis is slow; setting inflight_max_size too high increases memory usage proportionally to Redis round-trip latency.

Parameter	Type	Default	Description
`batch_size`	`int`	`100`	Maximum number of updates flushed to Redis in one batch.
`work_queue_size`	`int`	`1000000`	Depth of the internal work queue. At 300 000 updates/s this is roughly a 3-second buffer.
`inflight_max_size`	`int`	`10000`	Maximum changes allowed in flight to Redis at once. At 300 000 updates/s this tolerates 33 ms of Redis round-trip latency.
`send_queue_size`	`int`	`1000`	Depth of the internal send queue.
`result_queue_size`	`int`	`1000`	Depth of the internal result queue.

`resp`¶

The RESP section enables the Redis-protocol listener. Omit address to disable it.

Parameter	Type	Default	Description
`address`	`string`	—	Bind address in `host:port` form (e.g. `:5555`). Required to enable the RESP listener.
`tls`	`tlsconfig.Config`	`{}`	TLS settings for the RESP listener.

`nats`¶

The NATS section enables the NATS micro-service interface. Omit nats.itsy.url to disable it.

`nats.itsy`¶

The itsy sub-section follows the itsy configuration schema.

Parameter	Type	Default	Description
`url`	`string`	—	NATS server URL (e.g. `nats://localhost:4222`). Required to enable NATS.
`prefix`	`string`	`svc`	Subject prefix. With `prefix: pdnspf` commands are addressed as `pdnspf.ipmapper.<command>`.
`topologies`	`[]string`	`[]`	Optional topology tags.
`meta`	`map[string]string`	`{}`	Optional metadata attached to the service registration.
`tls`	`tlsconfig.Config`	`{}`	TLS settings for the NATS connection.

`options`¶

Session lifecycle and memory tuning.

Memory sizing¶

The IP Mapper pre-allocates its internal maps on startup. The right value for initial_allocation is the number of sessions you expect the service to hold at peak. Over-allocating wastes memory from the start; under-allocating causes Go to grow the maps at runtime, which is more expensive.

A session with a typical set of fields and one allocation uses roughly 1–2 kB of heap. A deployment with 1 million sessions should set initial_allocation: 1000000 and expect the process to use on the order of 1–2 GiB of heap before GC overhead.

Note

The service sets Go's garbage collector target (GOGC) to 50 by default, reducing peak heap overhead from 2× to 1.5× the live set. You can override this by setting GOGC in the environment before starting the service.

Parameter	Type	Default	Description
`initial_allocation`	`int`	`10000000`	Starting capacity of the internal session maps. Set to your expected peak session count.
`session_mute_expiry`	`go: Duration`	`30s`	How long a stopped session stays muted. Muted sessions absorb out-of-order events that arrive after a stop. See Architecture → session lifecycle.
`expired_sessions_cleanup_interval`	`go: Duration`	`35s`	Interval between sweeps that remove sessions past their TTL.
`query_static_mappings`	`boolean`	`false`	When enabled, the NATS `get-sessions` path queries Redis DB3 for static opaque-ID-to-username mappings as a fallback.

`log`¶

Parameter	Type	Default	Description
`format`	`string`	`logfmt`	Log output format. `logfmt` for key=value lines, `json` for JSON objects.

Configuration¶

Top-level structure¶

Deprecation policy¶

Full example config¶

http¶

http.api¶

redis¶

Connectivity¶

redis.conn_pool¶

redis.lock¶