plucky (3) dnsjit.output.dnscli.3.gz

NAME

       dnsjit.output.dnscli - DNS aware UDP/TCP/TLS client

SYNOPSIS

         local dnscli = require("dnsjit.output.dnscli")

   UDP Receiver Chain
         local output = dnscli.new(dnscli.UDP)
         output:connect("127.0.0.1", "53")
         input:receiver(output)

   TCP Nonblocking
         local output = dnscli.new(dnscli.TCP + dnscli.NONBLOCKING)
         output:send(object)

DESCRIPTION

       The  DNS client can a core.object.dns or a core.object.payload object via the receiver interface or using
       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  core.object.dns  then  it will look at 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 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 core.object.payload objects which  may
       include the DNS length depending on the protocol used and must be handled by the caller.

   MODES
       These transport modes and options are available when creating a new Dnscli output.

       UDP    Create an output using UDP.

       TCP    Create an output using TCP.

       TLS    Create an output using TCP and encrypt it with TLS.

       NONBLOCKING
              Make the client nonblocking, see send() and produce().

   Functions
       Dnscli.new(mode)
              Create a new Dnscli output.

       Dnscli:timeout(seconds, nanoseconds)
              Set or return the timeout used for sending and reciving, must be used before connect().

       Dnscli:connect(host, port)
              Connect to the host and port and return 0 if successful.

       Dnscli:nonblocking()
              Return if nonblocking mode is on (true) or off (false).

       Dnscli:send(object, sent)
              Send  an  object  and  optionally continue sending after 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.  Note the counters for  sent,  received,  errors  and
              timeouts are not affected by this function.

       Dnscli:receive()
              Return the C functions and context for receiving objects, these objects will be sent.

       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 timeout) it will return a payload object with length zero.   The  producer  returns
              nil on error.

       Dnscli:packets()
              Return the number of "packets" sent, actually the number of completely sent payloads.

       Dnscli:received()
              Return  the  number  of "packets" received, actually the number of successful calls to recvfrom(2)
              that returned data.

       Dnscli:errors()
              Return the number of errors when sending or receiving.

       Dnscli:timeouts()
              Return the number of timeouts when sending or receiving.

SEE ALSO

       core.object.dns(3), core.object.payload(3), core.timespec(3)

AUTHORS and CONTRIBUTORS

       Jerry Lundström (DNS-OARC), Tomáš Křížek (CZ.NIC), Petr Špaček (ISC)

       Maintained by DNS-OARC

              https://www.dns-oarc.net/

BUGS

       For issues and feature requests please use:

              https://github.com/DNS-OARC/dnsjit/issues

       For question and help please use:

              admin@dns-oarc.net