docs: clarify denylist scope vs routing layer (#11320)
denylists only block content retrieval and local IPNS resolution. they do not stop a DHT server from storing or serving provider and IPNS records for denied keys on behalf of other peers, and they do not gate /routing/v1/ responses. document this explicitly and point operators at Routing.Type=autoclient as the way to opt out of acting as a routing intermediary for blocked content. Closes #11317 Closes #11318 Closes #11319 these issues track the implementation work to push denylists into the kad-dht provider store, the IPNS validator and pubsub path, and the /routing/v1/ HTTP layer. until that lands, autoclient is the only operator-facing knob with the same effect, so the docs need to say so.
Marcin Rataj committed
May 6, 2026 at 12:06 UTC
aef5750ba25cdf3359c44ff9c299ce01ac2acbed
2 files changed
+33
-1
docs/config.md
+6
-1
@@ -2906,7 +2906,12 @@ Controls how your node discovers content and peers on the network.
2906
when reachable from the public internet.
2907
2908
- **`autoclient`**: Same as `auto`, but never runs a DHT server.
2909
- Use this if your node is behind a firewall or NAT.
2909
+ Use this if your node is behind a firewall or NAT, or if you run a
2910
+ [content denylist](https://github.com/ipfs/kubo/blob/master/docs/content-blocking.md)
2911
+ and do not want to store or serve routing records (provider records,
2912
+ IPNS records) for denied keys on behalf of other peers. See
2913
+ [Scope of denylists](https://github.com/ipfs/kubo/blob/master/docs/content-blocking.md#scope-of-denylists)
2914
+ for why this matters.
2915
2916
- **`dht`**: Uses only the Amino DHT (no HTTP routers). Automatically switches
2917
between client and server mode based on reachability.
docs/content-blocking.md
+27
@@ -39,6 +39,33 @@ End user is not informed about the exact reason, see [How to
39
debug](#how-to-debug) if you need to find out which line of which denylist
40
caused the request to be blocked.
41
42
+## Scope of denylists
43
+
44
+Denylists apply to **content retrieval and serving** by your local node:
45
+
46
+- Bitswap: your node neither requests blocked blocks from peers nor serves them to peers.
47
+- Gateway and CLI: requests for a denied CID return an error (HTTP 410 Gone from the gateway).
48
+- IPNS resolution: your node refuses to resolve a denied IPNS name locally.
49
+
50
+Denylists do **not** apply to the routing system. If your node runs as a DHT server (the default with `Routing.Type=auto` once your node is publicly reachable), it can still:
51
+
52
+- Accept and store provider records (`ADD_PROVIDER`) for denied CIDs from other peers, and return them on `GET_PROVIDERS`.
53
+- Accept and store IPNS records for denied names from other peers, and serve them on `GetValue`.
54
+- Forward IPNS records over pubsub when [`Ipns.UsePubsub`](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsusepubsub) is enabled.
55
+- Surface those records over the [`/routing/v1/`](https://specs.ipfs.tech/routing/http-routing-v1/) HTTP API when [`Gateway.ExposeRoutingAPI`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) is enabled.
56
+
57
+In short, your node will not fetch or serve the content itself, but as a DHT server it still helps other peers discover providers and resolve names for that content.
58
+
59
+### How to stop facilitating routing for blocked content
60
+
61
+Set [`Routing.Type`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingtype) to `autoclient`:
62
+
63
+```sh
64
+$ ipfs config Routing.Type autoclient
65
+```
66
+
67
+In `autoclient` mode your node only acts as a DHT client. It never runs a DHT server, so it does not store or serve provider records or IPNS records on behalf of other peers.
68
+
69
## Denylist file format
70
71
[NOpfs](https://github.com/ipfs-shipyard/nopfs) supports the format from [IPIP-383](https://specs.ipfs.tech/ipips/ipip-0383/).