1Net::DNS::Nameserver(3)User Contributed Perl DocumentatioNnet::DNS::Nameserver(3)
2
6 Net::DNS::Nameserver - DNS server class
7
9 use Net::DNS::Nameserver;
10 my $nameserver = Net::DNS::Nameserver->new(
12 LocalAddr => ['::1' , '127.0.0.1'],
13 ZoneFile => "filename"
14 );
15 my $nameserver = Net::DNS::Nameserver->new(
17 LocalAddr => '10.1.2.3',
18 LocalPort => 5353,
19 ReplyHandler => \&reply_handler
20 );
21
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 It is not, nor will it ever be, a general-purpose DNS nameserver
28 implementation.
29 See "EXAMPLE" for an example.
31
33 new
34 $nameserver = Net::DNS::Nameserver->new(
35 LocalAddr => ['::1' , '127.0.0.1'],
36 ZoneFile => "filename"
37 );
38 $nameserver = Net::DNS::Nameserver->new(
40 LocalAddr => '10.1.2.3',
41 LocalPort => 5353,
42 ReplyHandler => \&reply_handler,
43 Verbose => 1,
44 Truncate => 0
45 );
46 Returns a Net::DNS::Nameserver object, or undef if the object could not
48 be created.
49 Each instance is configured using the following optional arguments:
51 LocalAddr IP address on which to listen Defaults to loopback address
53 LocalPort Port on which to listen Defaults to 5353
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 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 The ReplyHandler subroutine is passed the query name, query class,
77 query type, peerhost, query record, and connection descriptor. It must
78 either return the response code and references to the answer,
79 authority, and additional sections of the response, or undef to leave
80 the query unanswered. Common response codes are:
81 NOERROR No error
83 FORMERR Format error
84 SERVFAIL Server failure
85 NXDOMAIN Non-existent domain (name doesn't exist)
86 NOTIMP Not implemented
87 REFUSED Query refused
88 For advanced usage it may also contain a headermask containing an
90 hashref with the settings for the "aa", "ra", and "ad" header bits. The
91 argument is of the form "{ ad => 1, aa => 0, ra => 1 }".
92 EDNS options may be specified in a similar manner using optionmask "{
94 $optioncode => $value, $optionname => $value }".
95 See RFC 1035 and the IANA dns-parameters file for more information:
97 ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
99 http://www.isi.edu/in-notes/iana/assignments/dns-parameters
100 The nameserver will listen for both UDP and TCP connections. On Unix-
102 like systems, unprivileged users are denied access to ports below 1024.
103 UDP reply truncation functionality was introduced in VERSION 830. The
105 size limit is determined by the EDNS0 size advertised in the query,
106 otherwise 512 is used. If you want to do packet truncation yourself
107 you should set "Truncate" to 0 and truncate the reply packet in the
108 code of the ReplyHandler.
109 See "EXAMPLE" for an example.
111 main_loop
113 $ns->main_loop;
114 Start accepting queries. Calling main_loop never returns.
116 loop_once
118 $ns->loop_once( [TIMEOUT_IN_SECONDS] );
119 Start accepting queries, but returns. If called without a parameter,
121 the call will not return until a request has been received (and replied
122 to). Otherwise, the parameter specifies the maximum time to wait for a
123 request. A zero timeout forces an immediate return if there is nothing
124 to do.
125 Handling a request and replying obviously depends on the speed of
127 ReplyHandler. Assuming a fast ReplyHandler, loop_once should spend just
128 a fraction of a second, if called with a timeout value of 0.0 seconds.
129 One exception is when an AXFR has requested a huge amount of data that
130 the OS is not ready to receive in full. In that case, it will remain in
131 a loop (while servicing new requests) until the reply has been sent.
132 In case loop_once accepted a TCP connection it will immediately check
134 if there is data to be read from the socket. If not it will return and
135 you will have to call loop_once() again to check if there is any data
136 waiting on the socket to be processed. In most cases you will have to
137 count on calling "loop_once" twice.
138 A code fragment like:
140 $ns->loop_once(10);
142 while( $ns->get_open_tcp() ){
143 $ns->loop_once(0);
144 }
145 Would wait for 10 seconds for the initial connection and would then
147 process all TCP sockets until none is left.
148 get_open_tcp
150 In scalar context returns the number of TCP connections for which state
151 is maintained. In array context it returns IO::Socket objects, these
152 could be useful for troubleshooting but be careful using them.
153
155 The following example will listen on port 5353 and respond to all
156 queries for A records with the IP address 10.1.2.3. All other queries
157 will be answered with NXDOMAIN. Authority and additional sections are
158 left empty. The $peerhost variable catches the IP address of the peer
159 host, so that additional filtering on its basis may be applied.
160 #!/usr/bin/perl
162 use strict;
164 use warnings;
165 use Net::DNS::Nameserver;
166 sub reply_handler {
168 my ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @_;
169 my ( $rcode, @ans, @auth, @add );
170 print "Received query from $peerhost to " . $conn->{sockhost} . "\n";
172 $query->print;
173 if ( $qtype eq "A" && $qname eq "foo.example.com" ) {
175 my ( $ttl, $rdata ) = ( 3600, "10.1.2.3" );
176 my $rr = Net::DNS::RR->new("$qname $ttl $qclass $qtype $rdata");
177 push @ans, $rr;
178 $rcode = "NOERROR";
179 } elsif ( $qname eq "foo.example.com" ) {
180 $rcode = "NOERROR";
181 } else {
183 $rcode = "NXDOMAIN";
184 }
185 # mark the answer as authoritative (by setting the 'aa' flag)
187 my $headermask = {aa => 1};
188 # specify EDNS options { option => value }
190 my $optionmask = {};
191 return ( $rcode, \@ans, \@auth, \@add, $headermask, $optionmask );
193 }
194 my $ns = Net::DNS::Nameserver->new(
197 LocalPort => 5353,
198 ReplyHandler => \&reply_handler,
199 Verbose => 1
200 ) || die "couldn't create nameserver object\n";
201 $ns->main_loop;
204
206 Limitations in perl make it impossible to guarantee that replies to UDP
207 queries from Net::DNS::Nameserver are sent from the IP-address to which
208 the query was directed. This is a problem for machines with multiple
209 IP-addresses and causes violation of RFC2181 section 4. Thus a UDP
210 socket created listening to INADDR_ANY (all available IP-addresses)
211 will reply not necessarily with the source address being the one to
212 which the request was sent, but rather with the address that the
213 operating system chooses. This is also often called "the closest
214 address". This should really only be a problem on a server which has
215 more than one IP-address (besides localhost - any experience with IPv6
216 complications here, would be nice). If this is a problem for you, a
217 work-around would be to not listen to INADDR_ANY but to specify each
218 address that you want this module to listen on. A separate set of
219 sockets will then be created for each IP-address.
220
222 Copyright (c)2000 Michael Fuhr.
223 Portions Copyright (c)2002-2004 Chris Reinhardt.
225 Portions Copyright (c)2005 Robert Martin-Legene.
227 Portions Copyright (c)2005-2009 O.M, Kolkman, RIPE NCC.
229 Portions Copyright (c)2017 Dick Franks.
231 All rights reserved.
233
235 Permission to use, copy, modify, and distribute this software and its
236 documentation for any purpose and without fee is hereby granted,
237 provided that the original copyright notices appear in all copies and
238 that both copyright notice and this permission notice appear in
239 supporting documentation, and that the name of the author not be used
240 in advertising or publicity pertaining to distribution of the software
241 without specific prior written permission.
242 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
244 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
245 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
246 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
247 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
248 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
249 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
250
252 perl, Net::DNS, Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Update,
253 Net::DNS::Header, Net::DNS::Question, Net::DNS::RR, RFC 1035
254perl v5.34.1 2022-06-08 Net::DNS::Nameserver(3)