Section: User Contributed Perl Documentation (3)
Updated: 2009-02-16


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


This class wraps around a rule definition which is used by the donutsDNS zone file checker. It stores the data that implements a given rule.

Rules are defined in donuts rule configuration files using thefollowing syntax. See the donuts manual page for details on where toplace those files and how to load them. 


Each rule file can contain multiple rules. Each rule is composed of anumber of parts. Minimally, it must contain a name and a testportion. Everything else is optional and/or has defaults associatedwith 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 thetokens below, other rule-specific data can be stored in tokensand each rule is a hash of the above tokens as keys and theirassociated data. However, there are a few exceptions where specialtokens imply special meanings. These special tokens include testand 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 torefer 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 anindication of a global test category, such as ``DNSSEC''. Thebetter-named the rules, the more power the user will have forselecting certain types of rules via donuts -i and other flags.


The rule's execution level, as recognized by donuts. donuts willrun only those rules at or above donuts' current execution level.The execution level is specified by the -l option todonuts; 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 andless serious problems should be placed at a higher number. Themaximum value is 9, which is reserved for debugging rules only.8 is the maximum rule level that user-defined rules should use.


The class code indicates the type of problem associated with therule. It defaults to "Error``, and the only other value that shouldbe used is ''Warning".

This value is displayed to the user. Technically, any value could bespecified, but using anything other than the Error/Warningconvention could break portability in future versions.

  class: Warning

Rules fall into one of two types (currently): record or name.record rules have their test section evaluated for each record in azone file. name rules, on the other hand, get called once perrecord name stored in the database. See the test description belowfor further details on the arguments passed to each rule type.

The default value for this clause is record.


  name: DNSSEC_TEST_SOME_SECURE_FEATURE  ruletype: record
Rules that test a particular type of record should specify thetype field with the type of record it will test. The rulewill only be executed for records of that type.

For example, if a rule is testing a particular aspect of an MX record,it should specify ``MX'' in this field.


A block of code to be executed immediately as the rule is being parsedfrom the rule definition file. This is useful for boot-strap code tobe performed only at start-up. For example, perl "useMODULE::NAME;" or similar statements should be used in init sections.

init sections are wrapped in an XML-like syntax whichspecifies the start and end of the init section of code.


  <init>    use My::Module;    $value = calculate();  </init>
A block of code defining the test to be executed for each record orrecord name. The test statement follows the same multi-line codespecification described in the init clause above. Specifically,all the lines between the <test> and </test> braces are consideredpart of the test code.

The test contents must be a block of perl code. If it is not in theform of an anonymous subroutine (surrounded by ``sub {'' and ``}''markers), then the code will be automatically put inside a basicsubroutine block to turn it into an anonymous subroutine.

EG, the resulting code for a record test will look like this:

  package main;  no strict;  sub  {    my ($record, $rule) = @_;      TESTCODE  }

And for name test will be:

  package main;  no strict;  sub  {    my ($records, $rule, $recordname) = @_;      TESTCODE  }

(Again, this structure is only created if the test definitiondoes notb begin with ``sub {'' already)

When the testcode is run and the test fails, it should return an errorstring which will be displayed for the user. The text will beline-wrapped before display (and thus should be unformatted text.) Ifthe test is checking for multiple problems, a reference to an array oferror strings may be returned. A test block that has no errors toreport should return either an empty string or a reference to an emptyarray.

There are two types of tests (currently), and the test code iscalled with arguments that depend on the ruletype clause of the rule.These arguments and calling conventions are as follows:

record tests
These code snippets are expected to test a single Net::DNS::RR record.

It is called with two arguments:

  1) $record: The record which is to be tested  2) $recordname: The Net::DNS::SEC::Tools::Donuts::Rule object     reference and rule definition information.

These are bound to $record and $rule automatically for the testcode to use.

name tests
These code snippets are expected to test all the recordsassociated with a given name record.

It is called with three arguments:

  1) $records: A hash reference to all the record types associated     with that record name (e.g., '' might have a hash     reference containing an entry for 'A', 'MX', ...).  Each value of     the hash will contain an array of all the records for that type     (for example, the hash entry for the 'A' key may contain an array     with 2 Net::DNS::RR records, one for each A record attached to     the '' entry).  2) $rule: The Net::DNS::SEC::Tools::Donuts::Rule object reference     and rule definition information.  3) $recordname: The record name being checked (the name associated     with the data from 1) above which might be "" for     instance, or "">).

These are bound to $records, $rule and $recordnameautomatically for the test code to use.

Example rules:

  # 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 for $record->{name} is too small" if ($record->ttl < 60);  </test>  # local policy rule 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 "$recordname has an A record but does not have an HINFO record"      if (exists($records->{'A'}) && !exists($records->{'HINFO'}));  </test>
feature: NAME
The feature tag prevents this rule from running unless the NAMEkeyword was specified using the --features flag.
A short description of what the rule tests that will be printed to theuser in help output or in the error summary when donuts outputs theresults.
If the rule is configurable via the user's .donuts.conf file, thisdescribes the configuration tokens for the user when they requestconfiguration help via the -H or --help-config flags. Tokens may beused within rules by accessing them using the $rule reference passed tothe code (the second argument).


  1) In the rule file (this is an incomplete rule definition):     name:           SOME_TEST     myconfig:       40     help: myconfig: A special number to configure this test     <test>      # ... 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.
noindent: 1
nowrap: 1
Normally donuts will line-wrap the error summary produced by a ruleto enable automatic pretty-printing of error results. Sometimes,however, rules may wish to self-format their outputs. The nowrapoption indicates to donuts that the output is pre-formatted butshould still be indented to align with the output of the rest of theerror text (currently about 15 spaces.) The noindent tag, however,indicates that neither wrapping nor indenting should be performed, butthat the error should be printed as is.


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


Wes Hardaker <> 



Net::DNS, Net::DNS::RR




This document was created byman2html,using the manual pages.