xenial (1) donuts.1p.gz

Provided by: dnssec-tools_2.2-2_all bug

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.

   QUERYING LIVE ZONES
       If the ZONEFILE may be a live name prefixed with "live:" and the records afterwards will be queried and
       analyized as if it was in a zonefile.  For example, running donuts as:

         donuts -i NSEC live:badsign-a,good-a test.dnssec-tools.org

       Will query the test.dnssec-tools.org zone for the badsign-a and good-a records, collect the data and run
       them through the donuts analysis.  Because other data is needed as well for the analysis to be useful,
       donuts will also automatically collect the DNSKEYs, SOAs, and NS records for the zone.  Because NSEC
       records aren't loaded, it is advisable to add that rule exclusion for rules to be run.

       Other data types may be queried by appending a ':' and the type name to a record.  For example:

         donuts -i NSEC live:good-a,good-aaaa:aaaa test.dnssec-tools.org

   QUERYING LIVE ZONES WITH AFXR
       If your host is allowed to query for afxr transfers of a particular zone, you may use the afxr: filename
       token to indicate it should pull the zone data using a AFXR transfer.

         donuts -i NSEC afxr: dnssec-tools.org

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.

   Extra Live Query Options:
       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:

       -s  Sorts the resource records so that the order they're processed in is always consistent.  If the
           incoming zone is not always consistently ordered, the output can vary unless the resource records are
           always in the same order.  When sorted, however, they're always evaluated in the same order even if
           the zone file (or similar) order changes, and thus the output is consistent, making it easier for
           tools like diff to detect where changes occur in the output.  This comes at a higher CPU cost, as it
           takes more time to sort the entries.

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

       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>