Net::DNS::SEC::Tools::Donuts::Rule - Define donuts DNS record-checking rules
This class wraps around a rule definition which is used by the donuts DNS zone file checker. It stores the data that implements a given rule.
Rules are defined in donuts rule configuration files using the following syntax. See the donuts manual page for details on where to place those files and how to load them.
Each rule file can contain multiple rules. Each rule is composed of a number of parts. Minimally, it must contain a name and a test portion. Everything else is optional and/or has defaults associated with it. The rule file format follows this example:
name: rulename
class: Warning
<test>
my ($record) = @_;
return "problem found"
if ($record{xxx} != yyy);
</test>
Further details about each section can be found below. Besides the tokens below, other rule-specific data can be stored in tokens and each rule is a hash of the above tokens as keys and their associated data. However, there are a few exceptions where special tokens imply special meanings. These special tokens include test and init. See below for details.
Each rule definition within a file should be separated using a blank line.
Lines beginning with the '#' character will be discarded as a comment.
The name of the rule. This is mandatory, as the user may need to refer to names in the future for use with the -i flag, specifying behavior in configuration files, and for other uses.
By convention, all names should be specified using capital letters and '_' characters between the words. The leftmost word should give an indication of a global test category, such as ``DNSSEC''. The better-named the rules, the more power the user will have for selecting certain types of rules via donuts -i and other flags.
Example:
name: DNSSEC_TEST_SOME_SECURE_FEATURE
The rule's execution level, as recognized by donuts. donuts will run only those rules at or above donuts' current execution level. The execution level is specified by the -l option to donuts; if not given, then the default execution level is 5.
The default level of every rule is 5.
Generally, more serious problems should receive lower numbers and less serious problems should be placed at a higher number. The maximum value is 9, which is reserved for debugging rules only. 8 is the maximum rule level that user-defined rules should use.
Example:
name: DNSSEC_TEST_SOME_SECURE_FEATURE level: 2
The class code indicates the type of problem associated with the rule. It defaults to ``Error'', and the only other value that should be used is ``Warning''.
This value is displayed to the user. Technically, any value could be specified, but using anything other than the Error/Warning convention could break portability in future versions.
Example: name: DNSSEC_TEST_SOME_SECURE_FEATURE class: Warning
Rules fall into one of two types (currently): record or name. record rules have their test evaluated for each record in a zone file. name rules, on the other hand, get called once per name stored in the database. See the test description below for further details on the arguments passed to each rule type.
The default value for this clause is record.
Example:
name: DNSSEC_TEST_SOME_SECURE_FEATURE ruletype: record
Rules that test a particular type of record should specify the type field with the type of record it will test. The rule will only be executed for records of that type. This will result in less error checking for the user in the test section.
For example, if a rule is testing a particular aspect of an MX record, it should specify MX in this field.
Example:
name: DNSSEC_TEST_SOME_SECURE_FEATURE type: MX
A block of code to be executed immediately. This is useful for boot-strap code to be performed only at start-up, rather than at every rule-test invocation. For example, ``use MODULE;'' type statements should be used in init sections.
init sections are wrapped in an XML-like syntax which specifies the start and end of the init section of code.
Example:
<init>
use My::Module;
$value = calculate();
</init>
A block of code defining the test for each record or name. The test statement follows the same multi-line code specification described in the init clause above. Specifically, all the lines between the <test> and </test> braces are considered part of the test code.
The end result must be a subroutine reference which will be called by the donuts program. When the code is evaluated, if it does not begin with ``sub {'' then a ``sub {'' prefix and ``}'' suffix will be automatically added to the code to turn the code-snippet into a Perl subroutine.
If the test fails, it should return an error string which will be displayed for the user. The text will be line-wrapped before display (and thus should be unformatted text.) If the test is checking for multiple problems, a reference to an array of error strings may be returned. A return value of a reference to an empty array also indicates no error.
There are two types of tests (currently), and the code snippet is called with arguments which depend on the ruletype clause above. These arguments and calling conventions are as follows:
These code snippets are expected to test a single Net::DNS::RR record.
It is called with two arguments:
1) the record which is to be tested
2) the rule definition itself.
These code snippets are expected to test all the records associated with a given name record.
It is called with three arguments:
1) a hash reference to all the record types associated
with that name (e.g., 'A', 'MX', ...) and each value of
the hash will contain an array of all the records for
that type. (I.e., more than one entry in the array
reference will exist for names containing multiple 'A'
records.)
2) The rule definition.
3) The record name being checked (the name associated with
the data from 1) above.)
Examples:
# local rule to mandate that each record must have a
# TTL > 60 seconds
name: DNS_TTL_AT_LEAST_60
level: 8
type: record
<test>
return "TTL too small" if ($_[0]->ttl < 60);
</test>
# local policy to mandate that anything with an A record
# must have an HINFO record too
name: DNS_MX_MUST_HAVE_A
level: 8
type: name
<test>
return "A records must have an HINFO record too"
if (exists($_[0]{'A'}) && !exists($_[0]{'HINFO'}));
</test>
The feature tag prevents this rule from running unless the NAME keyword was specified using the --features flag.
A short description of what the rule tests that will be printed to the user in help output or in the error summary when donuts outputs the results.
If the rule is configurable via the user's .donuts.conf file, this describes the configuration tokens for the user when they request configuration help via the -H or --help-config flags. Tokens may be used within rules by accessing them within the rule argument passed to the code (the second argument.)
Example:
1) In the rule file (this is an incomplete definition):
name: SOME_TEST
myconfig: 40
help: myconfig: A special number to configure this test
<test>
my ($record, $rule) = @_;
# ... use $rule->{'myconfig'}
</test>
2) This allows the user to change the value of myconfig via their
.donuts.conf file:
# change SOME_TEST config...
name: SOME_TEST
myconfig: 40
3) and running donuts -H will show the help line for myconfig.
Normally donuts will line-wrap the error summary produced by a rule to enable automatic pretty-printing of error results. Sometimes, however, rules may not want this. The nowrap option indicates to donuts that the output is pre-formatted but should still be indented to align with the output of the rest of the error text (currently about 15 spaces.) The noindent tag, however, indicates that neither wrapping nor indenting should be performed, but that the error should be printed as is.
Copyright 2004-2007 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.
Wes Hardaker <hardaker@users.sourceforge.net>
donuts(8)
Net::DNS, Net::DNS::RR