User guide
From DNSdoctor
Table of contents |
Introduction
The DNS is a critical resource for every network application (mail, web, ...), and so it is quite important to ensure that a zone or domain name is correctly configured.
The DNS has been designed to be robust to errors, as a result you can pervert it so to have a working DNS even if you misconfigured it. But in such a case, a single additional error can result in your zone completely disappearing, and this additional error is not necessarily your fault!
DNSdoctor will help you solving misconfigurations or inconsistencies by looking for potential errors and give you a description of the problem and refere you to RFC (http://www.rfc-editor.org/) or other documents; but of course it is still recommanded that you have some basic knowledge of how the DNS works.
Input
Common settings
Environment variables
- LANG
- Specify the lang and eventually the encoding to use to display messages. For examples: fr, fr_CA, fr.latin1, fr_CA.utf8, ...
- DDOC_CONFIG_DIR
- Directory where the configuration file and the different profiles are located.
- DDOC_CONFIG_FILE
- Name of the configuration file to use (defaul to dnsdoctor.conf), it is override by the --config option.
- DDOC_LOCALIZATION_DIR
- Directory where all the localization files are located.
- DDOC_TEST_DIR
- Directory where all the tests are located, it is override by the --testdir option.
- DDOC_HTML_PATH
- Path relative to the web server to use when generating HTML pages.
- DDOC_DEBUG
- The variable as the same effect as the debug parameter, but its main advantage is that it is taken into account from the beginning of the program.
- DDOC_INPUT
- The variable as the same effect as the undocumented INPUT parameter, it allows to chose the input interface used by DNSdoctor, the currently supported values are: cli, cgi, inetd and gtk (requires GTK/ruby binding). But other interfaces doesn’t accept the same parameters as the one described here.
- DDOC_IP_STACK
- Restrict the IP stack available to IPv4 or IPv6, for that set it respectively to 4 or 6. This is particularly useful if you have an IPv6 stack on your computer but don’t have the connectivity, in that case define
DDOC_IP_STACK=4
.
- DDOC_XML_PARSER
- If ruby-libxml is installed, this parser will be used instead of rexml for speed improvement, but you can force the use of rexml by setting DDOC_XML_PARSER to rexml.
NOTE: The following variables are mainly useful when it is not possible for the user to specify alternative value with the selected input interface: DDOC_CONFIG_DIR, DDOC_CONFIG_FILE, DDOC_LOCALIZATION_DIR, DDOC_TEST_DIR. Such a case happen when using the cgi interface, and you don’t want the user to read an arbitrary configuration file, but as the provider of the service you want to use another configuration.
Exit status
The following exit status can be reported by DNSdoctor:
- 0
- Everything went fine, no fatal errors were reported, the domain configuration is correct.
- 1
- The program completed but some tests failed with a fatal severity, the domain is NOT correctly configured.
- 2
- The program completed but some tests failed due with a fatal severity due to timeout occuring, the domain has been considered as NOT correctly configured, but you could want to check again later. This is currently not implemented.
- 3
- The user aborted the program before it’s completion.
- 4
- An error which is not directly related to the tests performed has occured (ie: something went wrong).
- 9
- The user (you?) didn’t bother reading the man page...
Configuration files
- /usr/local/etc/dnsdoctor/dnsdoctor.conf
- The default configuration file.
- /usr/local/etc/dnsdoctor/*.profile
- The test sequence to use for different domains.
- /usr/local/libexec/dnsdotor/test/
- Contains the code of the tests performed by DNSdoctor.
- /usr/local/libexec/dnsdoctor/locale/
- Contains the different translations.
- /usr/local/libexec/dnsdoctor/www/
- Contains a website sample for the web interface.
Command Line Interface (CLI)
NOTE: It doesn’t necessary make sense to combine some options together, if that case happens the most recent option will be taken into account, silently discarding the others.
- --lang lang
- Select another language (en, fr, ...). The syntax is the same as for the environment variable LANG.
- --debug, -d lvl
- Select the debugging messages to print or activate debugging code. This parameter will override the value of the environment variable DDOC_DEBUG. The available options are:
0x0001 : Initialisation 0x0002 : Localization / Internationalisation 0x0004 : Configuration 0x0008 : Autoconf 0x0010 : Loading tests 0x0020 : Tests performed 0x0040 : Debugging messages from tests 0x0400 : Information about cached object 0x0800 : Debugger itself 0x1000 : Crazy Debug, don’t try this at home! 0x2000 : NResolv module debugging messages 0x4000 : Disable caching 0x8000 : Don’t try to rescue exceptions
- --help, -h
- Show a short description of the different options available in DNSdoctor.
- --version, -V
- Display the version and exit.
- --config, -c filename
- Specify the location of the configuration file (default is dnsdoctor.conf).
- --testdir directory
- Location of the directory holding the tests definition.
- --profile, -P profilename
- Force uses of profile profilename.
- --category, -C catlist
- Limit the test to perform to the categories specified by catlist. The syntax for the catgory description is as follow: allow=[+|] disallow=[-|!] subcomponent=: separator=, ex: dns:soa,!dns,+ don’t perform DNS tests that are not SOA related
- --test, -T testname
- testname is the test to perform. In this case failing to pass the test is considered as fatal.
- --testlist
- List all the tests available.
- --testdesc desctype
- Give a description of the test, the possible values for desctype are name, success, failure, explanation.
- --resolver, -r resolver
- Resolver to use (only IP address is accepted) for finding the information about the tested zone, by default the name servers used are the one specified in /etc/resolv.conf. Note that for finding the name servers the zone should already have been delegated.
- --ns, -n nslist
- List of nameservers for the domain. Nameservers name are separated by a semicolon, the name can be followed by the equal sign and its IP addresses separated by a colon. This can give the following example: ns1;ns2=ip1,ip2;ns3=ip3
- --quiet, -q
- Don’t display extra titles.
- --one, -1
- Only display the most relevant message in a compact format.
- --tagonly, -g
- Display only tag. This option should be used for scripting.
- --verbose, -v options
- Display extra information, they can be prefix by ’-’ or ’!’ to remove the effect, available options are:
- intro, i
- Print a short summary about the domain name and its nameservers.
- testname, n
- Print the name of the test when reporting a test status.
- explain, x
- Print an explanation for failed tests (reference to RFC, ...).
- details, d
- Print a detailed description of the failure (name or value of the resource involved).
- reportok, o
- Report test even if they passed.
- fatalonly, f
- Only print fatal errors.
- testdesc, t
- Print the test description before performing it.
- counter, c
- Display a test progression bar (this option is not always available according to the output media).
- NOTE:: testdesc and counter are mutually exclusive.
- --output, -o options
- Output rendering/format selection, avalaible options are:
- byseverity, bs [default]
- Output is sorted/merged by severity.
- byhost, bh
- Output is sorted/merged by host.
- text, t [default]
- Output plain text.
- html, h
- Output HTML.
- gtk, g
- Use a GTK window to display the result (requires GTK binding).
- NOTE: The following set are mutually exclusive: [byseverity|byhost] and [text|html].
- --error, -e options
- Behaviour in case of error, available options are:
- allfatal, af
- All error are considered as fatals.
- allwarning, aw
- All error are considered as warnings.
- dfltseverity, ds [default]
- Use the severity associated with the test.
- stop, s [default]
- Stop on the first fatal error. WARNING: the current implementation stop on the first error but for each server.
- nostop, ns
- Never stop (even on fatal error). This generally result in a lot of errors or unexpected results due to the previous fatal error.
- NOTE: The following set are mutually exclusive: [allfatal|allwarning|dfltseverity] and [stop|nostop].
- --transp, -t options
- Transport/routing layer selection, available options are:
- ipv4, 4 [default]
- Use the IPv4 routing protocol.
- ipv6, 6 [default]
- Use the IPv6 routing protocol.
- udp, u
- Use the UDP transport layer.
- tcp, t
- Use the TCP transport layer.
- std, s [default]
- Use the UDP with fallback to TCP for truncated messages.
- NOTE: udp, tcp and std are mutually exclusive.
- --ipv4, -4
- Only check the zone with IPv4 connectivity.
- --ipv6, -6
- Only check the zone with IPv6 connectivity.
- --preset name
- Use of a preset configuration defined in the dnsdoctor.conf configuration file.
- --option options
- Set extra options. The syntax is: -,-opt,opt,opt=foo
Examples
- Test the domain_name with IPv6 only connectivity, print a summary information about the tested domain as well as explanations and details of failed tests.
dnsdoctor -6 --verbose=i,x,d domain_name
- Work in batch mode, where domains are read from stdin, a progress bar indicates how many tests remain, and only short report is written.
dnsdoctor -v c -1 -B -
- Ask for the ’error’ message associated with the test ’soa’.
dnsdoctor --testdesc error -T soa
- Only print tests which have failed and the result (succeed/failed), this would be ideal for giving people, through email for example, a short description of why their domains are not correctly configured.
dnsdoctor -q -vn,d,x,f domain_name
- If you want to test your domain, you will certainly like to use these parameters (the use of IPv4 only as been forced because now people have computer with IPv6 stack but very few have the IPv6 connectivity, so autodetection will failed).
dnsdoctor -4 -vi,x,d,c domain_name
Common Gateway Interface (CGI)
Follows a quick summary of the possible parameters, for more information see the DNSdoctor documentation.
parameters:
- lang = [ fr | en | ... ] - quiet - one - option - verbose = [ i|intro, n|testname, x|explain, d|details, t|testdesc, c|counter, o|reportok ] - intro - testname - explain - details - progress = [ t|testdesc | c|counter ] - reportok - fatalonly - output = [ bs|byseverity, bh|byhost, t|text, h|html ] - report = bs|byseverity | bh|byhost - format = h|html | text - error = [ af|allfatal, aw|allwarning, ds|dfltseverity, s|stop, ns|nostop ] - errorlvl = [ af|allfatal | aw|allwarning | ds|dfltseverity ] - dontstop - transp = [ ipv4, ipv6, udp, tcp, std ] - transp3 = [ ipv4, ipv6 ] - transp4 = [ udp | tcp | std ] - profile = profilename - category = cat1,!cat2:subcat1,cat2,!cat3,+ - chkmail (!mail) - chkrir (!rir) - chkzone (!dns:axfr) - ns = ns1=ip1,ip2;ns2=ip3;ns3 (WARNING: in URL '%3b' should be used instead of ';') - ns0 .. nsX = nameserver name - ips0 .. ipsX = coma separated ip addresses - zone = zone to test
Examples
All the following examples test the zone afnic.fr, a summary of the nameservers and there addresses will be displayed, as well as the list of the test being performed:
- Specify that we want to test IPv4 and IPv6, and the DNS query will be made using UDP with a fallback on TCP in case of problems
?zone=afnic.fr&intro&progress=testdesc&transp=ipv4,ipv6,std
- The list of nameserver is explicitely given
?zone=afnic.fr&verbose=i,t&ns=ns1.nic.fr%3bns2.nic.fr%3bns3.nic.fr
- The list of nameserver is explicitely given as well as some IP addresses
?zone=afnic.fr&verbose=i,t&ns=ns1.nic.fr=192.93.0.1&ns=ns2.nic.fr&ns=bns3.nic.fr
GTK
Output
Text
The report generated by DNSdoctor is as follow
s> error message : Details about the error, incriminated values are shown. `..... .. .. . . . | Ref: reference (with URL if possible) | The interesting part of the reference is quoted. `----- -- -- - - -
's' is replaced by the first character of the severity: informationnal, warning or fatal.
HTML
Configuration and Profiles
Config
The file dnsdoctor.conf allows you define the behaviour of DNSdoctor.
Presets
You can define presets, they are a convenient way to avoid passing numerous options to DNSdoctor, especially if you are always using the same set of options. The preset called default is automatically applied if none is explicitly requested. Note that the cgi and inetd input modes are not supporting preset values and are therefore ignored.
<preset name="presetname"> <param name="paramname1" value="paramvalue1"/> ... <param name="paramnameN" value="paramvalueN"/> </preset>
Constants
Constants that are used by the checks done in DNSdoctor must be defined, sensible default value are provided when possible in the dnsdoctor.conf file and can be overwritten by the different profiles (ie: *.profile files).
<const name="constname" value="constvalue"/>
It is necessary to take a look at the dnsdoctor.conf file to see if they correctly match your system, for example the ping4 and ping6 which define the command to run to test the connectivity using ICMP.
Domain name mapping
This feature let DNSdoctor automatically select the set of tests to apply according to the parent domain (generally the tld), to do this you need to specify a mapping between a domain (fully qualified) and a profile.
<map zone="zonename" profile="profilename"/>
You need to have a default entry that is defined as follow:
<map zone="." profile="profilename"/>
Profiles
Constants
They are the same as in the configuration file (see Config/Constants).
Rules
There are 4 classes of rules, describing the context in which the checks are applied (note that a class is already attached when writting the code of the check, but need to be specified again here):
- generic
- dont depend from the nameserver neither from their IP addresses.
- nameserver
- only depend from the nameserver name.
- address
- need to be applied for each IP addresses.
- extra
- is not DNS related.
When registering a check, you need to give its severity which can be informationnal, warning or fatal (use the first letter: i, w or f) and a category. A category is as string using ':' (colon) as a separator for subcategories, for example dns:soa; the category will provide an easy way to exclude or include a set of checks.
A case statement is available to provide conditional branching; for example some checking need to be skipped if the server is not allowing recursive queries.
<rules class="classname"> <check name="checkname1" severity="severity1" category="category1"/> ... <check name="checknameN" severity="severityN" category="categoryN"/> <case test="testname"> <when value="value1"> <!-- list of checks --> </when> ... <when value="valueN"> <!-- list of checks --> </when> <else> <!-- list of checks --> </else> </case> </rules>
DTD
The DTD that is used for parsing the configuration file and the profile is listed below, the entry points being config for both.
<!ELEMENT config ((preset*, const*, map*)|profile)> <!ELEMENT preset (param*)> <!ELEMENT param EMPTY> <!ELEMENT const EMPTY> <!ELEMENT map EMPTY> <!ELEMENT check EMPTY> <!ELEMENT profile (const*, rules*)> <!ELEMENT case (when*,else?)> <!ELEMENT rules (check|case)*> <!ELEMENT when (check|case)*> <!ELEMENT else (check|case)*> <!ATTLIST preset name CDATA #REQUIRED> <!ATTLIST param name (verbose|transp|output|error|quiet|one) #REQUIRED value CDATA #REQUIRED> <!ATTLIST const name CDATA #REQUIRED value CDATA #REQUIRED> <!ATTLIST map zone CDATA #REQUIRED profile CDATA #REQUIRED> <!ATTLIST case test CDATA #REQUIRED> <!ATTLIST when value CDATA #REQUIRED> <!ATTLIST check name CDATA #REQUIRED severity (i|f|w) #REQUIRED category CDATA #REQUIRED> <!ATTLIST rules class (generic|address|nameserver|extra) #REQUIRED> <!ATTLIST profile name CDATA #REQUIRED> <!ATTLIST profile longdesc CDATA #REQUIRED>