1Rule(3) User Contributed Perl Documentation 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 follow‐
14 ing syntax. See the donuts manual page for details on where to place
15 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 con‐
83 vention 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 evaluated for each record in a zone
92 file. name rules, on the other hand, get called once per name
93 stored in the database. See the test description below for further
94 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. This will result in less error
107 checking for the user in the test section.
108 For example, if a rule is testing a particular aspect of an MX
110 record, it should specify MX in this field.
111 Example:
113 name: DNSSEC_TEST_SOME_SECURE_FEATURE
115 type: MX
116 init
118 A block of code to be executed immediately. This is useful for
119 boot-strap code to be performed only at start-up, rather than at
120 every rule-test invocation. For example, "use MODULE;" type state‐
121 ments should be used in init 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 for each record or name. The
135 test statement follows the same multi-line code specification
136 described in the init clause above. Specifically, all the lines
137 between the <test> and </test> braces are considered part of the
138 test code.
139 The end result must be a subroutine reference which will be called
141 by the donuts program. When the code is evaluated, if it does not
142 begin with "sub {" then a "sub {" prefix and "}" suffix will be
143 automatically added to the code to turn the code-snippet into a
144 Perl subroutine.
145 If the test fails, it should return an error string which will be
147 displayed for the user. The text will be line-wrapped before dis‐
148 play (and thus should be unformatted text.) If the test is check‐
149 ing for multiple problems, a reference to an array of error strings
150 may be returned. A return value of a reference to an empty array
151 also indicates no error.
152 There are two types of tests (currently), and the code snippet is
154 called with arguments which depend on the ruletype clause above.
155 These arguments and calling conventions are as follows:
156 record tests
158 These code snippets are expected to test a single Net::DNS::RR
159 record.
160 It is called with two arguments:
162 1) the record which is to be tested
164 2) the rule definition itself.
166 name tests
168 These code snippets are expected to test all the records asso‐
169 ciated with a given name record.
170 It is called with three arguments:
172 1) a hash reference to all the record types associated
174 with that name (e.g., 'A', 'MX', ...) and each value of
175 the hash will contain an array of all the records for
176 that type. (I.e., more than one entry in the array
177 reference will exist for names containing multiple 'A'
178 records.)
179 2) The rule definition.
181 3) The record name being checked (the name associated with
183 the data from 1) above.)
184 Examples:
186 # local rule to mandate that each record must have a
188 # TTL > 60 seconds
189 name: DNS_TTL_AT_LEAST_60
190 level: 8
191 type: record
192 <test>
193 return "TTL too small" if ($_[0]->ttl < 60);
194 </test>
195 # local policy to mandate that anything with an A record
197 # must have an HINFO record too
198 name: DNS_MX_MUST_HAVE_A
199 level: 8
200 type: name
201 <test>
202 return "A records must have an HINFO record too"
203 if (exists($_[0]{'A'}) && !exists($_[0]{'HINFO'}));
204 </test>
205 feature: NAME
207 The feature tag prevents this rule from running unless the NAME
208 keyword was specified using the --features flag.
209 desc: DESCRIPTION
211 A short description of what the rule tests that will be printed to
212 the user in help output or in the error summary when donuts outputs
213 the results.
214 help: TOKEN: TOKEN-HELP
216 If the rule is configurable via the user's .donuts.conf file, this
217 describes the configuration tokens for the user when they request
218 configuration help via the -H or --help-config flags. Tokens may
219 be used within rules by accessing them within the rule argument
220 passed to the code (the second argument.)
221 Example:
223 1) In the rule file (this is an incomplete definition):
225 name: SOME_TEST
227 myconfig: 40
228 help: myconfig: A special number to configure this test
229 <test>
230 my ($record, $rule) = @_;
231 # ... use $rule->{'myconfig'}
232 </test>
233 2) This allows the user to change the value of myconfig via their
235 .donuts.conf file:
236 # change SOME_TEST config...
238 name: SOME_TEST
239 myconfig: 40
240 3) and running donuts -H will show the help line for myconfig.
242 noindent: 1
244 nowrap: 1
245 Normally donuts will line-wrap the error summary produced by a rule
246 to enable automatic pretty-printing of error results. Sometimes,
247 however, rules may not want this. The nowrap option indicates to
248 donuts that the output is pre-formatted but should still be
249 indented to align with the output of the rest of the error text
250 (currently about 15 spaces.) The noindent tag, however, indicates
251 that neither wrapping nor indenting should be performed, but that
252 the error should be printed as is.
253
255 Copyright 2004-2007 SPARTA, Inc. All rights reserved. See the COPYING
256 file included with the DNSSEC-Tools package for details.
257
259 Wes Hardaker <hardaker@users.sourceforge.net>
260
262 donuts(8)
263 Net::DNS, Net::DNS::RR
265 http://dnssec-tools.sourceforge.net
267perl v5.8.8 2007-05-22 Rule(3)