1######################################################################
2 DNS::ZoneParse 1.10
3######################################################################
4
5NAME
6 DNS::ZoneParse - Parse and manipulate DNS Zone Files.
7
8SYNOPSIS
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
30INSTALLATION
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
41DESCRIPTION
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
254CHANGES
255 See Changes
256
257API
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
265BUGS
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
275SEE ALSO
276 Other modules with similar functionality:
277
278 Net::DNS::ZoneParser, Net::DNS::ZoneFile, DNS::ZoneFile
279
280AUTHOR
281 Simon Flack
282
283MAINTENANCE
284 Maintainers: Mike Schilli (m@perlmeister.com), John Eaglesham
285 (perl@8192.net).
286
287 Bug queue:
288 http://rt.cpan.org/Public/Dist/Display.html?Name=DNS-ZoneParse
289
290LICENSE
291 DNS::ZoneParse is free software which you can redistribute and/or modify
292 under the same terms as Perl itself.
293
294