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
12 Instances of the "Net::DNS::Nameserver" class represent DNS server
13 objects. See "EXAMPLE" for an example.
14
16 new
17 my $ns = Net::DNS::Nameserver->new(
18 LocalAddr => "10.1.2.3",
19 LocalPort => "5353",
20 ReplyHandler => \&reply_handler,
21 Verbose => 1
22 );
23 my $ns = Net::DNS::Nameserver->new(
27 LocalAddr => ['::1' , '127.0.0.1' ],
28 LocalPort => "5353",
29 ReplyHandler => \&reply_handler,
30 Verbose => 1
31 );
32 Creates a nameserver object. Attributes are:
34 LocalAddr IP address on which to listen. Defaults to INADDR_ANY.
36 LocalPort Port on which to listen. Defaults to 53.
37 ReplyHandler Reference to reply-handling
38 subroutine Required.
39 NotifyHandler Reference to reply-handling
40 subroutine for queries with
41 opdcode NS_NOTIFY (RFC1996)
42 Verbose Print info about received
43 queries. Defaults to 0 (off).
44 The LocalAddr attribute may alternatively be specified as a list of IP
46 addresses to listen to.
47 If IO::Socket::INET6 and Socket6 are available on the system you can
49 also list IPv6 addresses and the default is '0' (listen on all
50 interfaces on IPv6 and IPv4);
51 The ReplyHandler subroutine is passed the query name, query class,
53 query type and optionally an argument containing the peerhost, the
54 incoming query, and the name of the incomming socket (sockethost). It
55 must return the response code and references to the answer, authority,
56 and additional sections of the response. Common response codes are:
57 NOERROR No error
59 FORMERR Format error
60 SERVFAIL Server failure
61 NXDOMAIN Non-existent domain (name doesn't exist)
62 NOTIMP Not implemented
63 REFUSED Query refused
64 For advanced usage it may also contain a headermaks containing an
66 hashref with the settings for the "aa", "ra", and "ad" header bits. The
67 argument is of the form "{ ad => 1, aa => 0, ra => 1 }".
68 See RFC 1035 and the IANA dns-parameters file for more information:
70 ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
72 http://www.isi.edu/in-notes/iana/assignments/dns-parameters
73 The nameserver will listen for both UDP and TCP connections. On Unix-
75 like systems, the program will probably have to run as root to listen
76 on the default port, 53. A non-privileged user should be able to
77 listen on ports 1024 and higher.
78 Returns a Net::DNS::Nameserver object, or undef if the object couldn't
80 be created.
81 See "EXAMPLE" for an example.
83 main_loop
85 $ns->main_loop;
86 Start accepting queries. Calling main_loop never returns.
88 loop_once
90 $ns->loop_once( [TIMEOUT_IN_SECONDS] );
91 Start accepting queries, but returns. If called without a parameter,
93 the call will not return until a request has been received (and replied
94 to). If called with a number, that number specifies how many seconds
95 (even fractional) to maximum wait before returning. If called with 0 it
96 will return immediately unless there's something to do.
97 Handling a request and replying obviously depends on the speed of
99 ReplyHandler. Assuming ReplyHandler is super fast, loop_once should
100 spend just a fraction of a second, if called with a timeout value of 0
101 seconds. One exception is when an AXFR has requested a huge amount of
102 data that the OS is not ready to receive in full. In that case, it will
103 keep running through a loop (while servicing new requests) until the
104 reply has been sent.
105 In case loop_once accepted a TCP connection it will immediatly check if
107 there is data to be read from the socket. If not it will return and you
108 will have to call loop_once() again to check if there is any data
109 waiting on the socket to be processed. In most cases you will have to
110 count on calling "loop_once" twice.
111 A code fragment like: $ns->loop_once(10);
113 while( $ns->get_open_tcp() ){ $ns->loop_once(0);
114 }
115 Would wait for 10 seconds for the initial connection and would then
117 process all TCP sockets until none is left.
118 get_open_tcp
120 In scalar context returns the number of TCP connections for which state
121 is maintained. In array context it returns IO::Socket objects, these
122 could be useful for troubleshooting but be careful using them.
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 its basis may be applied.
130 #!/usr/bin/perl
132 use Net::DNS::Nameserver;
134 use strict;
135 use warnings;
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" ) {
146 my ($ttl, $rdata) = (3600, "10.1.2.3");
147 push @ans, Net::DNS::RR->new("$qname $ttl $qclass $qtype $rdata");
148 $rcode = "NOERROR";
149 }elsif( $qname eq "foo.example.com" ) {
150 $rcode = "NOERROR";
151 }else{
153 $rcode = "NXDOMAIN";
154 }
155 # mark the answer as authoritive (by setting the 'aa' flag
158 return ($rcode, \@ans, \@auth, \@add, { aa => 1 });
159 }
160 my $ns = Net::DNS::Nameserver->new(
162 LocalPort => 5353,
163 ReplyHandler => \&reply_handler,
164 Verbose => 1,
165 ) || die "couldn't create nameserver object\n";
166 $ns->main_loop;
168
170 Limitations in perl 5.8.6 makes it impossible to guarantee that replies
171 to UDP queries from Net::DNS::Nameserver are sent from the IP-address
172 they were received on. This is a problem for machines with multiple IP-
173 addresses and causes violation of RFC2181 section 4. Thus a UDP socket
174 created listening to INADDR_ANY (all available IP-addresses) will reply
175 not necessarily with the source address being the one to which the
176 request was sent, but rather with the address that the operating system
177 choses. This is also often called "the closest address". This should
178 really only be a problem on a server which has more than one IP-address
179 (besides localhost - any experience with IPv6 complications here, would
180 be nice). If this is a problem for you, a work-around would be to not
181 listen to INADDR_ANY but to specify each address that you want this
182 module to listen on. A seperate set of sockets will then be created for
183 each IP-address.
184
186 Copyright (c) 1997-2002 Michael Fuhr.
187 Portions Copyright (c) 2002-2004 Chris Reinhardt.
189 Portions Copyright (c) 2005-2007 O.M, Kolkman, RIPE NCC.
191 Portions Copyright (c) 2005 Robert Martin-Legene.
193 All rights reserved. This program is free software; you may
195 redistribute it and/or modify it under the same terms as Perl itself.
196
198 perl(1), Net::DNS, Net::DNS::Resolver, Net::DNS::Packet,
199 Net::DNS::Update, Net::DNS::Header, Net::DNS::Question, Net::DNS::RR,
200 RFC 1035
201perl v5.12.0 2009-01-26 Net::DNS::Nameserver(3)