Provided by: libdns-zoneparse-perl_1.10-1.1_all bug

NAME

       DNS::ZoneParse - Parse and manipulate DNS Zone Files.

SYNOPSIS

           use DNS::ZoneParse;

           my $zonefile = DNS::ZoneParse->new("/path/to/dns/zonefile.db", $origin);

           # Get a reference to the MX records
           my $mx = $zonefile->mx;

           # Change the first mailserver on the list
           $mx->[0] = { host => 'mail.localhost.com',
                        priority => 10,
                        name => '@' };

           # update the serial number
           $zonefile->new_serial();

           # write the new zone file to disk
           my $newzone;
           open($newzone, '>', '/path/to/dns/zonefile.db') or die "error";
           print $newzone $zonefile->output();
           close $newzone;

INSTALLATION

          perl Makefile.PL
          make
          make test
          make install

       Win32 users substitute "make" with "nmake" or equivalent.  nmake is available at
       http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe

DESCRIPTION

       This module will parse a Zone File and put all the Resource Records (RRs) into an
       anonymous hash structure. Various record types are supported, see the methods section for
       details. It could be useful for maintaining DNS zones, or for transferring DNS zones to
       other servers. If you want to generate an XML-friendly version of your zone files, it is
       easy to use XML::Simple with this module once you have parsed the zone file.

       DNS::ZoneParse scans the DNS zone file - removes comments and seperates the file into its
       constituent records. It then parses each record and stores the records internally. See
       below for information on the accessor methods.

   METHODS
       new This creates the DNS::ZoneParse object and loads the zone file.

           Example:
               my $zonefile = DNS::ZoneParse->new("/path/to/zonefile.db");

           You can also initialise the object with the contents of a file:
               my $zonefile = DNS::ZoneParse->new( \$zone_contents );

           You can pass a second, optional parameter to the constructor to supply an $origin if
           none can be found in the zone file.

               my $zonefile = DNS::ZoneParse->new( \$zone_contents, $origin );

           You can pass a third, optional parameter to the constructor to supply a callback which
           will be called whenever an unparsable line is encountered in the zone file. See
           "on_unparseable_line" for details on this parameter and how errors are handled when
           parsing zone files.

           If you plan to pass a on_unparseable_line callback but do not wish to specify an
           $origin, pass 'undef' as the $origin parameter.

       a(), cname(), srv(), mx(), ns(), ptr(), txt(), hinfo(), rp(), loc()
           These methods return references to the resource records. For example:

               my $mx = $zonefile->mx;

           Returns the mx records in an array reference.

           All records (except SOA) have the following properties: 'ttl', 'class', 'host',
           'name', 'ORIGIN'.

           MX records also have a 'priority' property.

           SRV records also have 'priority', 'weight' and 'port' properties.

           TXT records also have a 'text' property representing the record's 'txt-data'
           descriptive text.

           HINFO records also have 'cpu' and 'os' properties.

           RP records also have 'mbox' and 'text' properties.

           LOC records also have 'd1', 'm1', 's1', 'NorS', 'd2', 'm2', 's2', 'EorW', 'alt',
           'siz', 'hp', and 'vp', as per RFC 1876.

           If there are no records of a given type in the zone, the call will croak with an error
           message about an invalid method. (This is not an ideal behavior, but has been kept for
           backwards compatibility.)

           The 'ORIGIN' property is the fully-qualified origin of the record. See fqname for
           details on constructing a fully qualified domain name. Note: for SOA records, the
           'ORIGIN' will match the 'origin' property when the SOA record is specified as fully
           qualified.

       soa()
           Returns a hash reference with the following properties: 'serial', 'origin', 'primary',
           'refresh', 'retry', 'ttl', 'minimumTTL', 'email', 'expire', 'class', 'ORIGIN'.

           The 'ORIGIN' property is returned separate from 'origin' property, though the data may
           be the same. 'ORIGIN' represents the implicit origin for the record while 'origin'
           represents the origin specified on the SOA line in the file.

           If the 'origin' value is relative (that is, does not end with a '.'), the actual zone
           for which the SOA line applies must be computed by concatenating the 'origin' and
           'ORIGIN' values. See fqname for details. If the 'origin' value is absolute, no
           computation is necessary and 'origin' is the same as 'ORIGIN'.

       generate()
           Returns an array of hashes representing $GENERATE directives present in the zone.
           Note, $GENERATE directives are BIND-specific additions. They are not expanded by
           DNS::ZoneParse, but users are able to access and modify these directives. The
           following properties are returned:

           'range', 'lhs', 'ttl', 'class', 'type', 'rhs', 'ORIGIN'.

           See the BIND documentation for details on the syntax and usage of the $GENERATE
           directive.

       dump
           Returns a copy of the datastructute that stores all the resource records. This might
           be useful if you want to quickly transform the data into another format, such as XML.

       fqname
           Takes a single parameter, a hash reference containing a record.

           Returns the fully qualified name of this record, with a trailing '.'. In most cases
           this is as simple as concatenating the 'name' and 'ORIGIN' with a '.'  unless 'name'
           is '@', in which case the fqname is simply the 'ORIGIN'. For SOA records, the same
           process is performed on the 'origin' instead of 'name'.

           Please note, fqname will not expand the right hand side of a record (ie, CNAME, SOA,
           MX, etc). The user must expand these values via the above method.

       ttl_to_int
           Takes a single parameter, a string representing a valid record TTL.

           Returns an integer representing the number of seconds the TTL represents.  Note, this
           does not take into account any leap-years, leap-seconds, DST changes, etc. It is
           simply the count of the number of seconds in the specified period of time.

       new_serial
           "new_serial()" incriments the Zone serial number. It will generate a date-based serial
           number. Or you can pass a positive number to add to the current serial number.

           Examples:

               $zonefile->new_serial();
                       # generates a new serial number based on date:
                       # YYYYmmddHH format, incriments current serial
                       # by 1 if the new serial is still smaller

               $zonefile->new_serial(50);
                       # adds 50 to the original serial number

       output
           "output()" returns the new zone file output as a string. If you wish your output
           formatted differently, you can pass the output of "dump()" to your favourite
           templating module.

       last_parse_error_count
           Returns a count of the number of unparsable lines from the last time a zone file was
           parsed. If no zone file has been parsed yet, returns 0.

           If you want to be sure that a zone file was parsed completely and without error, the
           return value of this method should be checked after the constructor is called (or
           after a call to _parse).

       on_unparseable_line
           "on_unparseable_line()" is an accessor method for the callback used when an
           unparseable line is encountered while parsing a zone file. If not set, DNS::ZoneParse
           will "croak" when an unparsable line is encountered, but will continue to parse the
           file. Each time an unparsable line is encountered, an internal counter is
           incrememnted. See "last_parse_error_count" for details.

           The callback is passed four parameters, a reference to the DNS::ZoneParse object which
           is doing the parsing, the text of the line that is unable to be parsed, the text of
           the reason the line could not be parsed, and the text of the last successfully parsed
           line.

           If you want to abort parsing when an unparsable line is found, call "die" from within
           your callback and catch that die with an eval block around the DNS::ZoneParse
           constructor (or call to _parse).

           The method takes a single optional parameter, a code reference to the function that
           will be called when an unparsable line is reached. Returns a reference to the last
           callback. If passed an undefined value, a reference to the current callback is
           returned. If passed any other value, undef is returned.

   EXAMPLES
       This script will print the A records in a zone file, add a new A record for the name "new"
       and then return the zone file.

           use strict;
           use DNS::ZoneParse;

           my $zonefile = DNS::ZoneParse->new("/path/to/zonefile.db");

           print "Current A Records\n";
           my $a_records = $zonefile->a();

           foreach my $record (@$a_records) {
               print "$record->{name} resolves at $record->{host}\n";
           }

           push (@$a_records, { name => 'new', class => 'IN',
                                host => '127.0.0.1', ttl => '' });

           $zonefile->new_serial();
           my $newfile = $zonefile->output();

       This script will convert a DNS Zone file to an XML file using XML::Simple.

           use strict;
           use DNS::ZoneParse;
           use XML::Simple;

           my $zonefile = DNS::ZoneParse->new("/path/to/zonefile.db");

           my $new_xml = XMLout($zonefile->dump,
                                noattr => 1,
                                suppressempty => 1,
                                rootname => $zonefile->origin);

CHANGES

       See Changes

API

       The DNS::ZoneParse API may change in future versions. At present, the parsing is not as
       strict as it should be and support for $ORIGIN and $TTL is quite basic. It would also be
       nice to support the "INCLUDE" statement. Furthermore, parsing large zone files with
       thousands of records can use lots of memory - some people have requested a callback
       interface.

BUGS

       I can squash more bugs with your help. Please let me know if you spot something that
       doesn't work as expected.

       You can report bugs via the CPAN RT:
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=DNS-ZoneParse>

       If possible, please provide a diff against t/dns-zoneparse.t and t/test-zone.db that
       demonstrates the bug(s).

SEE ALSO

       Other modules with similar functionality:

       Net::DNS::ZoneParser, Net::DNS::ZoneFile, DNS::ZoneFile

AUTHOR

       Simon Flack

MAINTENANCE

       Maintainers: Mike Schilli (m@perlmeister.com), John Eaglesham (perl@8192.net).

       Bug queue: http://rt.cpan.org/Public/Dist/Display.html?Name=DNS-ZoneParse

LICENSE

       DNS::ZoneParse is free software which you can redistribute and/or modify under the same
       terms as Perl itself.