Provided by: dnssec-tools_2.0-1_all bug

NAME

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

DESCRIPTION

       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.

RULE FILE FORMAT

       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.

       name
           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

       level
           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

       class
           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

       ruletype
           Rules fall into one of two types (currently): record or name.  record rules have their
           test section evaluated for each record in a zone file.  name rules, on the other hand,
           get called once per record 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

       type
           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.

           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

       init
           A block of code to be executed immediately as the rule is being parsed from the rule
           definition file. This is useful for boot-strap code to be performed only at start-up.
           For example, perl "use MODULE::NAME;" or similar 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>

       test
           A block of code defining the test to be executed for each record or record 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 test contents must be a block of perl code.  If it is not in the form of an
           anonymous subroutine (surrounded by "sub {" and "}" markers), then the code will be
           automatically put inside a basic subroutine 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 definition does notb begin with
           "sub {" already)

           When the testcode is run and 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 test block that has no
           errors to report should return either an empty string or a reference to an empty
           array.

           There are two types of tests (currently), and the test code is called 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 test code to use.

           name tests
               These code snippets are expected to test all the records associated 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., 'example.com' 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 'example.com' 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 "exmaple.com" for
                    instance, or "www.example.com">).

               These are bound to $records, $rule and $recordname automatically 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 NAME keyword was specified
           using the --features flag.

       desc: DESCRIPTION
           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.

       help: TOKEN: TOKEN-HELP
           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 using the
           $rule reference passed to the code (the second argument).

           Examples:

             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 rule to enable
           automatic pretty-printing of error results.  Sometimes, however, rules may wish to
           self-format their outputs.  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

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

AUTHOR

       Wes Hardaker <hardaker@users.sourceforge.net>

SEE ALSO

       donuts(8)

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

       http://dnssec-tools.sourceforge.net