NAME¶
donuts - analyze DNS zone files for errors and warnings
SYNOPSIS¶
donuts [-v] [-l LEVEL] [-r RULEFILES] [-i IGNORELIST]
[-C] [-c configfile] [-h] [-H] ZONEFILE DOMAINNAME...
DESCRIPTION¶
donuts is a DNS lint application that examines DNS zone files looking for
particular problems. This is especially important for zones making use of
DNSSEC security records, since many subtle problems can occur. The default
mode of operation assumes you want to check for DNSSEC-related issues; to turn
off the invocation of the DNSSEC-related rules run
donuts with "-i
DNSSEC".
If the
Text::Wrap Perl module is installed,
donuts will give
better output formatting.
OPTIONS¶
Rule Set Configuration:¶
- -l LEVEL
- --level=LEVEL
- Sets the level of errors to be displayed. The default is
level 5. The maximum value is level 9, which displays many debugging
results. You probably want to run no higher than level 8.
- -r RULEFILES
- --rules=RULEFILES
- A comma-separated list of rule files to load. The strings
will be passed to glob() so * wildcards can be used
to specify multiple files.
Defaults to /usr/local/share/dnssec-tools/donuts/rules/*.txt and
$HOME/.dnssec-tools/donuts/rules/*.txt.
- -i IGNORELIST
- --ignore=IGNORELIST
- A comma-separated list of regex patterns which are checked
against rule names to determine if some should be ignored. Run with
-v to figure out rule names if you're not sure which rule is
generating errors you don't wish to see.
- -f LIST
- --features=LIST
- The --features option specifies additional rule
features that should be executed. Some rules are turned off by default
because they are more intensive or require a live network connection, for
instance. Use the --features flag to turn them on. The LIST
argument should be a comma-separated list. Example usage:
--features live,nsec_check
Features available in the default rule set distributed with
donuts:
- live
- The live feature allows rules that need to perform
live DNS queries to run. Most of these live rules query parent and
children of the current zone, when appropriate, to see that the
parent/child relationships have been built properly. For example, if you
have a DS record which authenticates the key used in a child zone the
live feature will let a rule run which checks to see if the child
is actually publishing the DNSKEY that corresponds to the test zone's DS
record.
- nsec_check
- This checks all the NSEC or NSEC3 records (as appropriate
for the zone) to ensure the chain is complete and that no-overlaps exist.
It is fairly memory- and cpu-intensive in large zones.
Configuration File Options:¶
- -c CONFIGFILE
- --config-file=CONFIGFILE
- Parse a configuration file to change constraints specified
by rules. This defaults to $HOME/.donuts.conf.
- -C
- --no-config
- Don't read user configuration files at all, such as those
specified by the -c option or the
$HOME/.donuts.conf file.
Live Queries are enabled through the use of the
-f live arguments. These
options are only useful if that feature has been enabled.
- -t INTERFACE
- --tcpdump-capture=INTERFACE
- Specifies that tcpdump should be started on
INTERFACE (e.g., "eth0") just before donuts begins
its run of rules for each domain and will stop it just after it has
processed the rules. This is useful when you wish to capture the traffic
generated by the live feature, described above.
- -T FILTER
- --tcpdump-filter=FILTER
- When tcpdump is run, this FILTER is passed to
it for purposes of filtering traffic. By default, this is set to port
53 || ip[6:2] & 0x1fff != 0, which limits the traffic to
traffic destined to port 53 (DNS) or fragmented packets.
- -o FILE
- --tcpdump-output-file=FILE
- Saves the tcpdump-captured packets to FILE.
The following special fields can be used to help generate unique file
names:
- %d
- This is replaced with the current domain name being
analyzed (e.g., "example.com").
- %t
- This is replaced with the current epoch time (i.e., the
number of seconds since Jan 1, 1970).
This field defaults to
%d.%t.pcap.
- --show-gui
- [alpha code]
Displays a browsable GUI screen showing the results of the donuts
tests.
The QWizard and Gtk2 Perl modules must be installed for this
to work.
Help Options¶
- -H
- Displays the personal configuration file rules and tokens
that are acceptable in a configuration file. The output will consist of a
rule name, a token, and a description of its meaning.
Your configuration file (e.g., $HOME/.donuts.conf) may
have lines in it that look like this:
# change the default minimum number of legal NS records from 2 to 1
name: DNS_MULTIPLE_NS
minnsrecords: 1
# change the level of the following rule from 8 to 5
name: DNS_REASONABLE_TTLS
level: 5
This allows you to override certain aspects of how rules are executed.
- -R
- Displays a list of all known rules along with their
description (if available).
- -h
- Displays a help message.
- --help
- Displays a help message more tailored to people who prefer
long-style options.
- -q
- Turns on a quieter output mode where only the errors and
warnings are shown. IE, the summary line of "N errors found ..."
is not shown.
-q is ignored if a -v argument is present; the -v argument requests a longer
output summary and thus it doesn't make sense to use them both at the same
time.
- -v
- Turns on more verbose output. Multiple -v's will
turn on increasing amounts of output. The number of -v's will dictate
output:
- 1.
- Describes which rules are being loaded and extra detail for
rules that found errors (rule Level and extra text detail)
- 2.
- Even more detail about rules that found errors: file name,
file line number, rule type.
- 3.
- Shows extra detail on the record text being analyzed (the
detail is not always available, however).
- 4.
- Even more detail about rules that found errors: dumps the
rule code itself.
- 5.
- Even more detail about rules that found errors: dumps the
internal rule structure.
Obsolete Options¶
- -L
- Obsolete command line option. Please use --features
live instead.
EXAMPLES¶
Run
donuts in its default mode on the
example.com zone which is
contained in the
db.example.com file:
% donuts db.example.com example.com
Run
donuts with significantly more output, both in terms of verbosity and
in terms of the number of rules that are run to analyze the file:
% donuts -v -v --level 9 db.example.com example.com
COPYRIGHT¶
Copyright 2004-2012 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¶
For more information on the dnssec-tools project:
http://www.dnssec-tools.org/
For writing rules that can be loaded by
donuts:
B<Net::DNS::SEC::Tools::Donuts::Rule>,
General DNS and DNSSEC usage:
B<Net::DNS>, B<Net::DNS::SEC>