From 232ea3caf0ab4dda9485b26a6d0b5696fc7a8c9b Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 27 Apr 2026 22:01:49 +0200 Subject: [PATCH 1/2] docs(kubo): flag server-profile reverse-proxy gotcha Kubo's `server` profile filters loopback in `Swarm.AddrFilters`, which silently breaks any setup that fronts a `127.0.0.1` listener with a local reverse proxy (a common pattern for `/ws` bootstrappers). Kubo 0.42 will log an explicit ERROR at startup, but ipfs-docs had no on-ramp pointing readers at the override they need to apply, and the existing `server`-profile mention in the quickstart understated what the profile actually does. - `command-line-quick-start.md`: replace the data-center one-liner with a more accurate description (local discovery off, non-globally- routable connections refused) and link to the kubo `server` profile reference, including the reverse-proxy override row. - `troubleshooting-kubo.md`: add a short "A configured Swarm listener appears unreachable" section that quotes the kubo 0.42 ERROR line verbatim and links to the override table. - `nat-configuration.md`: add a tip clarifying that `Addresses.NoAnnounce` (publish-side) and `Swarm.AddrFilters` (connection gate) are different, since the existing example shows both as empty arrays without context. --- docs/how-to/command-line-quick-start.md | 4 +++- docs/how-to/nat-configuration.md | 9 ++++++++- docs/how-to/troubleshooting-kubo.md | 10 ++++++++++ 3 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/how-to/command-line-quick-start.md b/docs/how-to/command-line-quick-start.md index bcf11e5b9..ee4eec993 100644 --- a/docs/how-to/command-line-quick-start.md +++ b/docs/how-to/command-line-quick-start.md @@ -16,11 +16,13 @@ If you have not yet installed Kubo, follow the [Kubo install guide](../install/c `ipfs` stores all its settings and internal data in a directory called _the repository._ Before using Kubo for the first time, you’ll need to initialize the repository. :::tip - - If you are running a Kubo node in a data center, you should initialize IPFS with the `server` profile. Doing so will prevent IPFS from creating data center-internal traffic trying to discover local nodes: + - If you are running Kubo on a public-internet host (data center, VPS, cloud), initialize with the `server` profile. It disables local-network discovery and refuses libp2p connections to and from non-globally-routable address ranges, so the node does not generate discovery traffic that some hosting providers flag as abuse: ```bash ipfs init --profile server ``` + + See the [`server` profile reference](https://github.com/ipfs/kubo/blob/master/docs/config.md#server-profile) for the full filter list, override rows, and the reverse-proxy interaction (a `/ip4/127.0.0.1/tcp/.../ws` listener fronted by a local nginx or Caddy proxy needs one of those overrides to keep working). - Be careful using `sudo` on Unix platforms (including macOS)! Running `sudo ipfs init` will create the repository for the `root` user, instead of your local user account. Kubo doesn't require root privileges, so it's best to run all `ipfs` commands as a regular user! ::: diff --git a/docs/how-to/nat-configuration.md b/docs/how-to/nat-configuration.md index c146f4b52..b689104f5 100644 --- a/docs/how-to/nat-configuration.md +++ b/docs/how-to/nat-configuration.md @@ -98,7 +98,14 @@ In this step, you will update your Kubo configuration to set `Swarm.AppendAnnoun "API": "/ip4/127.0.0.1/tcp/5001", "Gateway": "/ip4/127.0.0.1/tcp/8080" }, - ``` + ``` + + :::tip + `Addresses.NoAnnounce` and [`Swarm.AddrFilters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#swarmaddrfilters) are not the same thing: + + - `Addresses.NoAnnounce` is a publish-side filter. It strips matching addresses from what other peers learn about you. Use it to hide LAN or loopback addresses from your DHT self-record. + - `Swarm.AddrFilters` is a connection gate. It refuses libp2p dial and accept on matching addresses. Putting loopback here will also break a local reverse proxy talking to Kubo on `127.0.0.1`. + ::: 1. Update `AppendAnnounce`, where `` is your public IP address and `` is the port number set in the previous step: diff --git a/docs/how-to/troubleshooting-kubo.md b/docs/how-to/troubleshooting-kubo.md index 8c618adaa..6ea944110 100644 --- a/docs/how-to/troubleshooting-kubo.md +++ b/docs/how-to/troubleshooting-kubo.md @@ -155,6 +155,16 @@ To see the multiaddr used for the connection run: ipfs swarm peers -v | grep ``` +## A configured Swarm listener appears unreachable + +If a listener you put in [`Addresses.Swarm`](https://github.com/ipfs/kubo/blob/master/docs/config.md#addressesswarm) does not work and Kubo logs an ERROR like + +``` +Addresses.Swarm listener "/ip4/127.0.0.1/tcp/8081/ws" matches Swarm.AddrFilters rule "/ip4/127.0.0.0/ipcidr/8", so Kubo rejects every incoming connection to it. Remove "/ip4/127.0.0.0/ipcidr/8" from Swarm.AddrFilters to allow connections to this listener. +``` + +(or the matching `Addresses.NoAnnounce` variant) at startup, the gate or announcement filter you configured covers that listener. The most common trigger is applying the [`server` profile](https://github.com/ipfs/kubo/blob/master/docs/config.md#server-profile) while keeping a `127.0.0.1` listener fronted by a local reverse proxy (nginx, Caddy). Remove the offending CIDR from the field named in the log line. The kubo [`server` profile override table](https://github.com/ipfs/kubo/blob/master/docs/config.md#overriding-specific-entries) lists the recommended removals for the common cases (multiple loopback daemons, LAN peering, Tailscale or other CGNAT overlays, IPv6 ULA mesh, Yggdrasil, NAT64). + ## Go debugging When you see ipfs doing something (using lots of CPU, memory, or otherwise being weird), the first thing you want to do is gather all the relevant profiling information. From 6c1dd75c2aefb8968e6ebde91850c07bf85cd863 Mon Sep 17 00:00:00 2001 From: guillaumemichel Date: Thu, 30 Apr 2026 16:29:18 +0200 Subject: [PATCH 2/2] docs(vale): allow "Tailscale" in spelling ignore list --- .github/styles/pln-ignore.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt index 7b6525df9..16aec32c0 100644 --- a/.github/styles/pln-ignore.txt +++ b/.github/styles/pln-ignore.txt @@ -303,6 +303,7 @@ sys systemd sztandera takedown +Tailscale testground testnet toolkits