Writing Donuts Rules

From DNSSEC-Tools Wiki

donuts is an extensible system that allows operators to write your own rules in order to process their zone files that will examine zone records looking for conformance adherence to custom rules and conventions. You can read the Net::DNS::SEC::Tools::Donuts::Rule manual for full details about the rule definition language. The following sections will provide a brief tutorial for writing your own rules:

Contents 1 Writing a new rule 1.1 Writing Record Rules 1.1.1 Example: checking address ranges 1.2 Writing Name Rules 1.2.1 Example: requiring an MX record

Writing a new rule

There are two types of donuts rules: one for processing each individual record and another for processing all the records associated with a given name.

If we use an example zone file that looks like the following:

$TTL 1D
example.com.   IN SOA host.example.com. admin.example.com. (
               2008010101
               3H                           ; refresh, seconds
               1H                           ; retry, seconds
               1W                           ; expire, seconds
               3H)                          ; negative ttl minimum, seconds

               NS      ns1.example.com.
               NS      ns2.example.com.
         1D IN MX      10 mail.example.com.

ns1.example.com.       1D IN A         192.0.2.81
ns2.example.com.       1D IN A         192.0.2.82
                       1D IN MX        10 mail.example.com.

www.example.com.       1D IN A         192.1.2.1
                       1D IN MX        10 mail.example.com.

ssh.example.com.       1D IN A         192.0.2.2
                       1D IN MX        10 mail.example.com.

Then the above has:

• 5 names (example.com, ns1, ns2, www and ssh)
• 10 records (1 SOA, 2 NS, 4 A and 3 MX).

And if the above zone is signed, it will contain no errors or warnings that are reported by donuts using the default rules and configuration.

Writing Record Rules

record rules describe a rule that is run once on each record in a zonefile. record rules are also the default type (if you do not include a ruletype: line in the rule definition, it will assume it is a record rule).

Defined rules can use the $record, $rule and $current_domain variables while processing.

The type: clause can be used to limit which record types are matched (E.G., a line of type: A will only analyze DNS A records with this rule.

Example: checking address ranges

Let's say you have a local policy that requires each A record in a zoneifle to contain an address within the 192.0.0.0/16 subnet. The following rule is an example rule that ensures your zone will support that requirement:

 name: CHECK_FOR_DIGIT
 desc: Checks to ensure all A records are within the 192.0 zone
 type: A
 <test>
   if ($record->address !~ /^192\.0\./) {
     return "Address for '$record->{name}' does not fall within the 192.0/16 range";
   }
 </test>

Running donuts as follows will then display an error for the www record above, which violates this new rule:

% donuts --rules /tmp/myrules.txt db.example.com example.com
www.example.com:
  Location:    db.example.com:16
  Error:       Address for 'www.example.com' does not fall within the
               192.0/16 range

1 errors found in db.example.com

Writing Name Rules

name rules describe a rule that is run once on each name in a zonefile.

Defined rules can use the $records, $rule, and $current_domain variables while processing.

Example: requiring an MX record

If you have a local policy that requires all records containing an A record also contain a MX record, then the following rule will test a zone to check that policy:

name: A_MUST_HAVE_MX
desc: Ensure that every name with an A record also has an MX record.
ruletype: name
<test>
  if (exists($records->{'A'}) && !exists($records->{'MX'})) {
    return "'$recordname' has an A record but does not have a MX record";
  }
</test>

Then running donuts on the zone above using that rule will result in 2 errors:

% donuts --rules /tmp/myrules.txt db.example.com example.com

ns1.example.com:
  Error:       'ns1.example.com' has an A record but does not have a MX
               record

ns2.example.com:
  Error:       'ns2.example.com' has an A record but does not have a MX
               record

2 errors found in db.example.com