.\" Copyright (c) 2018-2022, 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.dnscli 3 "1.2.3" "dnsjit"
.SH NAME
dnsjit.output.dnscli \- DNS aware UDP/TCP/TLS client
.SH SYNOPSIS
  local dnscli = require("dnsjit.output.dnscli")
.SS UDP Receiver Chain
  local output = dnscli.new(dnscli.UDP)
  output:connect("127.0.0.1", "53")
  input:receiver(output)
.SS TCP Nonblocking
  local output = dnscli.new(dnscli.TCP + dnscli.NONBLOCKING)
  output:send(object)
.SH DESCRIPTION
The DNS client can a
.I core.object.dns
or a
.I core.object.payload
object via the receiver interface or using
.I send()
and send it as DNS query after which it can receive the response by using
the producer interface.
If the object being sent is a
.I core.object.dns
then it will look at
.I includes_dnslen
attribute and depending on the protocol it will disregard, include or send
the DNS length as an extra packet.
If the object being sent is a
.I core.object.payload
then no special handling will be done and it will be sent as is.
When receiving responses the producer interface will generate
.I core.object.payload
objects which may include the DNS length depending on the protocol used and
must be handled by the caller.
.SS MODES
These transport modes and options are available when creating a new Dnscli
output.
.TP
UDP
Create an output using UDP.
.TP
TCP
Create an output using TCP.
.TP
TLS
Create an output using TCP and encrypt it with TLS.
.TP
NONBLOCKING
Make the client nonblocking, see
.I send()
and
.IR produce() .
.SS Functions
.TP
.BR Dnscli.new "(mode)"
Create a new Dnscli output.
.TP
.BR Dnscli:timeout "(seconds, nanoseconds)"
Set or return the timeout used for sending and reciving, must be used before
.IR connect() .
.TP
.BR Dnscli:connect "(host, port)"
Connect to the
.I host
and
.I port
and return 0 if successful.
.TP
.BR Dnscli:nonblocking "()"
Return if nonblocking mode is on (true) or off (false).
.TP
.BR Dnscli:send "(object, sent)"
Send an object and optionally continue sending after
.I sent
bytes.
Unlike the receive interface this function lets you know if the sending was
successful or not which might be needed on nonblocking connections.
Returns -2 on error, -1 if interrupted, timed out or unable to send due to
nonblocking, or the number of bytes sent.
.B Note
the counters for sent, received, errors and timeouts are not affected by
this function.
.TP
.BR Dnscli:receive "()"
Return the C functions and context for receiving objects, these objects
will be sent.
.TP
.BR Dnscli:produce "()"
Return the C functions and context for producing objects, these objects
are received.
If nonblocking mode is enabled the producer will return a payload object
with length zero if there was nothing to receive.
If nonblocking mode is disabled the producer will wait for data and if
timed out (see
.IR timeout )
it will return a payload object with length zero.
The producer returns nil on error.
.TP
.BR Dnscli:packets "()"
Return the number of "packets" sent, actually the number of completely sent
payloads.
.TP
.BR Dnscli:received "()"
Return the number of "packets" received, actually the number of successful
calls to
.IR recvfrom (2)
that returned data.
.TP
.BR Dnscli:errors "()"
Return the number of errors when sending or receiving.
.TP
.BR Dnscli:timeouts "()"
Return the number of timeouts when sending or receiving.
.SH SEE ALSO
.BR core.object.dns (3),
.BR core.object.payload (3),
.BR core.timespec (3)
.SH AUTHORS and CONTRIBUTORS
Jerry Lundström (DNS-OARC),
Tomáš Křížek (CZ.NIC),
Petr Špaček (ISC)
.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