donuts(1)

1DONUTS(1)             User Contributed Perl Documentation            DONUTS(1)
2
3
4

NAME

6       donuts - analyze DNS zone files for errors and warnings
7

SYNOPSIS

9         donuts [-v] [-l LEVEL] [-r RULEFILES] [-i IGNORELIST]
10                [-C] [-c configfile] [-h] [-H] ZONEFILE DOMAINNAME...
11

DESCRIPTION

13       donuts is a DNS lint application that examines DNS zone files looking
14       for particular problems.  This is especially important for zones making
15       use of DNSSEC security records, since many subtle problems can occur.
16       The default mode of operation assumes you want to check for DNSSEC-
17       related issues; to turn off the invocation of the DNSSEC-related rules
18       run donuts with "-i DNSSEC".
19
20       If the Text::Wrap Perl module is installed, donuts will give better
21       output formatting.
22
23   QUERYING LIVE ZONES
24       If the ZONEFILE may be a live name prefixed with "live:" and the
25       records afterwards will be queried and analyized as if it was in a
26       zonefile.  For example, running donuts as:
27
28         donuts -i NSEC live:badsign-a,good-a test.dnssec-tools.org
29
30       Will query the test.dnssec-tools.org zone for the badsign-a and good-a
31       records, collect the data and run them through the donuts analysis.
32       Because other data is needed as well for the analysis to be useful,
33       donuts will also automatically collect the DNSKEYs, SOAs, and NS
34       records for the zone.  Because NSEC records aren't loaded, it is
35       advisable to add that rule exclusion for rules to be run.
36
37       Other data types may be queried by appending a ':' and the type name to
38       a record.  For example:
39
40         donuts -i NSEC live:good-a,good-aaaa:aaaa test.dnssec-tools.org
41
42   QUERYING LIVE ZONES WITH AFXR
43       If your host is allowed to query for afxr transfers of a particular
44       zone, you may use the afxr: filename token to indicate it should pull
45       the zone data using a AFXR transfer.
46
47         donuts -i NSEC afxr: dnssec-tools.org
48

OPTIONS

50   Rule Set Configuration:
51       -l LEVEL
52       --level=LEVEL
53           Sets the level of errors to be displayed.  The default is level 5.
54           The maximum value is level 9, which displays many debugging
55           results.  You probably want to run no higher than level 8.
56
57       -r RULEFILES
58       --rules=RULEFILES
59           A comma-separated list of rule files to load.  The strings will be
60           passed to glob() so * wildcards can be used to specify multiple
61           files.
62
63           Defaults to /usr/local/share/dnssec-tools/donuts/rules/*.txt and
64           $HOME/.dnssec-tools/donuts/rules/*.txt.
65
66       -i IGNORELIST
67       --ignore=IGNORELIST
68           A comma-separated list of regex patterns which are checked against
69           rule names to determine if some should be ignored.  Run with -v to
70           figure out rule names if you're not sure which rule is generating
71           errors you don't wish to see.
72
73       -f LIST
74       --features=LIST
75           The --features option specifies additional rule features that
76           should be executed.  Some rules are turned off by default because
77           they are more intensive or require a live network connection, for
78           instance.  Use the --features flag to turn them on.  The LIST
79           argument should be a comma-separated list.  Example usage:
80
81             --features live,nsec_check
82
83           Features available in the default rule set distributed with donuts:
84
85           live
86               The live feature allows rules that need to perform live DNS
87               queries to run.  Most of these live rules query parent and
88               children of the current zone, when appropriate, to see that the
89               parent/child relationships have been built properly.  For
90               example, if you have a DS record which authenticates the key
91               used in a child zone the live feature will let a rule run which
92               checks to see if the child is actually publishing the DNSKEY
93               that corresponds to the test zone's DS record.
94
95           nsec_check
96               This checks all the NSEC or NSEC3 records (as appropriate for
97               the zone) to ensure the chain is complete and that no-overlaps
98               exist.  It is fairly memory- and cpu-intensive in large zones.
99
100   Configuration File Options:
101       -c CONFIGFILE
102       --config-file=CONFIGFILE
103           Parse a configuration file to change constraints specified by
104           rules.  This defaults to $HOME/.donuts.conf.
105
106       -C
107       --no-config
108           Don't read user configuration files at all, such as those specified
109           by the -c option or the $HOME/.donuts.conf file.
110
111   Extra Live Query Options:
112       Live Queries are enabled through the use of the -f live arguments.
113       These options are only useful if that feature has been enabled.
114
115       -t INTERFACE
116       --tcpdump-capture=INTERFACE
117           Specifies that tcpdump should be started on INTERFACE (e.g.,
118           "eth0") just before donuts begins its run of rules for each domain
119           and will stop it just after it has processed the rules.  This is
120           useful when you wish to capture the traffic generated by the live
121           feature, described above.
122
123       -T FILTER
124       --tcpdump-filter=FILTER
125           When tcpdump is run, this FILTER is passed to it for purposes of
126           filtering traffic.  By default, this is set to port 53 || ip[6:2] &
127           0x1fff != 0, which limits the traffic to traffic destined to port
128           53 (DNS) or fragmented packets.
129
130       -o FILE
131       --tcpdump-output-file=FILE
132           Saves the tcpdump-captured packets to FILE.  The following special
133           fields can be used to help generate unique file names:
134
135           %d  This is replaced with the current domain name being analyzed
136               (e.g., "example.com").
137
138           %t  This is replaced with the current epoch time (i.e., the number
139               of seconds since Jan 1, 1970).
140
141           This field defaults to %d.%t.pcap.
142
143       --show-gui
144           [alpha code]
145
146           Displays a browsable GUI screen showing the results of the donuts
147           tests.
148
149           The QWizard and Gtk2 Perl modules must be installed for this to
150           work.
151
152   Help Options
153       -H  Displays the personal configuration file rules and tokens that are
154           acceptable in a configuration file.  The output will consist of a
155           rule name, a token, and a description of its meaning.
156
157           Your configuration file (e.g., $HOME/.donuts.conf) may have lines
158           in it that look like this:
159
160             # change the default minimum number of legal NS records from 2 to 1
161             name: DNS_MULTIPLE_NS
162             minnsrecords: 1
163
164             # change the level of the following rule from 8 to 5
165             name: DNS_REASONABLE_TTLS
166             level: 5
167
168           This allows you to override certain aspects of how rules are
169           executed.
170
171       -R  Displays a list of all known rules along with their description (if
172           available).
173
174       -h  Displays a help message.
175
176       --help
177           Displays a help message more tailored to people who prefer long-
178           style options.
179
180       -q  Turns on a quieter output mode where only the errors and warnings
181           are shown.  IE, the summary line of "N errors found ..." is not
182           shown.
183
184           -q is ignored if a -v argument is present; the -v argument requests
185           a longer output summary and thus it doesn't make sense to use them
186           both at the same time.
187
188       -v  Turns on more verbose output.  Multiple -v's will turn on
189           increasing amounts of output.  The number of -v's will dictate
190           output:
191
192       -s  Sorts the resource records so that the order they're processed in
193           is always consistent.  If the incoming zone is not always
194           consistently ordered, the output can vary unless the resource
195           records are always in the same order.  When sorted, however,
196           they're always evaluated in the same order even if the zone file
197           (or similar) order changes, and thus the output is consistent,
198           making it easier for tools like diff to detect where changes occur
199           in the output.  This comes at a higher CPU cost, as it takes more
200           time to sort the entries.
201
202           1.  Describes which rules are being loaded and extra detail for
203               rules that found errors (rule Level and extra text detail)
204
205           2.  Even more detail about rules that found errors: file name, file
206               line number, rule type.
207
208           3.  Shows extra detail on the record text being analyzed (the
209               detail is not always available, however).
210
211           4.  Even more detail about rules that found errors: dumps the rule
212               code itself.
213
214           5.  Even more detail about rules that found errors: dumps the
215               internal rule structure.
216
217   Obsolete Options
218       -L  Obsolete command line option.  Please use --features live instead.
219

EXAMPLES

221       Run donuts in its default mode on the example.com zone which is
222       contained in the db.example.com file:
223
224         % donuts db.example.com example.com
225
226       Run donuts with significantly more output, both in terms of verbosity
227       and in terms of the number of rules that are run to analyze the file:
228
229         % donuts -v -v --level 9 db.example.com example.com
230

COPYRIGHT

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

AUTHOR

236       Wes Hardaker <hardaker@users.sourceforge.net>
237