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 = new Net::DNS::Nameserver(
12 LocalAddr => ['::1' , '127.0.0.1'],
13 ZoneFile => "filename"
14 );
15 my $nameserver = new Net::DNS::Nameserver(
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 = new Net::DNS::Nameserver(
35 LocalAddr => ['::1' , '127.0.0.1'],
36 ZoneFile => "filename"
37 );
38 $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 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 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 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, 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 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 See "EXAMPLE" for an example.
114 main_loop
116 $ns->main_loop;
117 Start accepting queries. Calling main_loop never returns.
119 loop_once
121 $ns->loop_once( [TIMEOUT_IN_SECONDS] );
122 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 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 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 A code fragment like:
143 $ns->loop_once(10);
145 while( $ns->get_open_tcp() ){
146 $ns->loop_once(0);
147 }
148 Would wait for 10 seconds for the initial connection and would then
150 process all TCP sockets until none is left.
151 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
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 #!/usr/bin/perl
165 use strict;
167 use warnings;
168 use Net::DNS::Nameserver;
169 sub reply_handler {
171 my ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @_;
172 my ( $rcode, @ans, @auth, @add );
173 print "Received query from $peerhost to " . $conn->{sockhost} . "\n";
175 $query->print;
176 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 } else {
186 $rcode = "NXDOMAIN";
187 }
188 # mark the answer as authoritative (by setting the 'aa' flag)
190 my $headermask = {aa => 1};
191 # specify EDNS options { option => value }
193 my $optionmask = {};
194 return ( $rcode, \@ans, \@auth, \@add, $headermask, $optionmask );
196 }
197 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 $ns->main_loop;
207
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 Portions Copyright (c)2002-2004 Chris Reinhardt.
228 Portions Copyright (c)2005 Robert Martin-Legene.
230 Portions Copyright (c)2005-2009 O.M, Kolkman, RIPE NCC.
232 Portions Copyright (c)2017 Dick Franks.
234 All rights reserved.
236
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 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
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
257perl v5.30.1 2020-01-30 Net::DNS::Nameserver(3)