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 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.