"Fossies" - the Fresh Open Source Software Archive

Member "Net-DNS-1.27/lib/Net/DNS.pm" (11 Sep 2020, 15947 Bytes) of package /linux/misc/dns/Net-DNS-1.27.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "DNS.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.26_02_vs_1.27.

    1 package Net::DNS;
    2 
    3 #
    4 # $Id: DNS.pm 1806 2020-09-11 18:48:57Z willem $
    5 #
    6 require 5.006;
    7 our $VERSION;
    8 $VERSION = '1.27';
    9 $VERSION = eval $VERSION;
   10 our $SVNVERSION = (qw$LastChangedRevision: 1806 $)[1];
   11 
   12 
   13 =head1 NAME
   14 
   15 Net::DNS - Perl Interface to the Domain Name System
   16 
   17 =head1 SYNOPSIS
   18 
   19     use Net::DNS;
   20 
   21 =head1 DESCRIPTION
   22 
   23 Net::DNS is a collection of Perl modules that act as a Domain Name System
   24 (DNS) resolver. It allows the programmer to perform DNS queries that are
   25 beyond the capabilities of "gethostbyname" and "gethostbyaddr".
   26 
   27 The programmer should be familiar with the structure of a DNS packet.
   28 See RFC 1035 or DNS and BIND (Albitz & Liu) for details.
   29 
   30 =cut
   31 
   32 
   33 use strict;
   34 use warnings;
   35 use integer;
   36 
   37 use base qw(Exporter);
   38 our @EXPORT = qw(SEQUENTIAL UNIXTIME YYYYMMDDxx
   39         yxrrset nxrrset yxdomain nxdomain rr_add rr_del
   40         mx rr rrsort);
   41 
   42 
   43 local $SIG{__DIE__};
   44 require Net::DNS::Resolver;
   45 require Net::DNS::Packet;
   46 require Net::DNS::RR;
   47 require Net::DNS::Update;
   48 
   49 
   50 sub version { $VERSION; }
   51 
   52 
   53 #
   54 # rr()
   55 #
   56 # Usage:
   57 #   @rr = rr('example.com');
   58 #   @rr = rr('example.com', 'A', 'IN');
   59 #   @rr = rr($res, 'example.com' ... );
   60 #
   61 sub rr {
   62     my ($arg1) = @_;
   63     my $res = ref($arg1) ? shift : new Net::DNS::Resolver();
   64 
   65     my $reply = $res->query(@_);
   66     my @list = $reply ? $reply->answer : ();
   67 }
   68 
   69 
   70 #
   71 # mx()
   72 #
   73 # Usage:
   74 #   @mx = mx('example.com');
   75 #   @mx = mx($res, 'example.com');
   76 #
   77 sub mx {
   78     my ($arg1) = @_;
   79     my @res = ( ref($arg1) ? shift : () );
   80     my ( $name, @class ) = @_;
   81 
   82     # This construct is best read backwards.
   83     #
   84     # First we take the answer section of the packet.
   85     # Then we take just the MX records from that list
   86     # Then we sort the list by preference
   87     # We do this into an array to force list context.
   88     # Then we return the list.
   89 
   90     my @list = sort { $a->preference <=> $b->preference }
   91             grep $_->type eq 'MX', &rr( @res, $name, 'MX', @class );
   92     return @list;
   93 }
   94 
   95 
   96 #
   97 # rrsort()
   98 #
   99 # Usage:
  100 #    @prioritysorted = rrsort( "SRV", "priority", @rr_array );
  101 #
  102 sub rrsort {
  103     my $rrtype = uc shift;
  104     my ( $attribute, @rr ) = @_;    ## NB: attribute is optional
  105     ( @rr, $attribute ) = @_ if ref($attribute) =~ /^Net::DNS::RR/;
  106 
  107     my @extracted = grep $_->type eq $rrtype, @rr;
  108     return @extracted unless scalar @extracted;
  109     my $func   = "Net::DNS::RR::$rrtype"->get_rrsort_func($attribute);
  110     my @sorted = sort $func @extracted;
  111 }
  112 
  113 
  114 #
  115 # Auxiliary functions to support policy-driven zone serial numbering.
  116 #
  117 #   $successor = $soa->serial(SEQUENTIAL);
  118 #   $successor = $soa->serial(UNIXTIME);
  119 #   $successor = $soa->serial(YYYYMMDDxx);
  120 #
  121 
  122 sub SEQUENTIAL {undef}
  123 
  124 sub UNIXTIME { return CORE::time; }
  125 
  126 sub YYYYMMDDxx {
  127     my ( $dd, $mm, $yy ) = (localtime)[3 .. 5];
  128     return 1900010000 + sprintf '%d%0.2d%0.2d00', $yy, $mm, $dd;
  129 }
  130 
  131 
  132 #
  133 # Auxiliary functions to support dynamic update.
  134 #
  135 
  136 sub yxrrset {
  137     my $rr = new Net::DNS::RR(@_);
  138     $rr->ttl(0);
  139     $rr->class('ANY') unless $rr->rdata;
  140     return $rr;
  141 }
  142 
  143 sub nxrrset {
  144     my $rr = new Net::DNS::RR(@_);
  145     new Net::DNS::RR(
  146         name  => $rr->name,
  147         type  => $rr->type,
  148         class => 'NONE'
  149         );
  150 }
  151 
  152 sub yxdomain {
  153     my ( $domain, @etc ) = map split, @_;
  154     my $rr = new Net::DNS::RR( scalar(@etc) ? @_ : ( name => $domain ) );
  155     new Net::DNS::RR(
  156         name  => $rr->name,
  157         type  => 'ANY',
  158         class => 'ANY'
  159         );
  160 }
  161 
  162 sub nxdomain {
  163     my ( $domain, @etc ) = map split, @_;
  164     my $rr = new Net::DNS::RR( scalar(@etc) ? @_ : ( name => $domain ) );
  165     new Net::DNS::RR(
  166         name  => $rr->name,
  167         type  => 'ANY',
  168         class => 'NONE'
  169         );
  170 }
  171 
  172 sub rr_add {
  173     my $rr = new Net::DNS::RR(@_);
  174     $rr->{ttl} = 86400 unless defined $rr->{ttl};
  175     return $rr;
  176 }
  177 
  178 sub rr_del {
  179     my ( $domain, @etc ) = map split, @_;
  180     my $rr = new Net::DNS::RR( scalar(@etc) ? @_ : ( name => $domain, type => 'ANY' ) );
  181     $rr->class( $rr->rdata ? 'NONE' : 'ANY' );
  182     $rr->ttl(0);
  183     return $rr;
  184 }
  185 
  186 
  187 1;
  188 __END__
  189 
  190 
  191 
  192 =head2 Resolver Objects
  193 
  194 A resolver object is an instance of the L<Net::DNS::Resolver> class.
  195 A program may have multiple resolver objects, each maintaining its
  196 own state information such as the nameservers to be queried, whether
  197 recursion is desired, etc.
  198 
  199 
  200 =head2 Packet Objects
  201 
  202 L<Net::DNS::Resolver> queries return L<Net::DNS::Packet> objects.
  203 A packet object has five sections:
  204 
  205 =over 3
  206 
  207 =item *
  208 
  209 header, represented by a L<Net::DNS::Header> object
  210 
  211 =item *
  212 
  213 question, a list of no more than one L<Net::DNS::Question> object
  214 
  215 =item *
  216 
  217 answer, a list of L<Net::DNS::RR> objects
  218 
  219 =item *
  220 
  221 authority, a list of L<Net::DNS::RR> objects
  222 
  223 =item *
  224 
  225 additional, a list of L<Net::DNS::RR> objects
  226 
  227 =back
  228 
  229 =head2 Update Objects
  230 
  231 L<Net::DNS::Update> is a subclass of L<Net::DNS::Packet>
  232 used to create dynamic update requests.
  233 
  234 
  235 =head2 Header Object
  236 
  237 The L<Net::DNS::Header> object mediates access to the header data
  238 which resides within the corresponding L<Net::DNS::Packet>.
  239 
  240 =head2 Question Object
  241 
  242 The L<Net::DNS::Question> object represents the content of the question
  243 section of the DNS packet.
  244 
  245 =head2 RR Objects
  246 
  247 L<Net::DNS::RR> is the base class for DNS resource record (RR) objects
  248 in the answer, authority, and additional sections of a DNS packet.
  249 
  250 Do not assume that RR objects will be of the type requested.
  251 The type of an RR object must be checked before calling any methods.
  252 
  253 
  254 =head1 METHODS
  255 
  256 Net::DNS exports methods and auxiliary functions to support
  257 DNS updates, zone serial number management, and simple DNS queries.
  258 
  259 =head2 version
  260 
  261     use Net::DNS;
  262     print Net::DNS->version, "\n";
  263 
  264 Returns the version of Net::DNS.
  265 
  266 
  267 =head2 rr
  268 
  269     # Use a default resolver -- can not get an error string this way.
  270     use Net::DNS;
  271     my @rr = rr("example.com");
  272     my @rr = rr("example.com", "AAAA");
  273     my @rr = rr("example.com", "AAAA", "IN");
  274 
  275     # Use your own resolver object.
  276     my $res = Net::DNS::Resolver->new;
  277     my @rr  = rr($res, "example.com" ... );
  278 
  279     my ($ptr) = rr("2001:DB8::dead:beef");
  280 
  281 The C<rr()> method provides simple RR lookup for scenarios where
  282 the full flexibility of Net::DNS is not required.
  283 
  284 Returns a list of L<Net::DNS::RR> objects for the specified name
  285 or an empty list if the query failed or no record was found.
  286 
  287 See L</EXAMPLES> for more complete examples.
  288 
  289 
  290 =head2 mx
  291 
  292     # Use a default resolver -- can not get an error string this way.
  293     use Net::DNS;
  294     my @mx = mx("example.com");
  295 
  296     # Use your own resolver object.
  297     my $res = Net::DNS::Resolver->new;
  298     my @mx  = mx($res, "example.com");
  299 
  300 Returns a list of L<Net::DNS::RR::MX> objects representing the MX
  301 records for the specified name.
  302 The list will be sorted by preference.
  303 Returns an empty list if the query failed or no MX record was found.
  304 
  305 This method does not look up address records; it resolves MX only.
  306 
  307 
  308 =head1 Dynamic DNS Update Support
  309 
  310 The Net::DNS module provides auxiliary functions which support
  311 dynamic DNS update requests.
  312 
  313 
  314 =head2 yxrrset
  315 
  316 Use this method to add an "RRset exists" prerequisite to a dynamic
  317 update packet.  There are two forms, value-independent and
  318 value-dependent:
  319 
  320     # RRset exists (value-independent)
  321     $update->push( pre => yxrrset("host.example.com AAAA") );
  322 
  323 Meaning:  At least one RR with the specified name and type must
  324 exist.
  325 
  326     # RRset exists (value-dependent)
  327     $update->push( pre => yxrrset("host.example.com AAAA 2001:DB8::dead:beef") );
  328 
  329 Meaning:  At least one RR with the specified name and type must
  330 exist and must have matching data.
  331 
  332 Returns a L<Net::DNS::RR> object or C<undef> if the object could not
  333 be created.
  334 
  335 =head2 nxrrset
  336 
  337 Use this method to add an "RRset does not exist" prerequisite to
  338 a dynamic update packet.
  339 
  340     $update->push( pre => nxrrset("host.example.com AAAA") );
  341 
  342 Meaning:  No RRs with the specified name and type can exist.
  343 
  344 Returns a L<Net::DNS::RR> object or C<undef> if the object could not
  345 be created.
  346 
  347 =head2 yxdomain
  348 
  349 Use this method to add a "name is in use" prerequisite to a dynamic
  350 update packet.
  351 
  352     $update->push( pre => yxdomain("host.example.com") );
  353 
  354 Meaning:  At least one RR with the specified name must exist.
  355 
  356 Returns a L<Net::DNS::RR> object or C<undef> if the object could not
  357 be created.
  358 
  359 =head2 nxdomain
  360 
  361 Use this method to add a "name is not in use" prerequisite to a
  362 dynamic update packet.
  363 
  364     $update->push( pre => nxdomain("host.example.com") );
  365 
  366 Meaning:  No RR with the specified name can exist.
  367 
  368 Returns a L<Net::DNS::RR> object or C<undef> if the object could not
  369 be created.
  370 
  371 =head2 rr_add
  372 
  373 Use this method to add RRs to a zone.
  374 
  375     $update->push( update => rr_add("host.example.com AAAA 2001:DB8::dead:beef") );
  376 
  377 Meaning:  Add this RR to the zone.
  378 
  379 RR objects created by this method should be added to the "update"
  380 section of a dynamic update packet.  The TTL defaults to 86400
  381 seconds (24 hours) if not specified.
  382 
  383 Returns a L<Net::DNS::RR> object or C<undef> if the object could not
  384 be created.
  385 
  386 =head2 rr_del
  387 
  388 Use this method to delete RRs from a zone.  There are three forms:
  389 delete all RRsets, delete an RRset, and delete a specific RR.
  390 
  391     # Delete all RRsets.
  392     $update->push( update => rr_del("host.example.com") );
  393 
  394 Meaning:  Delete all RRs having the specified name.
  395 
  396     # Delete an RRset.
  397     $update->push( update => rr_del("host.example.com AAAA") );
  398 
  399 Meaning:  Delete all RRs having the specified name and type.
  400 
  401     # Delete a specific RR.
  402     $update->push( update => rr_del("host.example.com AAAA 2001:DB8::dead:beef") );
  403 
  404 Meaning:  Delete the RR which matches the specified argument.
  405 
  406 RR objects created by this method should be added to the "update"
  407 section of a dynamic update packet.
  408 
  409 Returns a L<Net::DNS::RR> object or C<undef> if the object could not
  410 be created.
  411 
  412 
  413 =head1 Zone Serial Number Management
  414 
  415 The Net::DNS module provides auxiliary functions which support
  416 policy-driven zone serial numbering regimes.
  417 
  418 =head2 SEQUENTIAL
  419 
  420     $successor = $soa->serial( SEQUENTIAL );
  421 
  422 The existing serial number is incremented modulo 2**32.
  423 
  424 =head2 UNIXTIME
  425 
  426     $successor = $soa->serial( UNIXTIME );
  427 
  428 The Unix time scale will be used as the basis for zone serial
  429 numbering. The serial number will be incremented if the time
  430 elapsed since the previous update is less than one second.
  431 
  432 =head2 YYYYMMDDxx
  433 
  434     $successor = $soa->serial( YYYYMMDDxx );
  435 
  436 The 32 bit value returned by the auxiliary C<YYYYMMDDxx()> function
  437 will be used as the base for the date-coded zone serial number.
  438 Serial number increments must be limited to 100 per day for the
  439 date information to remain useful.
  440 
  441 
  442 
  443 =head1 Sorting of RR arrays
  444 
  445 C<rrsort()> provides functionality to help you sort RR arrays. In most cases
  446 this will give you the result that you expect, but you can specify your
  447 own sorting method by using the C<< Net::DNS::RR::FOO->set_rrsort_func() >>
  448 class method. See L<Net::DNS::RR> for details.
  449 
  450 =head2 rrsort
  451 
  452     use Net::DNS;
  453 
  454     my @sorted = rrsort( $rrtype, $attribute, @rr_array );
  455 
  456 C<rrsort()> selects all RRs from the input array that are of the type defined
  457 by the first argument. Those RRs are sorted based on the attribute that is
  458 specified as second argument.
  459 
  460 There are a number of RRs for which the sorting function is defined in the
  461 code.
  462 
  463 For instance:
  464 
  465     my @prioritysorted = rrsort( "SRV", "priority", @rr_array );
  466 
  467 returns the SRV records sorted from lowest to highest priority and for
  468 equal priorities from highest to lowest weight.
  469 
  470 If the function does not exist then a numerical sort on the attribute
  471 value is performed.
  472 
  473     my @portsorted = rrsort( "SRV", "port", @rr_array );
  474 
  475 If the attribute is not defined then either the C<default_sort()> function or
  476 "canonical sorting" (as defined by DNSSEC) will be used.
  477 
  478 C<rrsort()> returns a sorted array containing only elements of the specified
  479 RR type.  Any other RR types are silently discarded.
  480 
  481 C<rrsort()> returns an empty list when arguments are incorrect.
  482 
  483 
  484 =head1 EXAMPLES
  485 
  486 The following brief examples illustrate some of the features of Net::DNS.
  487 The documentation for individual modules and the demo scripts included
  488 with the distribution provide more extensive examples.
  489 
  490 See L<Net::DNS::Update> for an example of performing dynamic updates.
  491 
  492 
  493 =head2 Look up host addresses.
  494 
  495     use Net::DNS;
  496     my $res   = Net::DNS::Resolver->new;
  497     my $reply = $res->search("www.example.com", "AAAA");
  498 
  499     if ($reply) {
  500     foreach my $rr ($reply->answer) {
  501         print $rr->address, "\n" if $rr->can("address");
  502     }
  503     } else {
  504     warn "query failed: ", $res->errorstring, "\n";
  505     }
  506 
  507 
  508 =head2 Find the nameservers for a domain.
  509 
  510     use Net::DNS;
  511     my $res   = Net::DNS::Resolver->new;
  512     my $reply = $res->query("example.com", "NS");
  513 
  514     if ($reply) {
  515     foreach $rr (grep { $_->type eq "NS" } $reply->answer) {
  516         print $rr->nsdname, "\n";
  517     }
  518     } else {
  519     warn "query failed: ", $res->errorstring, "\n";
  520     }
  521 
  522 
  523 =head2 Find the MX records for a domain.
  524 
  525     use Net::DNS;
  526     my $name = "example.com";
  527     my $res  = Net::DNS::Resolver->new;
  528     my @mx   = mx($res, $name);
  529 
  530     if (@mx) {
  531     foreach $rr (@mx) {
  532         print $rr->preference, "\t", $rr->exchange, "\n";
  533     }
  534     } else {
  535     warn "Can not find MX records for $name: ", $res->errorstring, "\n";
  536     }
  537 
  538 
  539 =head2 Print domain SOA record in zone file format.
  540 
  541     use Net::DNS;
  542     my $res   = Net::DNS::Resolver->new;
  543     my $reply = $res->query("example.com", "SOA");
  544 
  545     if ($reply) {
  546     foreach my $rr ($reply->answer) {
  547         $rr->print;
  548     }
  549     } else {
  550     warn "query failed: ", $res->errorstring, "\n";
  551     }
  552 
  553 
  554 =head2 Perform a zone transfer and print all the records.
  555 
  556     use Net::DNS;
  557     my $res  = Net::DNS::Resolver->new;
  558     $res->tcp_timeout(20);
  559     $res->nameservers("ns.example.com");
  560 
  561     my @zone = $res->axfr("example.com");
  562 
  563     foreach $rr (@zone) {
  564     $rr->print;
  565     }
  566 
  567     warn $res->errorstring if $res->errorstring;
  568 
  569 
  570 =head2 Perform a background query and print the reply.
  571 
  572     use Net::DNS;
  573     my $res    = Net::DNS::Resolver->new;
  574     $res->udp_timeout(10);
  575     $res->tcp_timeout(20);
  576     my $socket = $res->bgsend("host.example.com", "AAAA");
  577 
  578     while ( $res->bgbusy($socket) ) {
  579     # do some work here while waiting for the response
  580     # ...and some more here
  581     }
  582 
  583     my $packet = $res->bgread($socket);
  584     if ($packet) {
  585     $packet->print;
  586     } else {
  587     warn "query failed: ", $res->errorstring, "\n";
  588     }
  589 
  590 
  591 =head1 BUGS
  592 
  593 Net::DNS is slow.
  594 
  595 For other items to be fixed, or if you discover a bug in this
  596 distribution please use the CPAN bug reporting system.
  597 
  598 
  599 =head1 COPYRIGHT
  600 
  601 Copyright (c)1997-2000 Michael Fuhr.
  602 
  603 Portions Copyright (c)2002,2003 Chris Reinhardt.
  604 
  605 Portions Copyright (c)2005 Olaf Kolkman (RIPE NCC)
  606 
  607 Portions Copyright (c)2006 Olaf Kolkman (NLnet Labs)
  608 
  609 Portions Copyright (c)2014 Dick Franks
  610 
  611 All rights reserved.
  612 
  613 
  614 =head1 LICENSE
  615 
  616 Permission to use, copy, modify, and distribute this software and its
  617 documentation for any purpose and without fee is hereby granted, provided
  618 that the above copyright notice appear in all copies and that both that
  619 copyright notice and this permission notice appear in supporting
  620 documentation, and that the name of the author not be used in advertising
  621 or publicity pertaining to distribution of the software without specific
  622 prior written permission.
  623 
  624 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  625 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  626 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  627 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  628 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  629 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  630 DEALINGS IN THE SOFTWARE.
  631 
  632 
  633 =head1 AUTHOR INFORMATION
  634 
  635 Net::DNS is maintained at NLnet Labs (www.nlnetlabs.nl) by Willem Toorop.
  636 
  637 Between 2005 and 2012 Net::DNS was maintained by Olaf Kolkman.
  638 
  639 Between 2002 and 2004 Net::DNS was maintained by Chris Reinhardt.
  640 
  641 Net::DNS was created in 1997 by Michael Fuhr.
  642 
  643 
  644 =head1 SEE ALSO
  645 
  646 L<perl>, L<Net::DNS::Resolver>, L<Net::DNS::Question>, L<Net::DNS::RR>,
  647 L<Net::DNS::Packet>, L<Net::DNS::Update>,
  648 RFC1035, L<http://www.net-dns.org/>,
  649 I<DNS and BIND> by Paul Albitz & Cricket Liu
  650 
  651 =cut
  652