| 1 |
###################################################################### |
| 2 |
DNS::ZoneParse 1.10 |
| 3 |
###################################################################### |
| 4 |
|
| 5 |
NAME |
| 6 |
DNS::ZoneParse - Parse and manipulate DNS Zone Files. |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
use DNS::ZoneParse; |
| 10 |
|
| 11 |
my $zonefile = DNS::ZoneParse->new("/path/to/dns/zonefile.db", $origin); |
| 12 |
|
| 13 |
# Get a reference to the MX records |
| 14 |
my $mx = $zonefile->mx; |
| 15 |
|
| 16 |
# Change the first mailserver on the list |
| 17 |
$mx->[0] = { host => 'mail.localhost.com', |
| 18 |
priority => 10, |
| 19 |
name => '@' }; |
| 20 |
|
| 21 |
# update the serial number |
| 22 |
$zonefile->new_serial(); |
| 23 |
|
| 24 |
# write the new zone file to disk |
| 25 |
my $newzone; |
| 26 |
open($newzone, '>', '/path/to/dns/zonefile.db') or die "error"; |
| 27 |
print $newzone $zonefile->output(); |
| 28 |
close $newzone; |
| 29 |
|
| 30 |
INSTALLATION |
| 31 |
perl Makefile.PL |
| 32 |
make |
| 33 |
make test |
| 34 |
make install |
| 35 |
|
| 36 |
Win32 users substitute "make" with "nmake" or equivalent. nmake is |
| 37 |
available at |
| 38 |
http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15 |
| 39 |
.exe |
| 40 |
|
| 41 |
DESCRIPTION |
| 42 |
This module will parse a Zone File and put all the Resource Records |
| 43 |
(RRs) into an anonymous hash structure. Various record types are |
| 44 |
supported, see the methods section for details. It could be useful for |
| 45 |
maintaining DNS zones, or for transferring DNS zones to other servers. |
| 46 |
If you want to generate an XML-friendly version of your zone files, it |
| 47 |
is easy to use XML::Simple with this module once you have parsed the |
| 48 |
zone file. |
| 49 |
|
| 50 |
DNS::ZoneParse scans the DNS zone file - removes comments and seperates |
| 51 |
the file into its constituent records. It then parses each record and |
| 52 |
stores the records internally. See below for information on the accessor |
| 53 |
methods. |
| 54 |
|
| 55 |
METHODS |
| 56 |
new This creates the DNS::ZoneParse object and loads the zone file. |
| 57 |
|
| 58 |
Example: my $zonefile = DNS::ZoneParse->new("/path/to/zonefile.db"); |
| 59 |
|
| 60 |
You can also initialise the object with the contents of a file: my |
| 61 |
$zonefile = DNS::ZoneParse->new( \$zone_contents ); |
| 62 |
|
| 63 |
You can pass a second, optional parameter to the constructor to |
| 64 |
supply an $origin if none can be found in the zone file. |
| 65 |
|
| 66 |
my $zonefile = DNS::ZoneParse->new( \$zone_contents, $origin ); |
| 67 |
|
| 68 |
You can pass a third, optional parameter to the constructor to |
| 69 |
supply a callback which will be called whenever an unparsable line |
| 70 |
is encountered in the zone file. See "on_unparseable_line" for |
| 71 |
details on this parameter and how errors are handled when parsing |
| 72 |
zone files. |
| 73 |
|
| 74 |
If you plan to pass a on_unparseable_line callback but do not wish |
| 75 |
to specify an $origin, pass 'undef' as the $origin parameter. |
| 76 |
|
| 77 |
a(), cname(), srv(), mx(), ns(), ptr(), txt(), hinfo(), rp(), loc() |
| 78 |
These methods return references to the resource records. For |
| 79 |
example: |
| 80 |
|
| 81 |
my $mx = $zonefile->mx; |
| 82 |
|
| 83 |
Returns the mx records in an array reference. |
| 84 |
|
| 85 |
All records (except SOA) have the following properties: 'ttl', |
| 86 |
'class', 'host', 'name', 'ORIGIN'. |
| 87 |
|
| 88 |
MX records also have a 'priority' property. |
| 89 |
|
| 90 |
SRV records also have 'priority', 'weight' and 'port' properties. |
| 91 |
|
| 92 |
TXT records also have a 'text' property representing the record's |
| 93 |
'txt-data' descriptive text. |
| 94 |
|
| 95 |
HINFO records also have 'cpu' and 'os' properties. |
| 96 |
|
| 97 |
RP records also have 'mbox' and 'text' properties. |
| 98 |
|
| 99 |
LOC records also have 'd1', 'm1', 's1', 'NorS', 'd2', 'm2', 's2', |
| 100 |
'EorW', 'alt', 'siz', 'hp', and 'vp', as per RFC 1876. |
| 101 |
|
| 102 |
If there are no records of a given type in the zone, the call will |
| 103 |
croak with an error message about an invalid method. (This is not an |
| 104 |
ideal behavior, but has been kept for backwards compatibility.) |
| 105 |
|
| 106 |
The 'ORIGIN' property is the fully-qualified origin of the record. |
| 107 |
See fqname for details on constructing a fully qualified domain |
| 108 |
name. Note: for SOA records, the 'ORIGIN' will match the 'origin' |
| 109 |
property when the SOA record is specified as fully qualified. |
| 110 |
|
| 111 |
soa() |
| 112 |
Returns a hash reference with the following properties: 'serial', |
| 113 |
'origin', 'primary', 'refresh', 'retry', 'ttl', 'minimumTTL', |
| 114 |
'email', 'expire', 'class', 'ORIGIN'. |
| 115 |
|
| 116 |
The 'ORIGIN' property is returned separate from 'origin' property, |
| 117 |
though the data may be the same. 'ORIGIN' represents the implicit |
| 118 |
origin for the record while 'origin' represents the origin specified |
| 119 |
on the SOA line in the file. |
| 120 |
|
| 121 |
If the 'origin' value is relative (that is, does not end with a |
| 122 |
'.'), the actual zone for which the SOA line applies must be |
| 123 |
computed by concatenating the 'origin' and 'ORIGIN' values. See |
| 124 |
fqname for details. If the 'origin' value is absolute, no |
| 125 |
computation is necessary and 'origin' is the same as 'ORIGIN'. |
| 126 |
|
| 127 |
generate() |
| 128 |
Returns an array of hashes representing $GENERATE directives present |
| 129 |
in the zone. Note, $GENERATE directives are BIND-specific additions. |
| 130 |
They are not expanded by DNS::ZoneParse, but users are able to |
| 131 |
access and modify these directives. The following properties are |
| 132 |
returned: |
| 133 |
|
| 134 |
'range', 'lhs', 'ttl', 'class', 'type', 'rhs', 'ORIGIN'. |
| 135 |
|
| 136 |
See the BIND documentation for details on the syntax and usage of |
| 137 |
the $GENERATE directive. |
| 138 |
|
| 139 |
dump |
| 140 |
Returns a copy of the datastructute that stores all the resource |
| 141 |
records. This might be useful if you want to quickly transform the |
| 142 |
data into another format, such as XML. |
| 143 |
|
| 144 |
fqname |
| 145 |
Takes a single parameter, a hash reference containing a record. |
| 146 |
|
| 147 |
Returns the fully qualified name of this record, with a trailing |
| 148 |
'.'. In most cases this is as simple as concatenating the 'name' and |
| 149 |
'ORIGIN' with a '.' unless 'name' is '@', in which case the fqname |
| 150 |
is simply the 'ORIGIN'. For SOA records, the same process is |
| 151 |
performed on the 'origin' instead of 'name'. |
| 152 |
|
| 153 |
Please note, fqname will not expand the right hand side of a record |
| 154 |
(ie, CNAME, SOA, MX, etc). The user must expand these values via the |
| 155 |
above method. |
| 156 |
|
| 157 |
ttl_to_int |
| 158 |
Takes a single parameter, a string representing a valid record TTL. |
| 159 |
|
| 160 |
Returns an integer representing the number of seconds the TTL |
| 161 |
represents. Note, this does not take into account any leap-years, |
| 162 |
leap-seconds, DST changes, etc. It is simply the count of the number |
| 163 |
of seconds in the specified period of time. |
| 164 |
|
| 165 |
new_serial |
| 166 |
"new_serial()" incriments the Zone serial number. It will generate a |
| 167 |
date-based serial number. Or you can pass a positive number to add |
| 168 |
to the current serial number. |
| 169 |
|
| 170 |
Examples: |
| 171 |
|
| 172 |
$zonefile->new_serial(); |
| 173 |
# generates a new serial number based on date: |
| 174 |
# YYYYmmddHH format, incriments current serial |
| 175 |
# by 1 if the new serial is still smaller |
| 176 |
|
| 177 |
$zonefile->new_serial(50); |
| 178 |
# adds 50 to the original serial number |
| 179 |
|
| 180 |
output |
| 181 |
"output()" returns the new zone file output as a string. If you wish |
| 182 |
your output formatted differently, you can pass the output of |
| 183 |
"dump()" to your favourite templating module. |
| 184 |
|
| 185 |
last_parse_error_count |
| 186 |
Returns a count of the number of unparsable lines from the last time |
| 187 |
a zone file was parsed. If no zone file has been parsed yet, returns |
| 188 |
0. |
| 189 |
|
| 190 |
If you want to be sure that a zone file was parsed completely and |
| 191 |
without error, the return value of this method should be checked |
| 192 |
after the constructor is called (or after a call to _parse). |
| 193 |
|
| 194 |
on_unparseable_line |
| 195 |
"on_unparseable_line()" is an accessor method for the callback used |
| 196 |
when an unparseable line is encountered while parsing a zone file. |
| 197 |
If not set, DNS::ZoneParse will "croak" when an unparsable line is |
| 198 |
encountered, but will continue to parse the file. Each time an |
| 199 |
unparsable line is encountered, an internal counter is incrememnted. |
| 200 |
See "last_parse_error_count" for details. |
| 201 |
|
| 202 |
The callback is passed four parameters, a reference to the |
| 203 |
DNS::ZoneParse object which is doing the parsing, the text of the |
| 204 |
line that is unable to be parsed, the text of the reason the line |
| 205 |
could not be parsed, and the text of the last successfully parsed |
| 206 |
line. |
| 207 |
|
| 208 |
If you want to abort parsing when an unparsable line is found, call |
| 209 |
"die" from within your callback and catch that die with an eval |
| 210 |
block around the DNS::ZoneParse constructor (or call to _parse). |
| 211 |
|
| 212 |
The method takes a single optional parameter, a code reference to |
| 213 |
the function that will be called when an unparsable line is reached. |
| 214 |
Returns a reference to the last callback. If passed an undefined |
| 215 |
value, a reference to the current callback is returned. If passed |
| 216 |
any other value, undef is returned. |
| 217 |
|
| 218 |
EXAMPLES |
| 219 |
This script will print the A records in a zone file, add a new A record |
| 220 |
for the name "new" and then return the zone file. |
| 221 |
|
| 222 |
use strict; |
| 223 |
use DNS::ZoneParse; |
| 224 |
|
| 225 |
my $zonefile = DNS::ZoneParse->new("/path/to/zonefile.db"); |
| 226 |
|
| 227 |
print "Current A Records\n"; |
| 228 |
my $a_records = $zonefile->a(); |
| 229 |
|
| 230 |
foreach my $record (@$a_records) { |
| 231 |
print "$record->{name} resolves at $record->{host}\n"; |
| 232 |
} |
| 233 |
|
| 234 |
push (@$a_records, { name => 'new', class => 'IN', |
| 235 |
host => '127.0.0.1', ttl => '' }); |
| 236 |
|
| 237 |
$zonefile->new_serial(); |
| 238 |
my $newfile = $zonefile->output(); |
| 239 |
|
| 240 |
This script will convert a DNS Zone file to an XML file using |
| 241 |
XML::Simple. |
| 242 |
|
| 243 |
use strict; |
| 244 |
use DNS::ZoneParse; |
| 245 |
use XML::Simple; |
| 246 |
|
| 247 |
my $zonefile = DNS::ZoneParse->new("/path/to/zonefile.db"); |
| 248 |
|
| 249 |
my $new_xml = XMLout($zonefile->dump, |
| 250 |
noattr => 1, |
| 251 |
suppressempty => 1, |
| 252 |
rootname => $zonefile->origin); |
| 253 |
|
| 254 |
CHANGES |
| 255 |
See Changes |
| 256 |
|
| 257 |
API |
| 258 |
The DNS::ZoneParse API may change in future versions. At present, the |
| 259 |
parsing is not as strict as it should be and support for $ORIGIN and |
| 260 |
$TTL is quite basic. It would also be nice to support the "INCLUDE" |
| 261 |
statement. Furthermore, parsing large zone files with thousands of |
| 262 |
records can use lots of memory - some people have requested a callback |
| 263 |
interface. |
| 264 |
|
| 265 |
BUGS |
| 266 |
I can squash more bugs with your help. Please let me know if you spot |
| 267 |
something that doesn't work as expected. |
| 268 |
|
| 269 |
You can report bugs via the CPAN RT: |
| 270 |
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=DNS-ZoneParse> |
| 271 |
|
| 272 |
If possible, please provide a diff against t/dns-zoneparse.t and |
| 273 |
t/test-zone.db that demonstrates the bug(s). |
| 274 |
|
| 275 |
SEE ALSO |
| 276 |
Other modules with similar functionality: |
| 277 |
|
| 278 |
Net::DNS::ZoneParser, Net::DNS::ZoneFile, DNS::ZoneFile |
| 279 |
|
| 280 |
AUTHOR |
| 281 |
Simon Flack |
| 282 |
|
| 283 |
MAINTENANCE |
| 284 |
Maintainers: Mike Schilli ([email protected]), John Eaglesham |
| 285 |
([email protected]). |
| 286 |
|
| 287 |
Bug queue: |
| 288 |
http://rt.cpan.org/Public/Dist/Display.html?Name=DNS-ZoneParse |
| 289 |
|
| 290 |
LICENSE |
| 291 |
DNS::ZoneParse is free software which you can redistribute and/or modify |
| 292 |
under the same terms as Perl itself. |
| 293 |
|