1Net::DNS::SEC::Tools::DUosneurtsC:o:nRturlieb(u3t)ed PerNletD:o:cDuNmSe:n:tSaEtCi:o:nTools::Donuts::Rule(3)
2
6 Net::DNS::SEC::Tools::Donuts::Rule - Define donuts DNS record-checking rules
7
9 This class wraps around a rule definition which is used by the donuts
10 DNS zone file checker. It stores the data that implements a given
11 rule.
12 Rules are defined in donuts rule configuration files using the
14 following syntax. See the donuts manual page for details on where to
15 place those files and how to load them.
16
18 Each rule file can contain multiple rules. Each rule is composed of a
19 number of parts. Minimally, it must contain a name and a test portion.
20 Everything else is optional and/or has defaults associated with it.
21 The rule file format follows this example:
22 name: rulename
24 class: Warning
25 <test>
26 my ($record) = @_;
27 return "problem found"
28 if ($record{xxx} != yyy);
29 </test>
30 Further details about each section can be found below. Besides the
32 tokens below, other rule-specific data can be stored in tokens and each
33 rule is a hash of the above tokens as keys and their associated data.
34 However, there are a few exceptions where special tokens imply special
35 meanings. These special tokens include test and init. See below for
36 details.
37 Each rule definition within a file should be separated using a blank
39 line.
40 Lines beginning with the '#' character will be discarded as a comment.
42 name
44 The name of the rule. This is mandatory, as the user may need to
45 refer to names in the future for use with the -i flag, specifying
46 behavior in configuration files, and for other uses.
47 By convention, all names should be specified using capital letters
49 and '_' characters between the words. The leftmost word should
50 give an indication of a global test category, such as "DNSSEC".
51 The better-named the rules, the more power the user will have for
52 selecting certain types of rules via donuts -i and other flags.
53 Example:
55 name: DNSSEC_TEST_SOME_SECURE_FEATURE
57 level
59 The rule's execution level, as recognized by donuts. donuts will
60 run only those rules at or above donuts' current execution level.
61 The execution level is specified by the -l option to donuts; if not
62 given, then the default execution level is 5.
63 The default level of every rule is 5.
65 Generally, more serious problems should receive lower numbers and
67 less serious problems should be placed at a higher number. The
68 maximum value is 9, which is reserved for debugging rules only. 8
69 is the maximum rule level that user-defined rules should use.
70 Example:
72 name: DNSSEC_TEST_SOME_SECURE_FEATURE
74 level: 2
75 class
77 The class code indicates the type of problem associated with the
78 rule. It defaults to "Error", and the only other value that should
79 be used is "Warning".
80 This value is displayed to the user. Technically, any value could
82 be specified, but using anything other than the Error/Warning
83 convention could break portability in future versions.
84 Example:
86 name: DNSSEC_TEST_SOME_SECURE_FEATURE
87 class: Warning
88 ruletype
90 Rules fall into one of two types (currently): record or name.
91 record rules have their test section evaluated for each record in a
92 zone file. name rules, on the other hand, get called once per
93 record name stored in the database. See the test description below
94 for further details on the arguments passed to each rule type.
95 The default value for this clause is record.
97 Example:
99 name: DNSSEC_TEST_SOME_SECURE_FEATURE
101 ruletype: record
102 type
104 Rules that test a particular type of record should specify the type
105 field with the type of record it will test. The rule will only be
106 executed for records of that type.
107 For example, if a rule is testing a particular aspect of an MX
109 record, it should specify "MX" in this field.
110 Example:
112 name: DNSSEC_TEST_SOME_SECURE_FEATURE
114 type: MX
115 init
117 A block of code to be executed immediately as the rule is being
118 parsed from the rule definition file. This is useful for boot-strap
119 code to be performed only at start-up. For example, perl "use
120 MODULE::NAME;" or similar statements should be used in init
121 sections.
122 init sections are wrapped in an XML-like syntax which specifies the
124 start and end of the init section of code.
125 Example:
127 <init>
129 use My::Module;
130 $value = calculate();
131 </init>
132 test
134 A block of code defining the test to be executed for each record or
135 record name. The test statement follows the same multi-line code
136 specification described in the init clause above. Specifically,
137 all the lines between the <test> and </test> braces are considered
138 part of the test code.
139 The test contents must be a block of perl code. If it is not in
141 the form of an anonymous subroutine (surrounded by "sub {" and "}"
142 markers), then the code will be automatically put inside a basic
143 subroutine block to turn it into an anonymous subroutine.
144 EG, the resulting code for a record test will look like this:
146 package main;
148 no strict;
149 sub
150 {
151 my ($record, $rule) = @_;
152 TESTCODE
153 }
154 And for name test will be:
156 package main;
158 no strict;
159 sub
160 {
161 my ($records, $rule, $recordname) = @_;
162 TESTCODE
163 }
164 (Again, this structure is only created if the test definition does
166 notb begin with "sub {" already)
167 When the testcode is run and the test fails, it should return an
169 error string which will be displayed for the user. The text will
170 be line-wrapped before display (and thus should be unformatted
171 text.) If the test is checking for multiple problems, a reference
172 to an array of error strings may be returned. A test block that
173 has no errors to report should return either an empty string or a
174 reference to an empty array.
175 There are two types of tests (currently), and the test code is
177 called with arguments that depend on the ruletype clause of the
178 rule. These arguments and calling conventions are as follows:
179 record tests
181 These code snippets are expected to test a single Net::DNS::RR
182 record.
183 It is called with two arguments:
185 1) $record: The record which is to be tested
187 2) $recordname: The Net::DNS::SEC::Tools::Donuts::Rule object
189 reference and rule definition information.
190 These are bound to $record and $rule automatically for the test
192 code to use.
193 name tests
195 These code snippets are expected to test all the records
196 associated with a given name record.
197 It is called with three arguments:
199 1) $records: A hash reference to all the record types associated
201 with that record name (e.g., 'example.com' might have a hash
202 reference containing an entry for 'A', 'MX', ...). Each value of
203 the hash will contain an array of all the records for that type
204 (for example, the hash entry for the 'A' key may contain an array
205 with 2 Net::DNS::RR records, one for each A record attached to
206 the 'example.com' entry).
207 2) $rule: The Net::DNS::SEC::Tools::Donuts::Rule object reference
209 and rule definition information.
210 3) $recordname: The record name being checked (the name associated
212 with the data from 1) above which might be "exmaple.com" for
213 instance, or "www.example.com">).
214 These are bound to $records, $rule and $recordname
216 automatically for the test code to use.
217 Example rules:
219 # local rule to mandate that each record must have a
221 # TTL > 60 seconds
222 name: DNS_TTL_AT_LEAST_60
223 level: 8
224 type: record
225 <test>
226 return "TTL for $record->{name} is too small" if ($record->ttl < 60);
227 </test>
228 # local policy rule to mandate that anything with an A record
230 # must have an HINFO record too
231 name: DNS_MX_MUST_HAVE_A
232 level: 8
233 type: name
234 <test>
235 return "$recordname has an A record but does not have an HINFO record"
236 if (exists($records->{'A'}) && !exists($records->{'HINFO'}));
237 </test>
238 feature: NAME
240 The feature tag prevents this rule from running unless the NAME
241 keyword was specified using the --features flag.
242 desc: DESCRIPTION
244 A short description of what the rule tests that will be printed to
245 the user in help output or in the error summary when donuts outputs
246 the results.
247 requires: PERLMODULE1 PERLMODULE2 ...
249 This allows rules to depend on installed perl modules. They'll be
250 required and imported as the rule starts executing. If they don't
251 exist, an error will be logged using donuts_error() stating that
252 the module is required for that rule to work.
253 help: TOKEN: TOKEN-HELP
255 If the rule is configurable via the user's .donuts.conf file, this
256 describes the configuration tokens for the user when they request
257 configuration help via the -H or --help-config flags. Tokens may
258 be used within rules by accessing them using the $rule reference
259 passed to the code (the second argument).
260 Examples:
262 1) In the rule file (this is an incomplete rule definition):
264 name: SOME_TEST
266 myconfig: 40
267 help: myconfig: A special number to configure this test
268 <test>
269 # ... use $rule->{'myconfig'}
270 </test>
271 2) This allows the user to change the value of myconfig via their
273 .donuts.conf file:
274 # change SOME_TEST config...
276 name: SOME_TEST
277 myconfig: 40
278 3) and running donuts -H will show the help line for myconfig.
280 noindent: 1
282 nowrap: 1
283 Normally donuts will line-wrap the error summary produced by a rule
284 to enable automatic pretty-printing of error results. Sometimes,
285 however, rules may wish to self-format their outputs. The nowrap
286 option indicates to donuts that the output is pre-formatted but
287 should still be indented to align with the output of the rest of
288 the error text (currently about 15 spaces.) The noindent tag,
289 however, indicates that neither wrapping nor indenting should be
290 performed, but that the error should be printed as is.
291
293 Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING
294 file included with the DNSSEC-Tools package for details.
295
297 Wes Hardaker <hardaker@users.sourceforge.net>
298
300 donuts(8)
301 Net::DNS, Net::DNS::RR, Net::DNS::SEC::Tools::Donuts
303 http://www.dnssec-tools.org/
305perl v5.32.0 2020-07-N2e7t::DNS::SEC::Tools::Donuts::Rule(3)