dstore-dist

Command Arguments

dstore-dist [-config file] [-debug] [-cpuprofile] [-memprofile]

Description

dstore-dist acts as a router/distributor of the protobuf messages that are generated by recursor and dnsdist. It is configured using a YAML-based configuration file.

dstore-dist is configured with a set of destinations, which indicate all the possible destinations for a message. It is also configured with a set of routes; each route can send messages to one or more destinations, and can also be configured to perform filtering on the messages.

Flags

Flag	Argument	Description
-config	file	Load configuration from file
-debug		Generate debug logging
-help		Display a helpful message and exit.
-cpuprofile		Write CPU profile to file
-memprofile		Write memory profile to file

Files

/etc/pdns-dstore-dist/dstore-dist.yml: Default location of the config file

Configuration

See Configuration of dstore-dist for details of the configuration file format.

Network Protocol/Encoding

When sending messages to destinations, the protocol/encoding used is slightly different depending on the destination.

PDNS Destination

For destinations of type pdns, dstore-dist will send messages over a TCP stream as serialised protobuf messages preceded by framing bytes (the type of framing is configurable). The destination does not send any responses.

Kafka Destination

For destinations of type kafka, the protocol used is the Kafka protocol, and each Kafka Message is encoded as follows:

• Key: This can be either "mm" or "sm".

  • If the Key is "mm" then each Kafka Message contains potentially multiple protobuf messages, which are encoded as repeated Protobuf fields. If Json encoding is selected, then the multiple JSON messages are separated by the , character.
  • If the Key is "sm" then each Kafka Message contains only one protobuf or JSON message.
  • Value: The protobuf message(s), encoded as described above.
  • Headers: The following Kafka headers are set:
  • *msgType: DNSMessage
  • instanceName: (Optional) The name of the instance if set

Storage Destination

For destinations of type storage the encoding can be either protobuf (using the default 16-bit framing), JSON, Parquet, or Bind Query log format (see BIND 9 Administrator Reference Manual)

For JSON and Parquet storage output, include_fields and exclude_fields can be used to control which protobuf fields are written. Parquet storage includes all supported protobuf fields except tracing and OpenTelemetry data fields.

WebSub Destination

For destinations of type websub the encoding is JSON, using the following JSON body in the HTTP POST:

{
    "head": {
        "hub.topic": <topic specified in configuration>,
        "hub.content": "fat"
    },
    "body": {
        "messages": [ <one or more PDNS events encoded as JSON objects> ]
    }
}

OpenTelemetry Destination

For OpenTelemetry destinations, the protocol is gRPC, and the encoding is protobuf.

By default, type: otel exports embedded OpenTelemetry trace data from DNS messages to the OTLP target. Set otel.enable_logs: true to also convert DNS messages into OTLP log records and export them to the OTLP target. Set otel.disable_traces: true for a logs-only destination.

Generated OTel logs can use otel.log_include_fields or otel.log_exclude_fields to limit which DNS message fields are emitted as log attributes. These options use the same field names as JSON include/exclude field filtering and are mutually exclusive.