.\" Copyright (c) 2018-2021, OARC, Inc.
.\" All rights reserved.
.\"
.\" This file is part of dnsjit.
.\"
.\" dnsjit is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" dnsjit is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with dnsjit.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsjit.output.dnssim 3 "1.1.0" "dnsjit"
.SH NAME
dnsjit.output.dnssim \- Simulate independent DNS clients over various transports
.SH SYNOPSIS
  output = require("dnsjit.output.dnssim").new()
.SS 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
.SS DNS-over-TLS example configuration
  output:tls("NORMAL:-VERS-ALL:+VERS-TLS1.3")  -- enforce TLS 1.3
.SS DNS-over-HTTPS/2 example configuration
  output:https2({ method = "POST", uri_path = "/doh" })
.SH DESCRIPTION
Output module for simulating traffic from huge number of independent,
individual DNS clients.
Uses libuv for asynchronous communication.
There may only be a single DnsSim in a thread.
Use
.I dnsjit.core.thread
to have multiple DnsSim instances.
.P
With proper use of this component, it is possible to simulate hundreds of
thousands of clients when using a high-performance server.
This also applies for state-full transports.
The complete set-up is quite complex and requires other components.
See DNS Shotgun
.RI ( https://gitlab.nic.cz/knot/shotgun )
for dnsjit scripts ready for use for high-performance
benchmarking.
.SS Functions
.TP
.BR DnsSim.new "(max_clients)"
Create a new DnsSim output for up to max_clients.
.TP
.BR DnsSim.check_version "(req_version)"
Check that version of dnssim is at minimum the one passed as
.B req_version
and return the actual version number.
Return nil if the condition is not met.

If no
.B req_version
is specified no check is done and only the version number is returned.
.TP
.BR DnsSim.check_json_version "(req_version)"
Check that version of dnssim's JSON data format is at minimum the one passed as
.B req_version
and return the actual version number.
Return nil if the condition is not met.

If no
.B req_version
is specified no check is done and only the version number is returned.
.TP
.BR 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.
.TP
.BR DnsSim:target "(ip, port)"
Set the target IPv4/IPv6 address where queries will be sent to.
.TP
.BR DnsSim:bind "(ip)"
Specify source IPv4/IPv6 address for sending queries.
Can be set multiple times.
Addresses are selected round-robin when sending.
.TP
.BR DnsSim:udp "(tcp_fallback)"
Set the preferred transport to UDP.

When the optional argument
.B tcp_fallback
is set to true, individual queries are re-tried over TCP when TC bit is set in the answer.
Defaults to
.B false
(aka only UDP is used).
.TP
.BR DnsSim:tcp "()"
Set the transport to TCP.
.TP
.BR DnsSim:tls "(tls_priority)"
Set the transport to TLS.

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

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

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

Refer to:
.I https://gnutls.org/manual/html_node/Priority-Strings.html
.TP
.BR DnsSim:https2 "(http2_options, tls_priority)"
Set the transport to HTTP/2 over TLS.

.B http2_options
is a lua table which supports the following keys:

.B method:
.B GET
(default)
or
.B POST

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

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

See tls() method for
.B tls_priority
documentation.
.TP
.BR DnsSim:timeout "(seconds)"
Set timeout for the individual requests in seconds (default 2s).

.BR 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.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR DnsSim:free_after_use "(free_after_use)"
Set this to true if DnsSim should free the memory of passed-in objects
(useful when using
.I dnsjit.filter.copy
to pass objects from different thread).
.TP
.BR DnsSim:discarded "()"
Number of input packets discarded due to various reasons.
To investigate causes, run with increased logging level.
.TP
.BR DnsSim:requests "()"
Number of valid requests (input packets) processed.
.TP
.BR DnsSim:answers "()"
Number of requests that received an answer
.TP
.BR DnsSim:noerror "()"
Number of requests that received a NOERROR response
.TP
.BR DnsSim:stats_collect "(seconds)"
Configure statistics to be collected every N seconds.
.TP
.BR DnsSim:stats_finish "()"
Stop the collection of statistics.
.TP
.BR DnsSim:export "(filename)"
Export the results to a JSON file.
.TP
.BR DnsSim:receive "()"
Return the C function and context for receiving objects.
Only
.I dnsjit.filter.core.object.ip
or
.I 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
.IR dnsjit.filter.ipsplit .
.TP
.BR DnsSim:udp_only "()"
Deprecated: use udp() instead.

Set the transport to UDP (without any TCP fallback).
.SH SEE ALSO
.BR dnsjit.filter.copy (3),
.BR dnsjit.filter.ipsplit (3),
.BR dnsjit.filter.core.object.ip (3),
.BR dnsjit.filter.core.object.ip6 (3),
.BR https://gitlab.nic.cz/knot/shotgun
.SH AUTHORS
Jerry Lundström (DNS-OARC),
Tomáš Křížek (CZ.NIC)
.LP
Maintained by DNS-OARC
.LP
.RS
.I https://www.dns-oarc.net/
.RE
.LP
.SH BUGS
For issues and feature requests please use:
.LP
.RS
\fIhttps://github.com/DNS-OARC/dnsjit/issues\fP
.RE
.LP
For question and help please use:
.LP
.RS
\fIadmin@dns-oarc.net\fP
.RE
.LP