Usage¶

output:udp()
output:target("::1", 53)
recv, rctx = output:receive()
-- pass in objects using recv(rctx, obj)
-- repeatedly call output:run_nowait() until it returns 0

DNS-over-TLS example configuration¶

output:tls("NORMAL:-VERS-ALL:+VERS-TLS1.3") -- enforce TLS 1.3

DNS-over-HTTPS/2 example configuration¶

output:https2({ method = "POST", uri_path = "/doh" })

Functions¶

DnsSim.new(max_clients)

Create a new DnsSim output for up to max_clients.

DnsSim.check_version(req_version)

Check that version of dnssim is at minimum the one passed as req_version and return the actual version number. Return nil if the condition is not met.

If no req_version is specified no check is done and only the version number is returned.

DnsSim.check_json_version(req_version)

Check that version of dnssim's JSON data format is at minimum the one passed as req_version and return the actual version number. Return nil if the condition is not met.

If no req_version is specified no check is done and only the version number is returned.

DnsSim:log(name)

Return the Log object to control logging of this instance or module. Optionally, set the instance's log name. Unique name should be used for each instance.

DnsSim:target(ip, port)

Set the target IPv4/IPv6 address where queries will be sent to.

DnsSim:bind(ip)

Specify source IPv4/IPv6 address for sending queries. Can be set multiple times. Addresses are selected round-robin when sending.

DnsSim:udp(tcp_fallback)

Set the preferred transport to UDP.

When the optional argument tcp_fallback is set to true, individual queries are re-tried over TCP when TC bit is set in the answer. Defaults to false (aka only UDP is used).

DnsSim:tcp()

Set the transport to TCP.

DnsSim:tls(tls_priority)

Set the transport to TLS.

The optional argument tls_priority is a GnuTLS priority string, which can be used to select TLS versions, cipher suites etc. For example:

- "NORMAL:%NO_TICKETS" will use defaults without TLS session resumption.

- "SECURE128:-VERS-ALL:+VERS-TLS1.3" will use only TLS 1.3 with 128-bit secure ciphers.

Refer to: https://gnutls.org/manual/html_node/Priority-Strings.html

DnsSim:https2(http2_options, tls_priority)

Set the transport to HTTP/2 over TLS.

http2_options is a lua table which supports the following keys:

method: GET (default) or POST

uri_path: where queries will be sent. Defaults to /dns-query

zero_out_msgid: when true (default), query ID is always set to 0

See tls() method for tls_priority documentation.

DnsSim:timeout(seconds)

Set timeout for the individual requests in seconds (default 2s).

Beware: increasing this value while the target resolver isn't very responsive (cold cache, heavy load) may degrade DnsSim's performance and skew the results.

DnsSim:idle_timeout(seconds)

Set TCP connection idle timeout for connection reuse according to RFC7766, Section 6.2.3 (defaults to 10s). When set to zero, connections are closed immediately after there are no more pending queries.

DnsSim:handshake_timeout(seconds)

Set TCP connection handshake timeout (defaults to 5s). During heavy load, the server may no longer accept new connections. This parameter ensures such connection attempts are aborted after the timeout expires.

DnsSim:run_nowait()

Run the libuv loop once without blocking when there is no I/O. This should be called repeatedly until 0 is returned and no more data is expected to be received by DnsSim.

DnsSim:free_after_use(free_after_use)

Set this to true if DnsSim should free the memory of passed-in objects (useful when using dnsjit.filter.copy to pass objects from different thread).

DnsSim:discarded()

Number of input packets discarded due to various reasons. To investigate causes, run with increased logging level.

DnsSim:requests()

Number of valid requests (input packets) processed.

DnsSim:answers()

Number of requests that received an answer

DnsSim:noerror()

Number of requests that received a NOERROR response

DnsSim:stats_collect(seconds)

Configure statistics to be collected every N seconds.

DnsSim:stats_finish()

Stop the collection of statistics.

DnsSim:export(filename)

Export the results to a JSON file.

DnsSim:receive()

Return the C function and context for receiving objects. Only dnsjit.filter.core.object.ip or dnsjit.filter.core.object.ip6 objects are supported. The component expects a 32bit integer (in host order) ranging from 0 to max_clients written to first 4 bytes of destination IP. See dnsjit.filter.ipsplit.

DnsSim:udp_only()

Deprecated: use udp() instead.

Set the transport to UDP (without any TCP fallback).