1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _troubleshooting: 13 14Troubleshooting 15=============== 16 17.. _common_problems: 18 19Common Problems 20--------------- 21 22It's Not Working; How Can I Figure Out What's Wrong? 23~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 24 25The best solution to installation and configuration issues is to 26take preventive measures by setting up logging files beforehand. The 27log files provide hints and information that can be used to 28identify anything that went wrong and fix the problem. 29 30EDNS Compliance Issues 31~~~~~~~~~~~~~~~~~~~~~~ 32 33EDNS (Extended DNS) is a standard that was first specified in 1999. It 34is required for DNSSEC validation, DNS COOKIE options, and other 35features. There are broken and outdated DNS servers and firewalls still 36in use which misbehave when queried with EDNS; for example, they may 37drop EDNS queries rather than replying with FORMERR. BIND and other 38recursive name servers have traditionally employed workarounds in this 39situation, retrying queries in different ways and eventually falling 40back to plain DNS queries without EDNS. 41 42Such workarounds cause unnecessary resolution delays, increase code 43complexity, and prevent deployment of new DNS features. In February 442019, all major DNS software vendors removed these 45workarounds; see https://dnsflagday.net/2019 for further details. This change 46was implemented in BIND as of release 9.14.0. 47 48As a result, some domains may be non-resolvable without manual 49intervention. In these cases, resolution can be restored by adding 50:namedconf:ref:`server` clauses for the offending servers, or by specifying ``edns no`` or 51``send-cookie no``, depending on the specific noncompliance. 52 53To determine which :namedconf:ref:`server` clause to use, run the following commands 54to send queries to the authoritative servers for the broken domain: 55 56:: 57 58 dig soa <zone> @<server> +dnssec 59 dig soa <zone> @<server> +dnssec +nocookie 60 dig soa <zone> @<server> +noedns 61 62 63If the first command fails but the second succeeds, the server most 64likely needs ``send-cookie no``. If the first two fail but the third 65succeeds, then the server needs EDNS to be fully disabled with 66``edns no``. 67 68Please contact the administrators of noncompliant domains and encourage 69them to upgrade their broken DNS servers. 70 71Inspecting Encrypted DNS Traffic 72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74.. note:: 75 76 This feature requires support from the cryptographic library that 77 BIND 9 is built against. For OpenSSL, version 1.1.1 or newer is 78 required (use :option:`named -V` to check). 79 80By definition, TLS-encrypted traffic (e.g. DNS over TLS, DNS over HTTPS) 81is opaque to packet sniffers, which makes debugging problems with 82encrypted DNS close to impossible. However, Wireshark_ offers a 83solution_ to this problem by being able to read key log files. In order 84to make :iscman:`named` prepare such a file, set the ``SSLKEYLOGFILE`` 85environment variable to either: 86 87- the string ``config`` (``SSLKEYLOGFILE=config``); this requires 88 defining a :any:`logging` :any:`channel` which will 89 handle messages belonging to the ``sslkeylog`` category, 90 91- the path to the key file to write (``SSLKEYLOGFILE=/path/to/file``); 92 this is equivalent to the following :any:`logging` configuration: 93 94 :: 95 96 channel default_sslkeylogfile { 97 file "${SSLKEYLOGFILE}" versions 10 size 100m suffix timestamp; 98 }; 99 100 category sslkeylog { 101 default_sslkeylogfile; 102 }; 103 104.. note:: 105 106 When using ``SSLKEYLOGFILE=config``, augmenting the log channel 107 output using options like :any:`print-time` or :any:`print-severity` is 108 strongly discouraged as it will likely make the key log file 109 unusable. 110 111When the ``SSLKEYLOGFILE`` environment variable is set, each TLS 112connection established by :iscman:`named` (both incoming and outgoing) causes 113about 1 kilobyte of data to be written to the key log file. 114 115.. warning:: 116 117 Due to the limitations of the current logging code in BIND 9, 118 enabling TLS pre-master secret logging adversely affects :iscman:`named` 119 performance. 120 121.. _Wireshark: https://www.wireshark.org/ 122.. _solution: https://wiki.wireshark.org/TLS#tls-decryption 123 124Incrementing and Changing the Serial Number 125------------------------------------------- 126 127Zone serial numbers are just numbers — they are not date-related. However, many 128people set them to a number that represents a date, usually of the 129form YYYYMMDDRR. Occasionally they make a mistake and set the serial number to a 130date in the future, then try to correct it by setting it to the 131current date. This causes problems because serial numbers are used to 132indicate that a zone has been updated. If the serial number on the secondary 133server is lower than the serial number on the primary, the secondary server 134attempts to update its copy of the zone. 135 136Setting the serial number to a lower number on the primary server than the one 137on the secondary server means that the secondary will not perform updates to its 138copy of the zone. 139 140The solution to this is to add 2147483647 (2^31-1) to the number, reload 141the zone and make sure all secondaries have updated to the new zone serial 142number, then reset it to the desired number and reload the 143zone again. 144 145.. _more_help: 146 147Where Can I Get Help? 148--------------------- 149The BIND-users mailing list, at https://lists.isc.org/mailman/listinfo/bind-users, is an excellent resource for 150peer user support. In addition, ISC maintains a Knowledgebase of helpful articles 151at https://kb.isc.org. 152 153Internet Systems Consortium (ISC) offers annual support agreements 154for BIND 9, ISC DHCP, and Kea DHCP. 155All paid support contracts include advance security notifications; some levels include 156service level agreements (SLAs), premium software features, and increased priority on bug fixes 157and feature requests. 158 159Please contact info@isc.org or visit 160https://www.isc.org/contact/ for more information. 161