Skip to content

Simulator HTTP Server

The PowerDNS Platform Filter Simulator HTTP Server (pdns-pf-simulator-server) hosts the Platform Filter Lua filter engine in a long-running process and exposes it as a query API. It runs the same filtering code the recursor runs, but reaches it through an HTTP REST endpoint (and optionally a NATS subject) instead of a DNS query.

What it does

  • Looks up domain categorizations from the local LMDB feed databases that the OX Feed clients keep in sync.
  • Simulates a user's filter decision end-to-end: given a domain plus a subscriber identifier (IP, username, or device id), returns the same verdict the recursor would return for a real DNS query, with optional verbose rule-evaluation logs.
  • Returns OX Feed classification code mappings so the Admin Portal can label numeric category codes with their human-readable names.
  • Reports its own state — region, last sync status, version — via a status page and a Prometheus /metrics endpoint.

It is primarily a test, debug, and integration surface for the rest of the platform. The Admin Portal calls it to answer the operator question "would this domain be filtered for this user, and why?". It is not part of the live DNS resolution path.

It can also be a live proxy decision backend. A proxy can call the simulator's /api/v1/simulate endpoint for each proxied HTTP or TLS/SNI decision instead of running the filter engine against local LMDBs in the proxy process. The current OpenResty proxy uses this path when it is configured with proxyremotebaseurl.

Two transports

The service can serve its API over two transports, independently:

  • HTTP. Always on when http.address is configured. The Admin Portal and operators connecting by hand both use this transport.
  • NATS (via itsy). Enabled when nats.itsy.url is set, or the NATS_URL environment variable is set. Lets the service be reached from other Platform Filter components in deployments where direct HTTP routing is awkward.

Both transports can be enabled at the same time; they share a single pool of Lua workers behind them.

Who this documentation is for

This site is for operators diving into a running deployment — the service has already been installed by Ansible (or equivalent tooling), and you need to understand how it behaves and what each YAML knob does. There is no installation walkthrough here.

Next steps

  • Architecture: how the service fits into Platform Filter, the request flow, and the Lua worker pool.
  • Configuration: full YAML reference for http, nats, lua, and log.
  • Operations: systemd, CLI flags, the REST API surface, and the metric reference.