NAME

Net::DNS::Server - Perl extension to implement dynamic DNS servers

SYNOPSIS

  use Net::DNS::Server;

  my $s = new Net::DNS::Server ($addr, \@methods);

  while (my $n = $s->get_question($timeout)) {
                                # Some code
      foreach (0..$n) {
          $s->process($private_data);
          $s->send_response();
          $question = $s->q();
          $answer = $s->answer();
      }
                                # Some more code
  }

  OR

  while ($s->get_question($timeout)) {
                                # Some code
      while ($s->process()) {
          $s->send_response();
          $question = $s->q();
          $answer = $s->answer();
      }
                                # Some more code
  }

DESCRIPTION

This module implements the basis for a simple, event-loop-based DNS server. In general, the code of a DNS server looks like what is presented in the synopsis earlier in this document.

Once a DNS question is received, this module's ->get_question() method will invoke the methods provided in order to generate a suitable answer. After this process is completed it will return a true value so that the user-provided event loop can take control. If the optional timeout expires before a question is received, this method will return a false value.

The methods passed to ->get_question() in the list reference are objects of classes derived from Net::DNS::Method. These objects must provide a method for each type of question (A, PTR, ...). The inheritance mechanism makes this easy as Net::DNS::Method already provides methods for all the RRs known to Net::DNS.

Those methods are invoked passing the current DNS question, the potential answer packet and a reference to a hash containing various pieces of information. The methods should check the question to see if they apply to it (if it matches) and if this is the case, modify the answer packet accordingly. After this actions are performed, they can return() with the OR of the various NS_* constants in order to tell ->get_question() what to do next.

The passed hash contains a number of entries that are discussed below:

>{from}

A NetAddr::IP object containing the address of the host that sent the request in the first place.

>{from_port}

From which port was the request sent.

>{to}

A NetAddr::IP object containing the address to which the request was sent.

>{to_port}

To which port was the request sent.

>{user}

The scalar passed to >process(). This can be used to supply additional information to the methods, such as a dynamic set of filters.

The following methods are provided by Net::DNS::Server:

->new($addr, $r_methods)

Creates a server that will listen at UDP address/port $addr and uses methods in the list referenced by $r_methods. Returns a Net::DNS::Server object if everything goes well or undef in case of errors. These might include the inability to create a socket.

->get_question($timeout)

Waits for up to $timeout seconds for a question to arrive. If $timeout is undefined or zero, the call will block until a question is received. If $timeout expires before getting any questions or any error condition is detected, the call will return a false value.

->process($data)

Calculates a response for the next pending question. Returns true if there are questions pending to process. The optional parameter $data is passed to the methods in the hash they receive as the third parameter.

->send_response()

Sends the previously calculated response to the client.

->q()

Returns the last question received.

->answer()

Returns the last answer received.

EXPORT

None by default.

AUTHOR

Luis E. Muñoz <luismunoz@cpan.org>

CAVEATS

Normally the DNS servers use port 53. Your script must have root privileges in order to bind to this port.

SEE ALSO

perl(1), Net::DNS(3), Net::DNS::Method(3), NetAddr::IP(3)