NAME¶
Net::DNS::ZoneFile::Fast -- parse BIND8/9 zone files
SYNOPSIS¶
use Net::DNS::ZoneFile::Fast;
my $rr = Net::DNS::ZoneFile::Fast::parse($zone_text);
DESCRIPTION¶
The Net::DNS::ZoneFile::Fast module provides an ability to parse zone files that
BIND8 and BIND9 use, fast. Currently it provides a single function,
parse() , which returns a reference to an array of
traditional
Net::DNS::RR objects, so that no new API has to be learned
in order to manipulate zone records.
Great care was taken to ensure that
parse() does its job as
fast as possible, so it is interesting to use this module to parse huge zones.
As an example datapoint, it takes less than 5 seconds to parse a 2.2 MB zone
with about 72000 records on an Athlon XP 2600+ box.
On the other hand, it is likely that
Net::DNS::RR objects that
parse() returns are going to be further processed. To
make it easier to link any record back to the zone file (say, to report a
logical error like infamous `CNAME and other data' back to the user, or to do
a zone file modification),
parse() inserts line numbering
information into
Net::DNS::RR objects.
The module currently understands:
- $GENERATE directive
- $ORIGIN directive
- $TTL directive
- $INCLUDE directive (only while
processing files or filehandles)
- A records
- AAAA records
- CNAME records
- DNAME records
- HINFO records
- LOC records
- MX records
- NS records
- PTR records
- RP records
- SOA records
- SRV records
- TXT records
- RRSIG records
- DNSKEY records
- DS records
- NSEC records
- RRSIG records
Non-standard third-party modules¶
Net::DNS.
Exports¶
None.
Subroutines¶
- parse
- Parses zone data and returns a reference to an array of
Net::DNS::RR objects if successful. Takes the following named (no
pun intended) parameters:
- text
- A semi-mandatory parameter, textual contents of the zone to
be parsed.
- fh
- A semi-mandatory parameter, a file handle from which zone
contents can be read for parsing.
- file
- A semi-mandatory parameter, a file name with the zone to
parse.
- origin
- An optional parameter specifying zone origin. The default
is ".". A trailing "." is appended if necessary.
- on_error
- An optional parameter, user-defined error handler. If
specified, it must be a subroutine reference, which will be called on any
error. This subroutine will be passed two parameters: a line number in the
zone, where the error occurred, and the error description.
- soft_errors
- By default, parse throws an exception on any error.
Set this optional parameter to a true value to avoid this. The default is
false, unless on_error is also specified, in which case it is
true.
- includes_root
- An optional parameter. By default, any $INCLUDE directives
encountered will be tested for existence and readability. If the base path
of the included filename is not your current working directory, this test
will fail. Set the includes_root to the same as your named.conf
file to avoid this failure.
- quiet
- An optional parameter. By default, on any error, the error
description is printed via warn(). Set quiet to a true value
if you don't want this. The default is false, unless on_error is
also specified, in which case it is true.
- debug
- An optional parameter. If set to true, will produce some
debug printing. You probably don't want to use that.
One of
text,
fh,
file must be specified. If more than one
is specified at the same time,
fh takes precedence over
file,
which takes precedence over
text.
As a special case, if
parse is called with a single, unnamed parameter,
it is assumed to be a zone text.
If
parse is unsuccessful, and does not throw an exception (because either
on_error or
soft_errors was specified),
parse returns
undef.
The returned
Net::DNS::RR are normal in every respect, except that each
of them has two extra keys, Line and Lines, which correspondingly are the line
number in the zone text where the record starts, and the number of lines the
record spans. This information can be accessed either via hash lookup
("$rr->{Line}"), or via an accessor method
("$rr->Line").
BUGS¶
The
parse() subroutine is not re-entrant, and it probably
will never be.
There is also no guarantee that
parse() will successfully
parse every zone parsable by BIND, and no guarantee that BIND will parse every
zone parsable by
parse(). That said,
parse() appears to do the right thing on around 50000
real life zones I tested it with.
SOA serial numbers with a decimal point are not supported (they're not a legal
zonefile contstruct, although bind8 supported them. Even bind is dropping
support for them in future releases).
COPYRIGHT AND LICENSE¶
Copyright 2003 by Anton Berezin and catpipe Systems ApS
"THE BEER-WARE LICENSE" (Revision 42)
<tobez@tobez.org> wrote this module. As long as you retain this notice
you can do whatever you want with this stuff. If we meet some day, and
you think this stuff is worth it, you can buy me a beer in return.
Anton Berezin
Copyright (c) 2004-2012 SPARTA, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of SPARTA, Inc nor the names of its contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
CREDITS¶
Anton Berezin created the versions up until 0.5. Wes Hardaker at Sparta
implemented the DNSSEC patches and took over maintenance of the module from
0.6 onward.
Anton's original CREDITS section:
This module was largely inspired by the I<Net::DNS::ZoneFile> module
by Luis E. Munoz.
Many thanks to Phil Regnauld and Luis E. Munoz for discussions.
SEE ALSO¶
http://www.dnssec-tools.org/, Net::DNS(3),
Net::DNS::RR(3),
Net::DNS::SEC(3)