.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DONUTS 1p"
.TH DONUTS 1p "2012-06-28" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
donuts \- analyze DNS zone files for errors and warnings
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  donuts [\-v] [\-l LEVEL] [\-r RULEFILES] [\-i IGNORELIST]
\&         [\-C] [\-c configfile] [\-h] [\-H] ZONEFILE DOMAINNAME...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdonuts\fR is a \s-1DNS\s0 lint application that examines \s-1DNS\s0 zone files
looking for particular problems.  This is especially important for
zones making use of \s-1DNSSEC\s0 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 \fBdonuts\fR with \*(L"\-i \s-1DNSSEC\s0\*(R".
.PP
If the \fBText::Wrap\fR Perl module is installed, \fBdonuts\fR will give better
output formatting.
.SH "OPTIONS"
.IX Header "OPTIONS"
.SS "Rule Set Configuration:"
.IX Subsection "Rule Set Configuration:"
.IP "\-l \fI\s-1LEVEL\s0\fR" 4
.IX Item "-l LEVEL"
.PD 0
.IP "\-\-level=\fI\s-1LEVEL\s0\fR" 4
.IX Item "--level=LEVEL"
.PD
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.
.IP "\-r \fI\s-1RULEFILES\s0\fR" 4
.IX Item "-r RULEFILES"
.PD 0
.IP "\-\-rules=\fI\s-1RULEFILES\s0\fR" 4
.IX Item "--rules=RULEFILES"
.PD
A comma-separated list of rule files to load.  The strings will be
passed to \fI\fIglob()\fI\fR so * wildcards can be used to specify multiple files.
.Sp
Defaults to \fB/usr/local/share/dnssec\-tools/donuts/rules/*.txt\fR and
\&\fB\f(CB$HOME\fB/.dnssec\-tools/donuts/rules/*.txt\fR.
.IP "\-i \fI\s-1IGNORELIST\s0\fR" 4
.IX Item "-i IGNORELIST"
.PD 0
.IP "\-\-ignore=\fI\s-1IGNORELIST\s0\fR" 4
.IX Item "--ignore=IGNORELIST"
.PD
A comma-separated list of regex patterns which are checked against
rule names to determine if some should be ignored.  Run with \fI\-v\fR to
figure out rule names if you're not sure which rule is generating
errors you don't wish to see.
.IP "\-f \s-1LIST\s0" 4
.IX Item "-f LIST"
.PD 0
.IP "\-\-features=LIST" 4
.IX Item "--features=LIST"
.PD
The \fI\-\-features\fR 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 \fI\-\-features\fR flag to turn them on.  The \s-1LIST\s0 argument should be
a comma-separated list.  Example usage:
.Sp
.Vb 1
\&  \-\-features live,nsec_check
.Ve
.Sp
Features available in the default rule set distributed with \fBdonuts\fR:
.RS 4
.IP "live" 4
.IX Item "live"
The \fIlive\fR feature allows rules that need to perform live \s-1DNS\s0 queries
to run.  Most of these \fIlive\fR 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
\&\s-1DS\s0 record which authenticates the key used in a child zone the \fIlive\fR
feature will let a rule run which checks to see if the child is
actually publishing the \s-1DNSKEY\s0 that corresponds to the test zone's \s-1DS\s0
record.
.IP "nsec_check" 4
.IX Item "nsec_check"
This checks all the \s-1NSEC\s0 or \s-1NSEC3\s0 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.
.RE
.RS 4
.RE
.SS "Configuration File Options:"
.IX Subsection "Configuration File Options:"
.IP "\-c \fI\s-1CONFIGFILE\s0\fR" 4
.IX Item "-c CONFIGFILE"
.PD 0
.IP "\-\-config\-file=\fI\s-1CONFIGFILE\s0\fR" 4
.IX Item "--config-file=CONFIGFILE"
.PD
Parse a configuration file to change constraints specified by rules.
This defaults to \fB\f(CB$HOME\fB/.donuts.conf\fR.
.IP "\-C" 4
.IX Item "-C"
.PD 0
.IP "\-\-no\-config" 4
.IX Item "--no-config"
.PD
Don't read user configuration files at all, such as those specified by
the \fI\-c\fR option or the \fB\f(CB$HOME\fB/.donuts.conf\fR file.
.SS "Extra Live Query Options:"
.IX Subsection "Extra Live Query Options:"
Live Queries are enabled through the use of the \fI\-f live\fR arguments.
These options are only useful if that feature has been enabled.
.IP "\-t \fI\s-1INTERFACE\s0\fR" 4
.IX Item "-t INTERFACE"
.PD 0
.IP "\-\-tcpdump\-capture=\fI\s-1INTERFACE\s0\fR" 4
.IX Item "--tcpdump-capture=INTERFACE"
.PD
Specifies that \fBtcpdump\fR should be started on \fI\s-1INTERFACE\s0\fR (e.g.,
\&\*(L"eth0\*(R") just before \fBdonuts\fR 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 \fIlive\fR
feature, described above.
.IP "\-T \fI\s-1FILTER\s0\fR" 4
.IX Item "-T FILTER"
.PD 0
.IP "\-\-tcpdump\-filter=\fI\s-1FILTER\s0\fR" 4
.IX Item "--tcpdump-filter=FILTER"
.PD
When \fBtcpdump\fR is run, this \fI\s-1FILTER\s0\fR is passed to it for purposes of
filtering traffic.  By default, this is set to \fIport 53 || ip[6:2] &
0x1fff != 0\fR, which limits the traffic to traffic destined to port 53
(\s-1DNS\s0) or fragmented packets.
.IP "\-o \fI\s-1FILE\s0\fR" 4
.IX Item "-o FILE"
.PD 0
.IP "\-\-tcpdump\-output\-file=\fI\s-1FILE\s0\fR" 4
.IX Item "--tcpdump-output-file=FILE"
.PD
Saves the \fBtcpdump\fR\-captured packets to \fI\s-1FILE\s0\fR.  The following
special fields can be used to help generate unique file names:
.RS 4
.ie n .IP "%d" 4
.el .IP "\f(CW%d\fR" 4
.IX Item "%d"
This is replaced with the current domain name being analyzed (e.g.,
\&\*(L"example.com\*(R").
.ie n .IP "%t" 4
.el .IP "\f(CW%t\fR" 4
.IX Item "%t"
This is replaced with the current epoch time (i.e., the number of
seconds since Jan 1, 1970).
.RE
.RS 4
.Sp
This field defaults to \fI\f(CI%d\fI.%t.pcap\fR.
.RE
.IP "\-\-show\-gui" 4
.IX Item "--show-gui"
[alpha code]
.Sp
Displays a browsable \s-1GUI\s0 screen showing the results of the \fBdonuts\fR tests.
.Sp
The \fBQWizard\fR and \fBGtk2\fR Perl modules must be installed for this to work.
.SS "Help Options"
.IX Subsection "Help Options"
.IP "\-H" 4
.IX Item "-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.
.Sp
Your configuration file (e.g., \fB\f(CB$HOME\fB/.donuts.conf\fR) may have lines in it
that look like this:
.Sp
.Vb 3
\&  # 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
.Ve
.Sp
This allows you to override certain aspects of how rules are executed.
.IP "\-R" 4
.IX Item "-R"
Displays a list of all known rules along with their description (if
available).
.IP "\-h" 4
.IX Item "-h"
Displays a help message.
.IP "\-\-help" 4
.IX Item "--help"
Displays a help message more tailored to people who prefer long-style
options.
.IP "\-q" 4
.IX Item "-q"
Turns on a quieter output mode where only the errors and warnings are
shown.  \s-1IE\s0, the summary line of \*(L"N errors found ...\*(R" is not shown.
.Sp
\&\-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.
.IP "\-v" 4
.IX Item "-v"
Turns on more verbose output.  Multiple \fI\-v\fR's will turn on increasing
amounts of output.  The number of \-v's will dictate output:
.RS 4
.IP "1." 4
Describes which rules are being loaded and extra detail for rules that found errors (rule Level and extra text detail)
.IP "2." 4
Even more detail about rules that found errors: file name, file line
number, rule type.
.IP "3." 4
Shows extra detail on the record text being analyzed (the detail is
not always available, however).
.IP "4." 4
Even more detail about rules that found errors: dumps the rule code itself.
.IP "5." 4
Even more detail about rules that found errors: dumps the internal
rule structure.
.RE
.RS 4
.RE
.SS "Obsolete Options"
.IX Subsection "Obsolete Options"
.IP "\-L" 4
.IX Item "-L"
Obsolete command line option.  Please use \fI\-\-features live\fR instead.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Run \fBdonuts\fR in its default mode on the \fIexample.com\fR zone which is
contained in the \fBdb.example.com\fR file:
.PP
.Vb 1
\&  % donuts db.example.com example.com
.Ve
.PP
Run \fBdonuts\fR with significantly more output, both in terms of verbosity
and in terms of the number of rules that are run to analyze the file:
.PP
.Vb 1
\&  % donuts \-v \-v \-\-level 9 db.example.com example.com
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2012 \s-1SPARTA\s0, Inc.  All rights reserved.
See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Wes Hardaker <hardaker@users.sourceforge.net>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information on the dnssec-tools project:
.PP
.Vb 1
\&  http://www.dnssec\-tools.org/
.Ve
.PP
For writing rules that can be loaded by \fBdonuts\fR:
.PP
.Vb 1
\&  B<Net::DNS::SEC::Tools::Donuts::Rule>,
.Ve
.PP
General \s-1DNS\s0 and \s-1DNSSEC\s0 usage:
.PP
.Vb 1
\&  B<Net::DNS>, B<Net::DNS::SEC>
.Ve