File: //proc/self/root/usr/share/doc/bind9-doc/arm/chapter9.html
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>9. Troubleshooting — BIND 9 9.18.39-0ubuntu0.24.04.2-Ubuntu documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=86f27845" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=9ab34431" />
<script src="_static/jquery.js?v=8dae8fb0"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=9d4ae9d2"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="10. Building BIND 9" href="chapter10.html" />
<link rel="prev" title="8. Configuration Reference" href="reference.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
BIND 9
</a>
<div class="version">
9.18.39-0ubuntu0.24.04.2-Ubuntu
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="chapter1.html">1. Introduction to DNS and BIND 9</a></li>
<li class="toctree-l1"><a class="reference internal" href="chapter2.html">2. Resource Requirements</a></li>
<li class="toctree-l1"><a class="reference internal" href="chapter3.html">3. Configurations and Zone Files</a></li>
<li class="toctree-l1"><a class="reference internal" href="chapter4.html">4. Name Server Operations</a></li>
<li class="toctree-l1"><a class="reference internal" href="chapter5.html">5. DNSSEC</a></li>
<li class="toctree-l1"><a class="reference internal" href="chapter6.html">6. Advanced Configurations</a></li>
<li class="toctree-l1"><a class="reference internal" href="chapter7.html">7. Security Configurations</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">8. Configuration Reference</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">9. Troubleshooting</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#common-problems">9.1. Common Problems</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#it-s-not-working-how-can-i-figure-out-what-s-wrong">9.1.1. It’s Not Working; How Can I Figure Out What’s Wrong?</a></li>
<li class="toctree-l3"><a class="reference internal" href="#edns-compliance-issues">9.1.2. EDNS Compliance Issues</a></li>
<li class="toctree-l3"><a class="reference internal" href="#inspecting-encrypted-dns-traffic">9.1.3. Inspecting Encrypted DNS Traffic</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#incrementing-and-changing-the-serial-number">9.2. Incrementing and Changing the Serial Number</a></li>
<li class="toctree-l2"><a class="reference internal" href="#where-can-i-get-help">9.3. Where Can I Get Help?</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="chapter10.html">10. Building BIND 9</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Appendices</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="notes.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="dnssec-guide.html">DNSSEC Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="history.html">A Brief History of the DNS and BIND</a></li>
<li class="toctree-l1"><a class="reference internal" href="general.html">General DNS Reference Information</a></li>
<li class="toctree-l1"><a class="reference internal" href="manpages.html">Manual Pages</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">BIND 9</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active"><span class="section-number">9. </span>Troubleshooting</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/chapter9.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="troubleshooting">
<span id="id1"></span><h1><span class="section-number">9. </span>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Link to this heading"></a></h1>
<section id="common-problems">
<span id="id2"></span><h2><span class="section-number">9.1. </span>Common Problems<a class="headerlink" href="#common-problems" title="Link to this heading"></a></h2>
<section id="it-s-not-working-how-can-i-figure-out-what-s-wrong">
<h3><span class="section-number">9.1.1. </span>It’s Not Working; How Can I Figure Out What’s Wrong?<a class="headerlink" href="#it-s-not-working-how-can-i-figure-out-what-s-wrong" title="Link to this heading"></a></h3>
<p>The best solution to installation and configuration issues is to
take preventive measures by setting up logging files beforehand. The
log files provide hints and information that can be used to
identify anything that went wrong and fix the problem.</p>
</section>
<section id="edns-compliance-issues">
<h3><span class="section-number">9.1.2. </span>EDNS Compliance Issues<a class="headerlink" href="#edns-compliance-issues" title="Link to this heading"></a></h3>
<p>EDNS (Extended DNS) is a standard that was first specified in 1999. It
is required for DNSSEC validation, DNS COOKIE options, and other
features. There are broken and outdated DNS servers and firewalls still
in use which misbehave when queried with EDNS; for example, they may
drop EDNS queries rather than replying with FORMERR. BIND and other
recursive name servers have traditionally employed workarounds in this
situation, retrying queries in different ways and eventually falling
back to plain DNS queries without EDNS.</p>
<p>Such workarounds cause unnecessary resolution delays, increase code
complexity, and prevent deployment of new DNS features. In February
2019, all major DNS software vendors removed these
workarounds; see <a class="reference external" href="https://www.dnsflagday.net/2019/">https://www.dnsflagday.net/2019/</a> for further details. This change
was implemented in BIND as of release 9.14.0.</p>
<p>As a result, some domains may be non-resolvable without manual
intervention. In these cases, resolution can be restored by adding
<a class="reference internal" href="reference.html#namedconf-statement-server" title="namedconf-statement-server"><code class="xref namedconf namedconf-ref docutils literal notranslate"><span class="pre">server</span></code></a> clauses for the offending servers, or by specifying <code class="docutils literal notranslate"><span class="pre">edns</span> <span class="pre">no</span></code> or
<code class="docutils literal notranslate"><span class="pre">send-cookie</span> <span class="pre">no</span></code>, depending on the specific noncompliance.</p>
<p>To determine which <a class="reference internal" href="reference.html#namedconf-statement-server" title="namedconf-statement-server"><code class="xref namedconf namedconf-ref docutils literal notranslate"><span class="pre">server</span></code></a> clause to use, run the following commands
to send queries to the authoritative servers for the broken domain:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">dig</span> <span class="n">soa</span> <span class="o"><</span><span class="n">zone</span><span class="o">></span> <span class="o">@<</span><span class="n">server</span><span class="o">></span> <span class="o">+</span><span class="n">dnssec</span>
<span class="n">dig</span> <span class="n">soa</span> <span class="o"><</span><span class="n">zone</span><span class="o">></span> <span class="o">@<</span><span class="n">server</span><span class="o">></span> <span class="o">+</span><span class="n">dnssec</span> <span class="o">+</span><span class="n">nocookie</span>
<span class="n">dig</span> <span class="n">soa</span> <span class="o"><</span><span class="n">zone</span><span class="o">></span> <span class="o">@<</span><span class="n">server</span><span class="o">></span> <span class="o">+</span><span class="n">noedns</span>
</pre></div>
</div>
<p>If the first command fails but the second succeeds, the server most
likely needs <code class="docutils literal notranslate"><span class="pre">send-cookie</span> <span class="pre">no</span></code>. If the first two fail but the third
succeeds, then the server needs EDNS to be fully disabled with
<code class="docutils literal notranslate"><span class="pre">edns</span> <span class="pre">no</span></code>.</p>
<p>Please contact the administrators of noncompliant domains and encourage
them to upgrade their broken DNS servers.</p>
</section>
<section id="inspecting-encrypted-dns-traffic">
<h3><span class="section-number">9.1.3. </span>Inspecting Encrypted DNS Traffic<a class="headerlink" href="#inspecting-encrypted-dns-traffic" title="Link to this heading"></a></h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This feature requires support from the cryptographic library that
BIND 9 is built against. For OpenSSL, version 1.1.1 or newer is
required (use <a class="reference internal" href="manpages.html#cmdoption-named-V"><code class="xref std std-option docutils literal notranslate"><span class="pre">named</span> <span class="pre">-V</span></code></a> to check).</p>
</div>
<p>By definition, TLS-encrypted traffic (e.g. DNS over TLS, DNS over HTTPS)
is opaque to packet sniffers, which makes debugging problems with
encrypted DNS close to impossible. However, <a class="reference external" href="https://www.wireshark.org/">Wireshark</a> offers a
<a class="reference external" href="https://wiki.wireshark.org/TLS#tls-decryption">solution</a> to this problem by being able to read key log files. In order
to make <a class="reference internal" href="manpages.html#std-iscman-named"><code class="xref std std-iscman docutils literal notranslate"><span class="pre">named</span></code></a> prepare such a file, set the <code class="docutils literal notranslate"><span class="pre">SSLKEYLOGFILE</span></code>
environment variable to either:</p>
<ul>
<li><p>the string <code class="docutils literal notranslate"><span class="pre">config</span></code> (<code class="docutils literal notranslate"><span class="pre">SSLKEYLOGFILE=config</span></code>); this requires
defining a <a class="reference internal" href="reference.html#namedconf-statement-logging" title="namedconf-statement-logging"><code class="xref any namedconf namedconf-ref docutils literal notranslate"><span class="pre">logging</span></code></a> <a class="reference internal" href="reference.html#namedconf-statement-channel" title="namedconf-statement-channel"><code class="xref any namedconf namedconf-ref docutils literal notranslate"><span class="pre">channel</span></code></a> which will
handle messages belonging to the <code class="docutils literal notranslate"><span class="pre">sslkeylog</span></code> category,</p></li>
<li><p>the path to the key file to write (<code class="docutils literal notranslate"><span class="pre">SSLKEYLOGFILE=/path/to/file</span></code>);
this is equivalent to the following <a class="reference internal" href="reference.html#namedconf-statement-logging" title="namedconf-statement-logging"><code class="xref any namedconf namedconf-ref docutils literal notranslate"><span class="pre">logging</span></code></a> configuration:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span> <span class="n">default_sslkeylogfile</span> <span class="p">{</span>
<span class="n">file</span> <span class="s2">"$</span><span class="si">{SSLKEYLOGFILE}</span><span class="s2">"</span> <span class="n">versions</span> <span class="mi">10</span> <span class="n">size</span> <span class="mi">100</span><span class="n">m</span> <span class="n">suffix</span> <span class="n">timestamp</span><span class="p">;</span>
<span class="p">};</span>
<span class="n">category</span> <span class="n">sslkeylog</span> <span class="p">{</span>
<span class="n">default_sslkeylogfile</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When using <code class="docutils literal notranslate"><span class="pre">SSLKEYLOGFILE=config</span></code>, augmenting the log channel
output using options like <a class="reference internal" href="reference.html#namedconf-statement-print-time" title="namedconf-statement-print-time"><code class="xref any namedconf namedconf-ref docutils literal notranslate"><span class="pre">print-time</span></code></a> or <a class="reference internal" href="reference.html#namedconf-statement-print-severity" title="namedconf-statement-print-severity"><code class="xref any namedconf namedconf-ref docutils literal notranslate"><span class="pre">print-severity</span></code></a> is
strongly discouraged as it will likely make the key log file
unusable.</p>
</div>
<p>When the <code class="docutils literal notranslate"><span class="pre">SSLKEYLOGFILE</span></code> environment variable is set, each TLS
connection established by <a class="reference internal" href="manpages.html#std-iscman-named"><code class="xref std std-iscman docutils literal notranslate"><span class="pre">named</span></code></a> (both incoming and outgoing) causes
about 1 kilobyte of data to be written to the key log file.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Due to the limitations of the current logging code in BIND 9,
enabling TLS pre-master secret logging adversely affects <a class="reference internal" href="manpages.html#std-iscman-named"><code class="xref std std-iscman docutils literal notranslate"><span class="pre">named</span></code></a>
performance.</p>
</div>
</section>
</section>
<section id="incrementing-and-changing-the-serial-number">
<h2><span class="section-number">9.2. </span>Incrementing and Changing the Serial Number<a class="headerlink" href="#incrementing-and-changing-the-serial-number" title="Link to this heading"></a></h2>
<p>Zone serial numbers are just numbers — they are not date-related. However, many
people set them to a number that represents a date, usually of the
form YYYYMMDDRR. Occasionally they make a mistake and set the serial number to a
date in the future, then try to correct it by setting it to the
current date. This causes problems because serial numbers are used to
indicate that a zone has been updated. If the serial number on the secondary
server is lower than the serial number on the primary, the secondary server
attempts to update its copy of the zone.</p>
<p>Setting the serial number to a lower number on the primary server than the one
on the secondary server means that the secondary will not perform updates to its
copy of the zone.</p>
<p>The solution to this is to add 2147483647 (2^31-1) to the number, reload
the zone and make sure all secondaries have updated to the new zone serial
number, then reset it to the desired number and reload the
zone again.</p>
</section>
<section id="where-can-i-get-help">
<span id="more-help"></span><h2><span class="section-number">9.3. </span>Where Can I Get Help?<a class="headerlink" href="#where-can-i-get-help" title="Link to this heading"></a></h2>
<p>The BIND-users mailing list, at <a class="reference external" href="https://lists.isc.org/mailman/listinfo/bind-users">https://lists.isc.org/mailman/listinfo/bind-users</a>, is an excellent resource for
peer user support. In addition, ISC maintains a Knowledgebase of helpful articles
at <a class="reference external" href="https://kb.isc.org">https://kb.isc.org</a>.</p>
<p>Internet Systems Consortium (ISC) offers annual support agreements
for BIND 9, ISC DHCP, and Kea DHCP.
All paid support contracts include advance security notifications; some levels include
service level agreements (SLAs), premium software features, and increased priority on bug fixes
and feature requests.</p>
<p>Please contact <a class="reference external" href="mailto:info%40isc.org">info<span>@</span>isc<span>.</span>org</a> or visit
<a class="reference external" href="https://www.isc.org/contact/">https://www.isc.org/contact/</a> for more information.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="reference.html" class="btn btn-neutral float-left" title="8. Configuration Reference" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="chapter10.html" class="btn btn-neutral float-right" title="10. Building BIND 9" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2025, Internet Systems Consortium.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>