From: Ondřej Surý <ondrej@isc.org>
Date: Thu, 26 Feb 2026 16:13:04 +0000 (+0100)
Subject: Expand blackhole description
X-Git-Tag: v9.21.20~9^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2b23c7011e0b6f2a2deaca17eb90c34386bb027d;p=thirdparty%2Fbind9.git

Expand blackhole description

Clarify the behavior of negated addresses within the `blackhole`
statement to prevent common configuration misunderstandings.
---

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index 5c09f64a3fc..b3d746d5b14 100644
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -3069,6 +3069,18 @@ for details on how to specify IP address lists.
    from or or cannot use to resolve a query. Queries from these addresses are not
    responded to. The default is ``none``.
 
+   When configuring this list, note that BIND evaluates Access Control Lists
+   sequentially (first match wins). A common misconception is that the directive
+   ``!address;`` blocks everything except that address. In reality, it only
+   explicitly exempts ``address`` from the blackhole; all other IP addresses
+   reach the end of the list without matching, meaning they are also not
+   blackholed.
+
+   To successfully blackhole all traffic *except* specific addresses, you must
+   explicitly catch the remaining traffic with ``any;`` at the end of the list.
+   For example: ``!address; any;``
+
+
 .. namedconf:statement:: no-case-compress
    :tags: server
    :short: Specifies a list of addresses that require case-insensitive compression in responses.