1Rule(3)               User Contributed Perl Documentation              Rule(3)
2
3
4

NAME

6         Net::DNS::SEC::Tools::Donuts::Rule - Define donuts DNS record-checking rules
7

DESCRIPTION

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
13       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

RULE FILE FORMAT

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
23         name: rulename
24         class: Warning
25         <test>
26           my ($record) = @_;
27           return "problem found"
28             if ($record{xxx} != yyy);
29         </test>
30
31       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
38       Each rule definition within a file should be separated using a blank
39       line.
40
41       Lines beginning with the '#' character will be discarded as a comment.
42
43       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
48           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
54           Example:
55
56             name: DNSSEC_TEST_SOME_SECURE_FEATURE
57
58       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
64           The default level of every rule is 5.
65
66           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
71           Example:
72
73             name: DNSSEC_TEST_SOME_SECURE_FEATURE
74             level: 2
75
76       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
81           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
85           Example:
86             name: DNSSEC_TEST_SOME_SECURE_FEATURE
87             class: Warning
88
89       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
96           The default value for this clause is record.
97
98           Example:
99
100             name: DNSSEC_TEST_SOME_SECURE_FEATURE
101             ruletype: record
102
103       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
109           For example, if a rule is testing a particular aspect of an MX
110           record, it should specify MX in this field.
111
112           Example:
113
114             name: DNSSEC_TEST_SOME_SECURE_FEATURE
115             type: MX
116
117       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
123           init sections are wrapped in an XML-like syntax which specifies the
124           start and end of the init section of code.
125
126           Example:
127
128             <init>
129               use My::Module;
130               $value = calculate();
131             </init>
132
133       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
140           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
146           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
153           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
157           record tests
158               These code snippets are expected to test a single Net::DNS::RR
159               record.
160
161               It is called with two arguments:
162
163                 1) the record which is to be tested
164
165                 2) the rule definition itself.
166
167           name tests
168               These code snippets are expected to test all the records asso‐
169               ciated with a given name record.
170
171               It is called with three arguments:
172
173                 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
180                 2) The rule definition.
181
182                 3) The record name being checked (the name associated with
183                    the data from 1) above.)
184
185           Examples:
186
187             # 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
196             # 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
206       feature: NAME
207           The feature tag prevents this rule from running unless the NAME
208           keyword was specified using the --features flag.
209
210       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
215       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
222           Example:
223
224             1) In the rule file (this is an incomplete definition):
225
226                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
234             2) This allows the user to change the value of myconfig via their
235                .donuts.conf file:
236
237                # change SOME_TEST config...
238                name:     SOME_TEST
239                myconfig: 40
240
241             3) and running donuts -H will show the help line for myconfig.
242
243       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

AUTHOR

259       Wes Hardaker <hardaker@users.sourceforge.net>
260

SEE ALSO

262       donuts(8)
263
264       Net::DNS, Net::DNS::RR
265
266       http://dnssec-tools.sourceforge.net
267
268
269
270perl v5.8.8                       2007-05-22                           Rule(3)
Impressum