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 Instantiates a Net::DNS::Nameserver object. An exception is raised if
48 the object could not 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 internal
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 an array of
73 IP addresses to listen to.
74 The ReplyHandler subroutine is passed the query name, query class,
76 query type, peerhost, query record, and connection descriptor. It must
77 either return the response code and references to the answer,
78 authority, and additional sections of the response, or undef to leave
79 the query unanswered. Common response codes are:
80 NOERROR No error
82 FORMERR Format error
83 SERVFAIL Server failure
84 NXDOMAIN Non-existent domain (name doesn't exist)
85 NOTIMP Not implemented
86 REFUSED Query refused
87 For advanced usage it may also contain a headermask containing an
89 hashref with the settings for the "aa", "ra", and "ad" header bits. The
90 argument is of the form: {ad => 1, aa => 0, ra => 1}
91 EDNS options may be specified in a similar manner using the optionmask:
93 {$optioncode => $value, $optionname => $value}
94 See RFC1035 and IANA DNS parameters file for more information:
96 The nameserver will listen for both UDP and TCP connections. On Unix-
98 like systems, unprivileged users are denied access to ports below 1024.
99 UDP reply truncation functionality was introduced in VERSION 830. The
101 size limit is determined by the EDNS0 size advertised in the query,
102 otherwise 512 is used. If you want to do packet truncation yourself
103 you should set "Truncate" to 0 and truncate the reply packet in the
104 code of the ReplyHandler.
105 See "EXAMPLE" for an example.
107 main_loop
109 $ns->main_loop;
110 Start accepting queries. Calling main_loop never returns.
112 loop_once
114 $ns->loop_once( [TIMEOUT_IN_SECONDS] );
115 Initialises the specified UDP and TCP sockets and starts the server
117 which will respond to a single connection on each socket.
118 The timeout parameter specifies the maximum time to wait for a request.
120 If called without parameters a default timeout of 10 minutes is
121 applied. If called with a zero parameter, the timeout function is
122 disabled.
123
125 The following example will listen on port 5353 and respond to all
126 queries for A records with the IP address 10.1.2.3. All other queries
127 will be answered with NXDOMAIN. Authority and additional sections are
128 left empty. The $peerhost variable catches the IP address of the peer
129 host, so that additional filtering on a per-host basis may be applied.
130 #!/usr/bin/perl -T
132 use strict;
134 use warnings;
135 use Net::DNS::Nameserver;
136 sub reply_handler {
138 my ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @_;
139 my ( $rcode, @ans, @auth, @add );
140 print "Received query from $peerhost to " . $conn->{sockhost} . "\n";
142 $query->print;
143 if ( $qtype eq "A" && $qname eq "foo.example.com" ) {
145 my ( $ttl, $rdata ) = ( 3600, "10.1.2.3" );
146 my $rr = Net::DNS::RR->new("$qname $ttl $qclass $qtype $rdata");
147 push @ans, $rr;
148 $rcode = "NOERROR";
149 } elsif ( $qname eq "foo.example.com" ) {
150 $rcode = "NOERROR";
151 } else {
153 $rcode = "NXDOMAIN";
154 }
155 # mark the answer as authoritative (by setting the 'aa' flag)
157 my $headermask = {aa => 1};
158 # specify EDNS options { option => value }
160 my $optionmask = {};
161 return ( $rcode, \@ans, \@auth, \@add, $headermask, $optionmask );
163 }
164 my $ns = Net::DNS::Nameserver->new(
167 LocalPort => 5353,
168 ReplyHandler => \&reply_handler,
169 Verbose => 1
170 ) || die "couldn't create nameserver object\n";
171 $ns->main_loop;
174 exit;
176
178 Limitations in perl make it impossible to guarantee that replies to UDP
179 queries from Net::DNS::Nameserver are sent from the IP-address to which
180 the query was directed. This is a problem for machines with multiple
181 IP-addresses and causes violation of RFC2181 section 4. Thus a UDP
182 socket created listening to INADDR_ANY (all available IP-addresses)
183 will reply not necessarily with the source address being the one to
184 which the request was sent, but rather with the address that the
185 operating system chooses. This is also often called "the closest
186 address". This should really only be a problem on a server which has
187 more than one IP-address (besides localhost - any experience with IPv6
188 complications here, would be nice). If this is a problem for you, a
189 work-around would be to not listen to INADDR_ANY but to specify each
190 address that you want this module to listen on. A separate set of
191 sockets will then be created for each IP-address.
192
194 Copyright (c)2000 Michael Fuhr.
195 Portions Copyright (c)2002-2004 Chris Reinhardt.
197 Portions Copyright (c)2005 Robert Martin-Legene.
199 Portions Copyright (c)2005-2009 O.M.Kolkman, RIPE NCC.
201 Portions Copyright (c)2017,2023 R.W.Franks.
203 All rights reserved.
205
207 Permission to use, copy, modify, and distribute this software and its
208 documentation for any purpose and without fee is hereby granted,
209 provided that the original copyright notices appear in all copies and
210 that both copyright notice and this permission notice appear in
211 supporting documentation, and that the name of the author not be used
212 in advertising or publicity pertaining to distribution of the software
213 without specific prior written permission.
214 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
216 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
217 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
218 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
219 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
220 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
221 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
222
224 perl Net::DNS Net::DNS::Resolver Net::DNS::Packet Net::DNS::Update
225 Net::DNS::Header Net::DNS::Question Net::DNS::RR
226 RFC1035 <https://tools.ietf.org/html/rfc1035>
228 IANA DNS parameters <http://www.iana.org/assignments/dns-parameters>
230perl v5.36.1 2023-06-01 Net::DNS::Nameserver(3)