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 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 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 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 EDNS options may be specified in a similar manner using optionmask "{
95 $optioncode => $value, $optionname => $value }".
96 See RFC 1035 and the IANA dns-parameters file for more information:
98 ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
100 http://www.isi.edu/in-notes/iana/assignments/dns-parameters
101 The nameserver will listen for both UDP and TCP connections. On Unix-
103 like systems, unprivileged users are denied access to ports below 1024.
104 UDP reply truncation functionality was introduced in VERSION 830. The
106 size limit is determined by the EDNS0 size advertised in the query,
107 otherwise 512 is used. If you want to do packet truncation yourself
108 you should set "Truncate" to 0 and truncate the reply packet in the
109 code of the ReplyHandler.
110 See "EXAMPLE" for an example.
112 main_loop
114 $ns->main_loop;
115 Start accepting queries. Calling main_loop never returns.
117 loop_once
119 $ns->loop_once( [TIMEOUT_IN_SECONDS] );
120 Start accepting queries, but returns. If called without a parameter,
122 the call will not return until a request has been received (and replied
123 to). Otherwise, the parameter specifies the maximum time to wait for a
124 request. A zero timeout forces an immediate return if there is nothing
125 to do.
126 Handling a request and replying obviously depends on the speed of
128 ReplyHandler. Assuming a fast ReplyHandler, loop_once should spend just
129 a fraction of a second, if called with a timeout value of 0.0 seconds.
130 One exception is when an AXFR has requested a huge amount of data that
131 the OS is not ready to receive in full. In that case, it will remain in
132 a loop (while servicing new requests) until the reply has been sent.
133 In case loop_once accepted a TCP connection it will immediately check
135 if there is data to be read from the socket. If not it will return and
136 you will have to call loop_once() again to check if there is any data
137 waiting on the socket to be processed. In most cases you will have to
138 count on calling "loop_once" twice.
139 A code fragment like:
141 $ns->loop_once(10);
143 while( $ns->get_open_tcp() ){
144 $ns->loop_once(0);
145 }
146 Would wait for 10 seconds for the initial connection and would then
148 process all TCP sockets until none is left.
149 get_open_tcp
151 In scalar context returns the number of TCP connections for which state
152 is maintained. In array context it returns IO::Socket objects, these
153 could be useful for troubleshooting but be careful using them.
154
156 The following example will listen on port 5353 and respond to all
157 queries for A records with the IP address 10.1.2.3. All other queries
158 will be answered with NXDOMAIN. Authority and additional sections are
159 left empty. The $peerhost variable catches the IP address of the peer
160 host, so that additional filtering on its basis may be applied.
161 #!/usr/bin/perl
163 use strict;
165 use warnings;
166 use Net::DNS::Nameserver;
167 sub reply_handler {
169 my ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @_;
170 my ( $rcode, @ans, @auth, @add );
171 print "Received query from $peerhost to " . $conn->{sockhost} . "\n";
173 $query->print;
174 if ( $qtype eq "A" && $qname eq "foo.example.com" ) {
176 my ( $ttl, $rdata ) = ( 3600, "10.1.2.3" );
177 my $rr = Net::DNS::RR->new("$qname $ttl $qclass $qtype $rdata");
178 push @ans, $rr;
179 $rcode = "NOERROR";
180 } elsif ( $qname eq "foo.example.com" ) {
181 $rcode = "NOERROR";
182 } else {
184 $rcode = "NXDOMAIN";
185 }
186 # mark the answer as authoritative (by setting the 'aa' flag)
188 my $headermask = {aa => 1};
189 # specify EDNS options { option => value }
191 my $optionmask = {};
192 return ( $rcode, \@ans, \@auth, \@add, $headermask, $optionmask );
194 }
195 my $ns = Net::DNS::Nameserver->new(
198 LocalPort => 5353,
199 ReplyHandler => \&reply_handler,
200 Verbose => 1
201 ) || die "couldn't create nameserver object\n";
202 $ns->main_loop;
205
207 Limitations in perl make it impossible to guarantee that replies to UDP
208 queries from Net::DNS::Nameserver are sent from the IP-address to which
209 the query was directed. This is a problem for machines with multiple
210 IP-addresses and causes violation of RFC2181 section 4. Thus a UDP
211 socket created listening to INADDR_ANY (all available IP-addresses)
212 will reply not necessarily with the source address being the one to
213 which the request was sent, but rather with the address that the
214 operating system chooses. This is also often called "the closest
215 address". This should really only be a problem on a server which has
216 more than one IP-address (besides localhost - any experience with IPv6
217 complications here, would be nice). If this is a problem for you, a
218 work-around would be to not listen to INADDR_ANY but to specify each
219 address that you want this module to listen on. A separate set of
220 sockets will then be created for each IP-address.
221
223 Copyright (c)2000 Michael Fuhr.
224 Portions Copyright (c)2002-2004 Chris Reinhardt.
226 Portions Copyright (c)2005 Robert Martin-Legene.
228 Portions Copyright (c)2005-2009 O.M, Kolkman, RIPE NCC.
230 Portions Copyright (c)2017 Dick Franks.
232 All rights reserved.
234
236 Permission to use, copy, modify, and distribute this software and its
237 documentation for any purpose and without fee is hereby granted,
238 provided that the above copyright notice appear in all copies and that
239 both that copyright notice and this permission notice appear in
240 supporting documentation, and that the name of the author not be used
241 in advertising or publicity pertaining to distribution of the software
242 without specific prior written permission.
243 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
245 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
246 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
247 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
248 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
249 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
250 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
251
253 perl, Net::DNS, Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Update,
254 Net::DNS::Header, Net::DNS::Question, Net::DNS::RR, RFC 1035
255perl v5.34.0 2021-07-22 Net::DNS::Nameserver(3)