1Net::DNS::Nameserver(3)User Contributed Perl DocumentatioNnet::DNS::Nameserver(3)
2
3
4

NAME

6       Net::DNS::Nameserver - DNS server class
7

SYNOPSIS

9           use Net::DNS::Nameserver;
10
11           my $nameserver = new Net::DNS::Nameserver(
12               LocalAddr       => ['::1' , '127.0.0.1'],
13               ZoneFile        => "filename"
14               );
15
16           my $nameserver = new Net::DNS::Nameserver(
17               LocalAddr       => '10.1.2.3',
18               LocalPort       => 5353,
19               ReplyHandler    => \&reply_handler
20           );
21

DESCRIPTION

23       Net::DNS::Nameserver offers a simple mechanism for instantiation of
24       customised DNS server objects intended to provide test responses to
25       queries emanating from a client resolver.
26
27       It is not, nor will it ever be, a general-purpose DNS nameserver
28       implementation.
29
30       See "EXAMPLE" for an example.
31

METHODS

33   new
34           $nameserver = new Net::DNS::Nameserver(
35               LocalAddr       => ['::1' , '127.0.0.1'],
36               ZoneFile        => "filename"
37               );
38
39           $nameserver = new Net::DNS::Nameserver(
40               LocalAddr       => '10.1.2.3',
41               LocalPort       => 5353,
42               ReplyHandler    => \&reply_handler,
43               Verbose         => 1,
44               Truncate        => 0
45           );
46
47       Returns a Net::DNS::Nameserver object, or undef if the object could not
48       be created.
49
50       Each instance is configured using the following optional arguments:
51
52           LocalAddr           IP address on which to listen   Defaults to loopback address
53           LocalPort           Port on which to listen         Defaults to 53
54           ZoneFile            Name of file containing RRs
55                               accessed using the default
56                               reply-handling subroutine
57           ReplyHandler        Reference to customised
58                               reply-handling subroutine
59           NotifyHandler       Reference to reply-handling
60                               subroutine for queries with
61                               opcode NOTIFY (RFC1996)
62           UpdateHandler       Reference to reply-handling
63                               subroutine for queries with
64                               opcode UPDATE (RFC2136)
65           Verbose             Report internal activity        Defaults to 0 (off)
66           Truncate            Truncates UDP packets that
67                               are too big for the reply       Defaults to 1 (on)
68           IdleTimeout         TCP clients are disconnected
69                               if they are idle longer than
70                               this duration                   Defaults to 120 (secs)
71
72       The LocalAddr attribute may alternatively be specified as a list of IP
73       addresses to listen to.  If the IO::Socket::IP library package is
74       available on the system this may also include IPv6 addresses.
75
76       The ReplyHandler subroutine is passed the query name, query class,
77       query type and optionally an argument containing the peerhost, the
78       incoming query, and the name of the incoming socket (sockethost). It
79       must either return the response code and references to the answer,
80       authority, and additional sections of the response, or undef to leave
81       the query unanswered.  Common response codes are:
82
83           NOERROR     No error
84           FORMERR     Format error
85           SERVFAIL    Server failure
86           NXDOMAIN    Non-existent domain (name doesn't exist)
87           NOTIMP      Not implemented
88           REFUSED     Query refused
89
90       For advanced usage it may also contain a headermask containing an
91       hashref with the settings for the "aa", "ra", and "ad" header bits. The
92       argument is of the form "{ ad => 1, aa => 0, ra => 1 }".
93
94       EDNS options may be specified in a similar manner using optionmask "{
95       $optioncode => $value, $optionname => $value }".
96
97       See RFC 1035 and the IANA dns-parameters file for more information:
98
99         ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
100         http://www.isi.edu/in-notes/iana/assignments/dns-parameters
101
102       The nameserver will listen for both UDP and TCP connections.  On Unix-
103       like systems, the program will probably have to run as root to listen
104       on the default port, 53.  A non-privileged user should be able to
105       listen on ports 1024 and higher.
106
107       UDP reply truncation functionality was introduced in VERSION 830.  The
108       size limit is determined by the EDNS0 size advertised in the query,
109       otherwise 512 is used.  If you want to do packet truncation yourself
110       you should set "Truncate" to 0 and truncate the reply packet in the
111       code of the ReplyHandler.
112
113       See "EXAMPLE" for an example.
114
115   main_loop
116           $ns->main_loop;
117
118       Start accepting queries. Calling main_loop never returns.
119
120   loop_once
121           $ns->loop_once( [TIMEOUT_IN_SECONDS] );
122
123       Start accepting queries, but returns. If called without a parameter,
124       the call will not return until a request has been received (and replied
125       to).  Otherwise, the parameter specifies the maximum time to wait for a
126       request.  A zero timeout forces an immediate return if there is nothing
127       to do.
128
129       Handling a request and replying obviously depends on the speed of
130       ReplyHandler. Assuming a fast ReplyHandler, loop_once should spend just
131       a fraction of a second, if called with a timeout value of 0.0 seconds.
132       One exception is when an AXFR has requested a huge amount of data that
133       the OS is not ready to receive in full. In that case, it will remain in
134       a loop (while servicing new requests) until the reply has been sent.
135
136       In case loop_once accepted a TCP connection it will immediately check
137       if there is data to be read from the socket. If not it will return and
138       you will have to call loop_once() again to check if there is any data
139       waiting on the socket to be processed. In most cases you will have to
140       count on calling "loop_once" twice.
141
142       A code fragment like:
143
144           $ns->loop_once(10);
145           while( $ns->get_open_tcp() ){
146               $ns->loop_once(0);
147           }
148
149       Would wait for 10 seconds for the initial connection and would then
150       process all TCP sockets until none is left.
151
152   get_open_tcp
153       In scalar context returns the number of TCP connections for which state
154       is maintained. In array context it returns IO::Socket objects, these
155       could be useful for troubleshooting but be careful using them.
156

EXAMPLE

158       The following example will listen on port 5353 and respond to all
159       queries for A records with the IP address 10.1.2.3.   All other queries
160       will be answered with NXDOMAIN.   Authority and additional sections are
161       left empty.  The $peerhost variable catches the IP address of the peer
162       host, so that additional filtering on its basis may be applied.
163
164           #!/usr/bin/perl
165
166           use strict;
167           use warnings;
168           use Net::DNS::Nameserver;
169
170           sub reply_handler {
171               my ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @_;
172               my ( $rcode, @ans, @auth, @add );
173
174               print "Received query from $peerhost to " . $conn->{sockhost} . "\n";
175               $query->print;
176
177               if ( $qtype eq "A" && $qname eq "foo.example.com" ) {
178                       my ( $ttl, $rdata ) = ( 3600, "10.1.2.3" );
179                       my $rr = new Net::DNS::RR("$qname $ttl $qclass $qtype $rdata");
180                       push @ans, $rr;
181                       $rcode = "NOERROR";
182               } elsif ( $qname eq "foo.example.com" ) {
183                       $rcode = "NOERROR";
184
185               } else {
186                       $rcode = "NXDOMAIN";
187               }
188
189               # mark the answer as authoritative (by setting the 'aa' flag)
190               my $headermask = {aa => 1};
191
192               # specify EDNS options  { option => value }
193               my $optionmask = {};
194
195               return ( $rcode, \@ans, \@auth, \@add, $headermask, $optionmask );
196           }
197
198
199           my $ns = new Net::DNS::Nameserver(
200               LocalPort    => 5353,
201               ReplyHandler => \&reply_handler,
202               Verbose      => 1
203               ) || die "couldn't create nameserver object\n";
204
205
206           $ns->main_loop;
207

BUGS

209       Limitations in perl 5.8.6 makes it impossible to guarantee that replies
210       to UDP queries from Net::DNS::Nameserver are sent from the IP-address
211       they were received on. This is a problem for machines with multiple IP-
212       addresses and causes violation of RFC2181 section 4.  Thus a UDP socket
213       created listening to INADDR_ANY (all available IP-addresses) will reply
214       not necessarily with the source address being the one to which the
215       request was sent, but rather with the address that the operating system
216       chooses. This is also often called "the closest address". This should
217       really only be a problem on a server which has more than one IP-address
218       (besides localhost - any experience with IPv6 complications here, would
219       be nice). If this is a problem for you, a work-around would be to not
220       listen to INADDR_ANY but to specify each address that you want this
221       module to listen on. A separate set of sockets will then be created for
222       each IP-address.
223
225       Copyright (c)2000 Michael Fuhr.
226
227       Portions Copyright (c)2002-2004 Chris Reinhardt.
228
229       Portions Copyright (c)2005 Robert Martin-Legene.
230
231       Portions Copyright (c)2005-2009 O.M, Kolkman, RIPE NCC.
232
233       Portions Copyright (c)2017 Dick Franks.
234
235       All rights reserved.
236

LICENSE

238       Permission to use, copy, modify, and distribute this software and its
239       documentation for any purpose and without fee is hereby granted,
240       provided that the above copyright notice appear in all copies and that
241       both that copyright notice and this permission notice appear in
242       supporting documentation, and that the name of the author not be used
243       in advertising or publicity pertaining to distribution of the software
244       without specific prior written permission.
245
246       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
247       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
248       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
249       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
250       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
251       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
252       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
253

SEE ALSO

255       perl, Net::DNS, Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Update,
256       Net::DNS::Header, Net::DNS::Question, Net::DNS::RR, RFC 1035
257
258
259
260perl v5.30.1                      2020-01-30           Net::DNS::Nameserver(3)
Impressum