add documentation

diff --git a/CHANGES b/CHANGES
index a17df7937add84a5942227d290d943ddc6c4bb75..5e55faa14aaff1d077a0b98ca30027c3c8b31b9b 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,10 @@
+5029.  [func]          Workarounds for servers that misbehave when queried
+                       with EDNS have been removed, because these broken
+                       servers and the workarounds for their noncompliance
+                       cause unnecessary delays, increase code complexity,
+                       and prevent deployment of new DNS features. See
+                       https://dnsflagday.net for further details. [GL #150]
+
 5028.  [bug]           Spread the initial RRSIG expiration times over the
                        entire working sig-validity-interval when signing a
                        zone in named to even out re-signing and transfer

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index 4530c0876eda375a2864442b2c21e2e5a1f55fbe..453b7a43bd721abb1a0757168ff1f27eeeac7cd4 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -17139,7 +17139,58 @@ allow-query { !{ !10/8; any; }; key example; };
            source of hints and information that can be used to figure out
            what went wrong and how to fix the problem.
          </para>
+       </section>
 
+       <section><info><title>EDNS compliance issues</title></info>
+         <para>
+           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.
+         </para>
+         <para>
+           Such workarounds cause unnecessary resolution delays,
+           increase code complexity, and prevent deployment of new DNS
+           features. As of February 2019, all major DNS software vendors
+           have agreed to remove these workarounds; see
+           <link xmlns:xlink="http://www.w3.org/1999/xlink"
+             xlink:href="https://dnsflagday.net">https://dnsflagday.net</link>
+           for further details. This change was implemented in BIND
+           as of release 9.14.0.
+         </para>
+         <para>
+           As a result, some domains may be non-resolvable without manual
+           intervention.  In these cases, resolution can be restored by
+           adding <command>server</command> clauses for the offending
+           servers, specifying <command>edns no</command> or
+           <command>send-cookie no</command>, depending on the specific
+           noncompliance.
+         </para>
+         <para>
+           To determine which <command>server</command> clause to use,
+           run the following commands to send queries to the authoritative
+           servers for the broken domain:
+         </para>
+  <literallayout>
+           dig soa &lt;zone&gt; @&lt;server&gt; +dnssec
+           dig soa &lt;zone&gt; @&lt;server&gt; +dnssec +nocookie
+           dig soa &lt;zone&gt; @&lt;server&gt; +noedns
+  </literallayout>
+         <para>
+           If the first command fails but the second succeeds, the
+           server most likely needs <command>send-cookie no</command>.
+           If the first two fail but the third succeeds, then the server
+           needs EDNS to be fully disabled with <command>edns no</command>.
+         </para>
+         <para>
+           Please contact the administrators of noncompliant domains
+           and encourage them to upgrade their broken DNS servers.
+         </para>
        </section>
       </section>
       <section><info><title>Incrementing and Changing the Serial Number</title></info>

diff --git a/doc/arm/notes.xml b/doc/arm/notes.xml
index f3c4e2017ad1a7df2d5d918013a933f0f51871c0..f326885798c94cbc338b11122be591f082c4ba86 100644 (file)
--- a/doc/arm/notes.xml
+++ b/doc/arm/notes.xml
@@ -156,6 +156,47 @@
 
   <section xml:id="relnotes_removed"><info><title>Removed Features</title></info>
     <itemizedlist>
+      <listitem>
+       <para>
+         Workarounds for servers that misbehave when queried with EDNS
+         have been removed, because these broken servers and the
+         workarounds for their noncompliance cause unnecessary delays,
+         increase code complexity, and prevent deployment of new DNS
+         features. See <link xmlns:xlink="http://www.w3.org/1999/xlink"
+           xlink:href="https://dnsflagday.net">https://dnsflagday.net</link>
+         for further details.
+       </para>
+       <para>
+         In particular, resolution will no longer fall back to
+         plain DNS when there was no response from an authoritative
+         server.  This will cause some domains to become non-resolvable
+         without manual intervention.  In these cases, resolution can
+         be restored by adding <command>server</command> clauses for the
+         offending servers, specifying <command>edns no</command> or
+         <command>send-cookie no</command>, depending on the specific
+         noncompliance.
+       </para>
+       <para>
+         To determine which <command>server</command> clause to use, run
+         the following commands to send queries to the authoritative
+         servers for the broken domain:
+       </para>
+<literallayout>
+         dig soa &lt;zone&gt; @&lt;server&gt; +dnssec
+         dig soa &lt;zone&gt; @&lt;server&gt; +dnssec +nocookie
+         dig soa &lt;zone&gt; @&lt;server&gt; +noedns
+</literallayout>
+       <para>
+         If the first command fails but the second succeeds, the
+         server most likely needs <command>send-cookie no</command>.
+         If the first two fail but the third succeeds, then the server
+         needs EDNS to be fully disabled with <command>edns no</command>.
+       </para>
+       <para>
+         Please contact the administrators of noncompliant domains
+         and encourage them to upgrade their broken DNS servers. [GL #150]
+       </para>
+      </listitem>
       <listitem>
        <para>
          Previously, it was possible to build BIND without thread support