Net::DNS::SEC::Tools::Donuts::Rule(3pm)

1Net::DNS::SEC::Tools::DUosneurtsC:o:nRturlieb(u3t)ed PerNletD:o:cDuNmSe:n:tSaEtCi:o:nTools::Donuts::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
14       following syntax.  See the donuts manual page for details on where to
15       place 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
83           convention 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 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
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.
107
108           For example, if a rule is testing a particular aspect of an MX
109           record, it should specify "MX" in this field.
110
111           Example:
112
113             name: DNSSEC_TEST_SOME_SECURE_FEATURE
114             type: MX
115
116       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
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 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
140           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
145           EG, the resulting code for a record test will look like this:
146
147             package main;
148             no strict;
149             sub
150             {
151               my ($record, $rule) = @_;
152               TESTCODE
153             }
154
155           And for name test will be:
156
157             package main;
158             no strict;
159             sub
160             {
161               my ($records, $rule, $recordname) = @_;
162               TESTCODE
163             }
164
165           (Again, this structure is only created if the test definition does
166           notb begin with "sub {" already)
167
168           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
176           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
180           record tests
181               These code snippets are expected to test a single Net::DNS::RR
182               record.
183
184               It is called with two arguments:
185
186                 1) $record: The record which is to be tested
187
188                 2) $recordname: The Net::DNS::SEC::Tools::Donuts::Rule object
189                    reference and rule definition information.
190
191               These are bound to $record and $rule automatically for the test
192               code to use.
193
194           name tests
195               These code snippets are expected to test all the records
196               associated with a given name record.
197
198               It is called with three arguments:
199
200                 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
208                 2) $rule: The Net::DNS::SEC::Tools::Donuts::Rule object reference
209                    and rule definition information.
210
211                 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
215               These are bound to $records, $rule and $recordname
216               automatically for the test code to use.
217
218           Example rules:
219
220             # 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
229             # 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
239       feature: NAME
240           The feature tag prevents this rule from running unless the NAME
241           keyword was specified using the --features flag.
242
243       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
248       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
254       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
261           Examples:
262
263             1) In the rule file (this is an incomplete rule definition):
264
265                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
272             2) This allows the user to change the value of myconfig via their
273                .donuts.conf file:
274
275                # change SOME_TEST config...
276                name:     SOME_TEST
277                myconfig: 40
278
279             3) and running donuts -H will show the help line for myconfig.
280
281       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

COPYRIGHT

293       Copyright 2004-2013 SPARTA, Inc.  All rights reserved.  See the COPYING
294       file included with the DNSSEC-Tools package for details.
295

AUTHOR

297       Wes Hardaker <hardaker@users.sourceforge.net>
298

NAME

DESCRIPTION

RULE FILE FORMAT

COPYRIGHT

AUTHOR

SEE ALSO