1Net::DNS::Nameserver(3)User Contributed Perl DocumentatioNnet::DNS::Nameserver(3)
2
3
4

NAME

6       Net::DNS::Nameserver - DNS server class
7

SYNOPSIS

9       "use Net::DNS::Nameserver;"
10

DESCRIPTION

12       Instances of the "Net::DNS::Nameserver" class represent DNS server
13       objects.  See "EXAMPLE" for an example.
14

METHODS

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
24
25
26        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
33       Creates a nameserver object.  Attributes are:
34
35         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
45       The LocalAddr attribute may alternatively be specified as a list of IP
46       addresses to listen to.
47
48       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
52       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
58         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
65       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
69       See RFC 1035 and the IANA dns-parameters file for more information:
70
71         ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
72         http://www.isi.edu/in-notes/iana/assignments/dns-parameters
73
74       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
79       Returns a Net::DNS::Nameserver object, or undef if the object couldn't
80       be created.
81
82       See "EXAMPLE" for an example.
83
84   main_loop
85               $ns->main_loop;
86
87       Start accepting queries. Calling main_loop never returns.
88
89   loop_once
90               $ns->loop_once( [TIMEOUT_IN_SECONDS] );
91
92       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
98       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
106       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
112       A code fragment like:      $ns->loop_once(10);
113               while( $ns->get_open_tcp() ){            $ns->loop_once(0);
114            }
115
116       Would wait for 10 seconds for the initial connection and would then
117       process all TCP sockets until none is left.
118
119   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

EXAMPLE

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
131        #!/usr/bin/perl
132
133        use Net::DNS::Nameserver;
134        use strict;
135        use warnings;
136
137        sub reply_handler {
138                my ($qname, $qclass, $qtype, $peerhost,$query,$conn) = @_;
139                my ($rcode, @ans, @auth, @add);
140
141                print "Received query from $peerhost to ". $conn->{"sockhost"}. "\n";
142                $query->print;
143
144
145                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
152                }else{
153                         $rcode = "NXDOMAIN";
154                }
155
156
157                # mark the answer as authoritive (by setting the 'aa' flag
158                return ($rcode, \@ans, \@auth, \@add, { aa => 1 });
159        }
160
161        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
167        $ns->main_loop;
168

BUGS

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
188       Portions Copyright (c) 2002-2004 Chris Reinhardt.
189
190       Portions Copyright (c) 2005-2007 O.M, Kolkman, RIPE NCC.
191
192       Portions Copyright (c) 2005 Robert Martin-Legene.
193
194       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

SEE ALSO

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
201
202
203
204perl v5.12.0                      2009-01-26           Net::DNS::Nameserver(3)
Impressum