You can find configuration files for presets in
are an excellent starting point to create your own configurations.
Configuration is written in TOML. There are multiple sections that may have additional subsections.
[traffic]contains one or more subsections that each define client behaviour, including protocol
[charts]is an optional section which can contain subsections that define charts that should be automatically plotted
[defaults.traffic]is an optional section that makes it possible specify defaults shared by all traffic senders
[input]is an optional section that specifies how to read input data
You can define one or more traffic senders with specific client behaviour. Every traffic sender has a name and may have multiple parameters. At the very least, each traffic sender must define
This is an example of minimal configuration file sending all traffic as DNS-over-TLS using defaults for everything. The name of the traffic sender here is "DoT".
[traffic] [traffic.DoT] protocol = "dot"
The following configuration parameters for traffic senders are supported.
udp: DNS over UDP
tcp: DNS over TCP
dot: DNS over TLS over TCP
doh: DNS over HTTP/2 over TLS over TCP
When multiple traffic senders are defined, weight affects the client distribution between them. Weight is relative to the sum of all weights.
Integer or float. Defaults to 1.
Determines whether clients keep the connection in idle state, i.e. leaving it established after they have received all answers and currently have no more queries to send. Idle time of 0 means the client will close the connection as soon as possible.
Integer. Defaults to 10 seconds.
GnuTLS priority string which can be used to select TLS protocol version and features, for example:
gnutls_priority = "NORMAL:%NO_TICKETS" # don't use TLS Session Resumption gnutls_priority = "NORMAL:-VERS-ALL:+VERS-TLS1.3" # only use TLS 1.3
String. Defaults to
NORMAL which is determined by the system's GnuTLS library.
Individual query timeout in seconds.
Integer. Defaults to 2 seconds.
Increasing the query timeout can negatively impact DNS Shotgun's performance and is not recommended.
Timeout for establishing a connection in seconds.
Integer. Defaults to 5 seconds.
You shouldn't use these unless you need to.
cpu_factor: override the default CPU thread distribution (UDP: 1, TCP:2, DoT/DoH: 3)
max_clients: number of clients each dnssim instance can hold (per-thread settings)
channel_size: number of queries that can be buffered before thread starts to block
batch_size: number of queries processed in each loop
The following options can be used to override the CLI options for
Values in configuration file always take precedence before CLI options.
server: target server's IPv4/IPv6 address
dns_port: target server's port for plain DNS (UDP and TCP)
dot_port: target server's port for DNS-over-TLS
doh_port: target server's port for DNS-over-HTTPS
This section is optional and is only provided as a convenience to automate plotting charts after the test. Anything defined in this section can be achieved by using the plotting scripts directly.
Similarly to the
[traffic] section, it also contains named subsections. Every
such subsection must contain
type which determines the charts that should be
plotted. For example:
[charts] [charts.response-rate] type = "response-rate"
Type determines which chart will be plotted. The following charts are supported:
Title of the chart.
Output filename for the chart. Various file extensions can be used. Defaults to using svg.
These depend on the specific chart type. Generally, any option that can be
passed directly to the plotting scripts can also be specified in the config.
Refer to the tools
--help for possible options.
This section can provide defaults for all traffic senders. If a specific traffic sender re-defines the same parameter, the traffic sender-specific value takes precedence before the default value.
Any parameter that can be specified for traffic senders in
can also be specified in this section. For example, to override the default
behavior to not use TLS Session Resumption, you can use:
[defaults] [defaults.traffic] gnutls_priority = "NORMAL:%NO_TICKETS"
Optionally specifies how to read input data.
[input] pcap = /path/to/input.pcap stop_after_s = 600
Path to PCAP file, overrides value specified by
--read command line option.
Intended as shortcut when re-running test with the same dataset again and again.
Time limit for test, in seconds (integer).
Reading queries from PCAP will stop at first packet with timestamp >=
Defaults to no limit, i.e. read all packets from PCAP.
stop_after_s option negatively impacts DNS Shotgun's read
performance and slows down PCAP processing by 50 %. If this performance
penalty is unacceptable, cut the PCAP using external tools and avoid using