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 $nameserver = new Net::DNS::Nameserver(
12 LocalAddr => ['::1' , '127.0.0.1' ],
13 LocalPort => "5353",
14 ReplyHandler => \&reply_handler,
15 Verbose => 1,
16 Truncate => 0
17 );
18
20 Instances of the "Net::DNS::Nameserver" class represent DNS server
21 objects. See "EXAMPLE" for an example.
22
24 new
25 my $ns = new Net::DNS::Nameserver(
26 LocalAddr => "10.1.2.3",
27 LocalPort => "5353",
28 ReplyHandler => \&reply_handler,
29 Verbose => 1
30 );
31 my $ns = new Net::DNS::Nameserver(
35 LocalAddr => ['::1' , '127.0.0.1' ],
36 LocalPort => "5353",
37 ReplyHandler => \&reply_handler,
38 Verbose => 1,
39 Truncate => 0
40 );
41 Creates a nameserver object. Attributes are:
43 LocalAddr IP address on which to listen. Defaults to INADDR_ANY.
45 LocalPort Port on which to listen. Defaults to 53.
46 ReplyHandler Reference to reply-handling
47 subroutine Required.
48 NotifyHandler Reference to reply-handling
49 subroutine for queries with
50 opcode NOTIFY (RFC1996)
51 Verbose Print info about received
52 queries. Defaults to 0 (off).
53 Truncate Truncates UDP packets that
54 are too big for the reply Defaults to 1 (on)
55 IdleTimeout TCP clients are disconnected
56 if they are idle longer than
57 this duration. Defaults to 120 (secs)
58 The LocalAddr attribute may alternatively be specified as a list of IP
60 addresses to listen to.
61 If IO::Socket::INET6 and Socket6 are available on the system you can
63 also list IPv6 addresses and the default is '0' (listen on all
64 interfaces on IPv6 and IPv4);
65 The ReplyHandler subroutine is passed the query name, query class,
67 query type and optionally an argument containing the peerhost, the
68 incoming query, and the name of the incoming socket (sockethost). It
69 must either return the response code and references to the answer,
70 authority, and additional sections of the response, or undef to leave
71 the query unanswered. Common response codes are:
72 NOERROR No error
74 FORMERR Format error
75 SERVFAIL Server failure
76 NXDOMAIN Non-existent domain (name doesn't exist)
77 NOTIMP Not implemented
78 REFUSED Query refused
79 For advanced usage it may also contain a headermask containing an
81 hashref with the settings for the "aa", "ra", and "ad" header bits. The
82 argument is of the form "{ ad => 1, aa => 0, ra => 1 }".
83 See RFC 1035 and the IANA dns-parameters file for more information:
85 ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
87 http://www.isi.edu/in-notes/iana/assignments/dns-parameters
88 The nameserver will listen for both UDP and TCP connections. On Unix-
90 like systems, the program will probably have to run as root to listen
91 on the default port, 53. A non-privileged user should be able to
92 listen on ports 1024 and higher.
93 Packet Truncation is new functionality for
95 $Net::DNS::Nameserver::VERSION>830 and uses the
96 Net::DNS::Packet::truncate method with a size determinde by the
97 advertised EDNS0 size in the query, or 512 if EDNS0 is not advertised
98 in the query. Only UDP replies are truncated. If you want to do packet
99 runcation yourself you should set Truncate to 0 and use the truncate
100 method on the reply packet in the code you use for the ReplyHandler.
101 Returns a Net::DNS::Nameserver object, or undef if the object couldn't
103 be created.
104 See "EXAMPLE" for an example.
106 main_loop
108 $ns->main_loop;
109 Start accepting queries. Calling main_loop never returns.
111 loop_once
113 $ns->loop_once( [TIMEOUT_IN_SECONDS] );
114 Start accepting queries, but returns. If called without a parameter,
116 the call will not return until a request has been received (and replied
117 to). If called with a number, that number specifies how many seconds
118 (even fractional) to maximum wait before returning. If called with 0 it
119 will return immediately unless there's something to do.
120 Handling a request and replying obviously depends on the speed of
122 ReplyHandler. Assuming ReplyHandler is super fast, loop_once should
123 spend just a fraction of a second, if called with a timeout value of 0
124 seconds. One exception is when an AXFR has requested a huge amount of
125 data that the OS is not ready to receive in full. In that case, it will
126 keep running through a loop (while servicing new requests) until the
127 reply has been sent.
128 In case loop_once accepted a TCP connection it will immediatly check if
130 there is data to be read from the socket. If not it will return and you
131 will have to call loop_once() again to check if there is any data
132 waiting on the socket to be processed. In most cases you will have to
133 count on calling "loop_once" twice.
134 A code fragment like:
136 $ns->loop_once(10);
138 while( $ns->get_open_tcp() ){
139 $ns->loop_once(0);
140 }
141 Would wait for 10 seconds for the initial connection and would then
143 process all TCP sockets until none is left.
144 get_open_tcp
146 In scalar context returns the number of TCP connections for which state
147 is maintained. In array context it returns IO::Socket objects, these
148 could be useful for troubleshooting but be careful using them.
149
151 The following example will listen on port 5353 and respond to all
152 queries for A records with the IP address 10.1.2.3. All other queries
153 will be answered with NXDOMAIN. Authority and additional sections are
154 left empty. The $peerhost variable catches the IP address of the peer
155 host, so that additional filtering on its basis may be applied.
156 #!/usr/bin/perl
158 use strict;
160 use warnings;
161 use Net::DNS::Nameserver;
162 sub reply_handler {
164 my ($qname, $qclass, $qtype, $peerhost,$query,$conn) = @_;
165 my ($rcode, @ans, @auth, @add);
166 print "Received query from $peerhost to ". $conn->{sockhost}. "\n";
168 $query->print;
169 if ($qtype eq "A" && $qname eq "foo.example.com" ) {
171 my ($ttl, $rdata) = (3600, "10.1.2.3");
172 my $rr = new Net::DNS::RR("$qname $ttl $qclass $qtype $rdata");
173 push @ans, $rr;
174 $rcode = "NOERROR";
175 }elsif( $qname eq "foo.example.com" ) {
176 $rcode = "NOERROR";
177 }else{
179 $rcode = "NXDOMAIN";
180 }
181 # mark the answer as authoritive (by setting the 'aa' flag
183 return ($rcode, \@ans, \@auth, \@add, { aa => 1 });
184 }
185 my $ns = new Net::DNS::Nameserver(
187 LocalPort => 5353,
188 ReplyHandler => \&reply_handler,
189 Verbose => 1
190 ) || die "couldn't create nameserver object\n";
191 $ns->main_loop;
193
195 Limitations in perl 5.8.6 makes it impossible to guarantee that replies
196 to UDP queries from Net::DNS::Nameserver are sent from the IP-address
197 they were received on. This is a problem for machines with multiple IP-
198 addresses and causes violation of RFC2181 section 4. Thus a UDP socket
199 created listening to INADDR_ANY (all available IP-addresses) will reply
200 not necessarily with the source address being the one to which the
201 request was sent, but rather with the address that the operating system
202 chooses. This is also often called "the closest address". This should
203 really only be a problem on a server which has more than one IP-address
204 (besides localhost - any experience with IPv6 complications here, would
205 be nice). If this is a problem for you, a work-around would be to not
206 listen to INADDR_ANY but to specify each address that you want this
207 module to listen on. A separate set of sockets will then be created for
208 each IP-address.
209
211 Copyright (c)1997-2002 Michael Fuhr.
212 Portions Copyright (c)2002-2004 Chris Reinhardt.
214 Portions Copyright (c)2005-2009 O.M, Kolkman, RIPE NCC.
216 Portions Copyright (c)2005 Robert Martin-Legene.
218 All rights reserved.
220 This program is free software; you may redistribute it and/or modify it
222 under the same terms as Perl itself.
223
225 perl, Net::DNS, Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Update,
226 Net::DNS::Header, Net::DNS::Question, Net::DNS::RR, RFC 1035
227perl v5.16.3 2012-12-28 Net::DNS::Nameserver(3)