{ "mode": "perldoc", "parameter": "Net::DNS::Nameserver", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/Net%3A%3ADNS%3A%3ANameserver/json", "generated": "2026-10-09T17:06:00Z", "synopsis": "use Net::DNS::Nameserver;\nmy $nameserver = Net::DNS::Nameserver->new(\nLocalAddr => ['::1', '127.0.0.1'],\nLocalPort => 15353,\nZoneFile => 'filename'\n);\nmy $nameserver = Net::DNS::Nameserver->new(\nLocalAddr => '10.1.2.3',\nLocalPort => 15353,\nReplyHandler => \\&replyhandler\n);\n$nameserver->startserver($timeout);\n$nameserver->stopserver;", "sections": { "NAME": { "content": "Net::DNS::Nameserver - DNS server class\n", "subsections": [] }, "SYNOPSIS": { "content": "use Net::DNS::Nameserver;\n\nmy $nameserver = Net::DNS::Nameserver->new(\nLocalAddr => ['::1', '127.0.0.1'],\nLocalPort => 15353,\nZoneFile => 'filename'\n);\n\nmy $nameserver = Net::DNS::Nameserver->new(\nLocalAddr => '10.1.2.3',\nLocalPort => 15353,\nReplyHandler => \\&replyhandler\n);\n\n$nameserver->startserver($timeout);\n$nameserver->stopserver;\n", "subsections": [] }, "DESCRIPTION": { "content": "Net::DNS::Nameserver offers a simple mechanism for instantiation of customised DNS server\nobjects intended to provide test responses to queries emanating from a client resolver.\n\nIt is not, nor will it ever be, a general-purpose DNS nameserver implementation.\n\nSee \"EXAMPLES\" below for further details.\n", "subsections": [] }, "METHODS": { "content": "new\n$nameserver = Net::DNS::Nameserver->new(\nLocalAddr => ['::1', '127.0.0.1'],\nLocalPort => 15353,\nZoneFile => \"filename\"\n);\n\n$nameserver = Net::DNS::Nameserver->new(\nLocalAddr => '10.1.2.3',\nLocalPort => 15353,\nReplyHandler => \\&replyhandler,\nVerbose => 1,\nTruncate => 0\n);\n\nInstantiates a Net::DNS::Nameserver object. An exception is raised if the object could not be\ncreated.\n\nEach instance is configured using the following optional arguments:\n\nLocalAddr IP address on which to listen Defaults to loopback address\nLocalPort Port on which to listen\nZoneFile Name of file containing RRs\naccessed using the internal\nreply-handling subroutine\nReplyHandler Reference to customised\nreply-handling subroutine\nNotifyHandler Reference to reply-handling\nsubroutine for queries with\nopcode NOTIFY (RFC1996)\nUpdateHandler Reference to reply-handling\nsubroutine for queries with\nopcode UPDATE (RFC2136)\nVerbose Report internal activity Defaults to 0 (off)\nTruncate Truncates UDP packets that\nare too big for the reply Defaults to 1 (on)\n\nThe LocalAddr attribute may alternatively be specified as an array of IP addresses to listen to.\n\nThe ReplyHandler subroutine is passed the query name, query class, query type, peerhost, query\nrecord, and connection descriptor. It must either return the response code and references to the\nanswer, authority, and additional sections of the response, or undef to leave the query\nunanswered. Common response codes are:\n\nNOERROR No error\nFORMERR Format error\nSERVFAIL Server failure\nNXDOMAIN Non-existent domain (name doesn't exist)\nNOTIMP Not implemented\nREFUSED Query refused\n\nFor advanced usage it may also contain a headermask containing an hashref with the settings for\nthe \"aa\", \"ra\", and \"ad\" header bits. The argument is of the form: {ad => 1, aa => 0, ra => 1}\n\nEDNS options may be specified in a similar manner using the optionmask: {$optioncode => $value,\n$optionname => $value}\n\nSee RFC1035 and IANA DNS parameters file for more information:\n\nThe nameserver will listen for both UDP and TCP connections. On linux and other Unix-like\nsystems, unprivileged users are denied access to ports below 1024.\n\nUDP reply truncation functionality was introduced in Net::DNS 0.66. The size limit is determined\nby the EDNS0 size advertised in the query, otherwise 512 is used. If you want to do packet\ntruncation yourself you should set Truncate=>0 and truncate the reply packet in the code of the\nReplyHandler.\n\nstartserver\n$ns->startserver( );\n\nStarts a server process for each of the specified UDP and TCP sockets which continuously\nresponds to user connections.\n\nThe timeout parameter specifies the time the server is to remain active. If called with no\nparameter a default timeout of 10 minutes is applied.\n\nstopserver\n$ns->stopserver();\n\nTerminates all server processes in an orderly fashion.\n", "subsections": [] }, "EXAMPLES": { "content": "", "subsections": [ { "name": "Example 1: Test script with embedded nameserver", "content": "The following example is a self-contained test script which queries DNS zonefile data served by\nan embedded Net::DNS::Nameserver instance.\n\nuse strict;\nuse warnings;\nuse Test::More;\n\nplan skipall => 'Net::DNS::Nameserver not available'\nunless eval { require Net::DNS::Nameserver }\nand Net::DNS::Nameserver->can('startserver');\nplan tests => 2;\n\nmy $resolver = Net::DNS::Resolver->new(\nnameserver => ['::1', '127.0.0.1'],\nport => 15353\n);\n\nmy $ns = Net::DNS::Nameserver->new(\nLocalAddr => [$resolver->nameserver],\nLocalPort => $resolver->port,\nVerbose => 0,\nZoneFile => \\*DATA\n)\n|| die \"couldn't create nameserver object\";\n\n$ns->startserver(10);\n\nmy $reply = $resolver->send(qw(example.com SOA));\nis( ref($reply), 'Net::DNS::Packet', 'received reply packet' );\nmy ($rr) = $reply->answer;\nis( $rr->type, 'SOA', 'answer contains SOA record' );\n\n$ns->stopserver();\n\nexit;\n\nDATA\n$ORIGIN example.com.\n@ IN SOA mname rname 2023 2h 1h 2w 1h\nwww IN A 93.184.216.34\n" }, { "name": "Example 2: Free-standing customised DNS nameserver", "content": "The following example will listen on port 15353 and respond to all queries for A records with\nthe IP address 10.1.2.3. All other queries will be answered with NXDOMAIN. Authority and\nadditional sections are left empty. The $peerhost variable catches the IP address of the peer\nhost, so that additional filtering on a per-host basis may be applied.\n\nuse strict;\nuse warnings;\nuse Net::DNS::Nameserver;\n\nsub replyhandler {\nmy ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @;\nmy ( $rcode, @ans, @auth, @add );\n\nprint \"Received query from $peerhost to \" . $conn->{sockhost} . \"\\n\";\n$query->print;\n\nif ( $qtype eq \"A\" && $qname eq \"foo.example.com\" ) {\nmy ( $ttl, $rdata ) = ( 3600, \"10.1.2.3\" );\nmy $rr = Net::DNS::RR->new(\"$qname $ttl $qclass $qtype $rdata\");\npush @ans, $rr;\n$rcode = \"NOERROR\";\n} elsif ( $qname eq \"foo.example.com\" ) {\n$rcode = \"NOERROR\";\n\n} else {\n$rcode = \"NXDOMAIN\";\n}\n\n# mark the answer as authoritative (by setting the 'aa' flag)\nmy $headermask = {aa => 1};\n\n# specify EDNS options { option => value }\nmy $optionmask = {};\n\nreturn ( $rcode, \\@ans, \\@auth, \\@add, $headermask, $optionmask );\n}\n\nmy $ns = Net::DNS::Nameserver->new(\nLocalPort => 15353,\nReplyHandler => \\&replyhandler,\nVerbose => 1\n) or die \"couldn't create nameserver object\";\n\n$ns->startserver(60);\n\nexit; # leaving nameserver processes running\n" } ] }, "BUGS": { "content": "Limitations in perl make it impossible to guarantee that replies to UDP queries from\nNet::DNS::Nameserver are sent from the IP-address to which the query was directed, the source\naddress being chosen by the operating system based upon its notion of \"closest address\". This\nlimitation is mitigated by creating a separate set of sockets and server subprocesses bound to\neach IP address.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c)2000 Michael Fuhr.\n\nPortions Copyright (c)2002-2004 Chris Reinhardt.\n\nPortions Copyright (c)2005 Robert Martin-Legene.\n\nPortions Copyright (c)2005-2009 O.M.Kolkman, RIPE NCC.\n\nPortions Copyright (c)2017-2024 R.W.Franks.\n\nAll rights reserved.\n", "subsections": [] }, "LICENSE": { "content": "Permission to use, copy, modify, and distribute this software and its documentation for any\npurpose and without fee is hereby granted, provided that the original copyright notices appear\nin all copies and that both copyright notice and this permission notice appear in supporting\ndocumentation, and that the name of the author not be used in advertising or publicity\npertaining to distribution of the software without specific prior written permission.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING\nBUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,\nDAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n", "subsections": [] }, "SEE ALSO": { "content": "perl Net::DNS Net::DNS::Resolver Net::DNS::Packet Net::DNS::Update Net::DNS::Header\nNet::DNS::Question Net::DNS::RR\n\nRFC1035 \n\nIANA DNS parameters \n", "subsections": [] } }, "summary": "Net::DNS::Nameserver - DNS server class", "flags": [], "examples": [ "The following example is a self-contained test script which queries DNS zonefile data served by", "an embedded Net::DNS::Nameserver instance.", "use strict;", "use warnings;", "use Test::More;", "plan skipall => 'Net::DNS::Nameserver not available'", "unless eval { require Net::DNS::Nameserver }", "and Net::DNS::Nameserver->can('startserver');", "plan tests => 2;", "my $resolver = Net::DNS::Resolver->new(", "nameserver => ['::1', '127.0.0.1'],", "port => 15353", ");", "my $ns = Net::DNS::Nameserver->new(", "LocalAddr => [$resolver->nameserver],", "LocalPort => $resolver->port,", "Verbose => 0,", "ZoneFile => \\*DATA", "|| die \"couldn't create nameserver object\";", "$ns->startserver(10);", "my $reply = $resolver->send(qw(example.com SOA));", "is( ref($reply), 'Net::DNS::Packet', 'received reply packet' );", "my ($rr) = $reply->answer;", "is( $rr->type, 'SOA', 'answer contains SOA record' );", "$ns->stopserver();", "exit;", "DATA", "$ORIGIN example.com.", "@ IN SOA mname rname 2023 2h 1h 2w 1h", "www IN A 93.184.216.34", "The following example will listen on port 15353 and respond to all queries for A records with", "the IP address 10.1.2.3. All other queries will be answered with NXDOMAIN. Authority and", "additional sections are left empty. The $peerhost variable catches the IP address of the peer", "host, so that additional filtering on a per-host basis may be applied.", "use strict;", "use warnings;", "use Net::DNS::Nameserver;", "sub replyhandler {", "my ( $qname, $qclass, $qtype, $peerhost, $query, $conn ) = @;", "my ( $rcode, @ans, @auth, @add );", "print \"Received query from $peerhost to \" . $conn->{sockhost} . \"\\n\";", "$query->print;", "if ( $qtype eq \"A\" && $qname eq \"foo.example.com\" ) {", "my ( $ttl, $rdata ) = ( 3600, \"10.1.2.3\" );", "my $rr = Net::DNS::RR->new(\"$qname $ttl $qclass $qtype $rdata\");", "push @ans, $rr;", "$rcode = \"NOERROR\";", "} elsif ( $qname eq \"foo.example.com\" ) {", "$rcode = \"NOERROR\";", "} else {", "$rcode = \"NXDOMAIN\";", "# mark the answer as authoritative (by setting the 'aa' flag)", "my $headermask = {aa => 1};", "# specify EDNS options { option => value }", "my $optionmask = {};", "return ( $rcode, \\@ans, \\@auth, \\@add, $headermask, $optionmask );", "my $ns = Net::DNS::Nameserver->new(", "LocalPort => 15353,", "ReplyHandler => \\&replyhandler,", "Verbose => 1", ") or die \"couldn't create nameserver object\";", "$ns->startserver(60);", "exit; # leaving nameserver processes running" ], "see_also": [] }