395
396
### `Addresses.NoAnnounce`
397
398
-An array of swarm addresses not to announce to the network.
399
-Takes precedence over `Addresses.Announce` and `Addresses.AppendAnnounce`.
398
+An array of multiaddrs (exact matches or `/ipcidr/` netmasks). Kubo does not
399
+announce these addresses and strips them from libp2p identify, the DHT
400
+self-record, and the signed peer record. Matching entries in
401
+[`Addresses.Announce`](#addressesannounce) and
402
+[`Addresses.AppendAnnounce`](#addressesappendannounce) are removed as well.
403
+
404
+This is the **publish-side** filter: it controls what other peers learn about
405
+this node's addresses. It does not affect what this node dials. For the
406
+**dial-side** filter see [`Swarm.AddrFilters`](#swarmaddrfilters). The
407
+[`server` profile](#server-profile) typically populates both fields together
408
+so that a range is neither advertised nor dialed.
409
410
> [!TIP]
402
-> The [`server` configuration profile](#server-profile) fills up this list with sensible defaults,
403
-> preventing announcement of non-routable IP addresses (e.g., `/ip4/192.168.0.0/ipcidr/16`,
404
-> which is the [multiaddress][multiaddr] representation of `192.168.0.0/16`) but you should always
405
-> check settings against your own network and/or hosting provider.
411
+> The [`server` profile](#server-profile) populates this field with a set of
412
+> private, local-only, and non-globally-reachable prefixes (RFC 1918 private,
413
+> RFC 6598 CGNAT, ULA, link-local, and others). See the
414
+> [`server` profile](#server-profile) section for the full list and for
415
+> optional entries operators may add manually.
416
417
Default: `[]`
418
3090
3091
### `Swarm.AddrFilters`
3092
3083
-An array of addresses (multiaddr netmasks) to not dial. By default, IPFS nodes
3084
-advertise _all_ addresses, even internal ones. This makes it easier for nodes on
3085
-the same network to reach each other. Unfortunately, this means that an IPFS
3086
-node will try to connect to one or more private IP addresses whenever dialing
3087
-another node, even if this other node is on a different network. This may
3088
-trigger netscan alerts on some hosting providers or cause strain in some setups.
3093
+An array of multiaddr netmasks. The libp2p connection gater refuses any
3094
+connection (inbound or outbound) whose remote address matches an entry,
3095
+before any handshake.
3096
+
3097
+By default Kubo advertises every interface address, so without this list a
3098
+node may dial private or non-routable addresses learned from other peers.
3099
+Some hosting providers treat such dials as netscan abuse.
3100
+
3101
+This is the **dial-side** filter: it controls which peers this node connects
3102
+to or accepts connections from. It does not affect what this node advertises
3103
+about itself. For the **publish-side** filter see
3104
+[`Addresses.NoAnnounce`](#addressesnoannounce). The
3105
+[`server` profile](#server-profile) typically populates both fields together
3106
+so that a range is neither advertised nor dialed.
3107
3108
> [!TIP]
3091
-> The [`server` configuration profile](#server-profile) fills up this list with sensible defaults,
3092
-> preventing dials to all non-routable IP addresses (e.g., `/ip4/192.168.0.0/ipcidr/16`,
3093
-> which is the [multiaddress][multiaddr] representation of `192.168.0.0/16`) but you should always
3094
-> check settings against your own network and/or hosting provider.
3109
+> The [`server` profile](#server-profile) populates this field with a set of
3110
+> private, local-only, and non-globally-reachable prefixes (RFC 1918 private,
3111
+> RFC 6598 CGNAT, ULA, link-local, and others). See the
3112
+> [`server` profile](#server-profile) section for the full list and for
3113
+> optional entries operators may add manually.
3114
3115
Default: `[]`
3116
4120
4121
### `server` profile
4122
4104
-Disables local [`Discovery.MDNS`](#discoverymdns), [turns off uPnP NAT port mapping](#swarmdisablenatportmap), and blocks connections to
4105
-IPv4 and IPv6 prefixes that are [private, local only, or unrouteable](https://github.com/ipfs/kubo/blob/b71cf0d15904bdef21fe2eee5f1118a274309a4d/config/profile.go#L24-L43).
4106
-
4107
-Recommended when running IPFS on machines with public IPv4 addresses (no NAT, no uPnP)
4108
-at providers that interpret local IPFS discovery and traffic as netscan abuse ([example](https://github.com/ipfs/kubo/issues/10327)).
4123
+The `server` profile hardens a node for public-internet operation. Recommended
4124
+on machines with public IPv4 addresses (no NAT, no uPnP) at providers that
4125
+interpret local IPFS discovery and traffic as netscan abuse
4126
+([example](https://github.com/ipfs/kubo/issues/10327)).
4127
+
4128
+Applying it:
4129
+
4130
+- disables local [`Discovery.MDNS`](#discoverymdns),
4131
+- turns off [uPnP NAT port mapping](#swarmdisablenatportmap),
4132
+- appends a set of IPv4 and IPv6 prefixes to both
4133
+ [`Addresses.NoAnnounce`](#addressesnoannounce) (do not advertise) and
4134
+ [`Swarm.AddrFilters`](#swarmaddrfilters) (do not dial or accept).
4135
+
4136
+The prefix list comes from the IANA [IPv4][iana-ipv4-special] and
4137
+[IPv6][iana-ipv6-special] Special-Purpose Address Registries per
4138
+[RFC 6890], covering entries marked "Not Globally Reachable."
4139
+
4140
+The filters apply only at the libp2p swarm layer. The HTTP
4141
+[`Addresses.API`](#addressesapi) and [`Addresses.Gateway`](#addressesgateway)
4142
+listeners keep working over loopback.
4143
+
4144
+#### IPv4 prefixes filtered by `server` profile
4145
+
4146
+| Multiaddr | Description | Reference |
4147
+| ----------------------------- | ------------------------------------------------ | ------------------------------------ |
4148
+| `/ip4/10.0.0.0/ipcidr/8` | Private-use | [RFC 1918] |
4149
+| `/ip4/100.64.0.0/ipcidr/10` | Shared address space (CGNAT) | [RFC 6598] |
4150
+| `/ip4/127.0.0.0/ipcidr/8` | Loopback | [RFC 1122 §3.2.1.3][rfc1122-3.2.1.3] |
4151
+| `/ip4/169.254.0.0/ipcidr/16` | Link-local | [RFC 3927] |
4152
+| `/ip4/172.16.0.0/ipcidr/12` | Private-use | [RFC 1918] |
4153
+| `/ip4/192.0.0.0/ipcidr/24` | IETF protocol assignments | [RFC 6890] |
4154
+| `/ip4/192.0.2.0/ipcidr/24` | `TEST-NET-1` (documentation) | [RFC 5737] |
4155
+| `/ip4/192.168.0.0/ipcidr/16` | Private-use | [RFC 1918] |
4156
+| `/ip4/198.18.0.0/ipcidr/15` | Benchmarking | [RFC 2544] |
4157
+| `/ip4/198.51.100.0/ipcidr/24` | `TEST-NET-2` (documentation) | [RFC 5737] |
4158
+| `/ip4/203.0.113.0/ipcidr/24` | `TEST-NET-3` (documentation) | [RFC 5737] |
4159
+| `/ip4/240.0.0.0/ipcidr/4` | Reserved (covers broadcast `255.255.255.255/32`) | [RFC 1112 §4][rfc1112-4] |
4160
+
4161
+#### IPv6 prefixes filtered by `server` profile
4162
+
4163
+| Multiaddr | Description | Reference |
4164
+| --------------------------- | ------------------------------------------------------------------ | ---------------------------- |
4165
+| `/ip6/::/ipcidr/3` | IANA-reserved `0000::/3` (catches unallocated leaks like `1e::/16`) | [RFC 4291 §2.4][rfc4291-2.4] |
4166
+| `/ip6/::1/ipcidr/128` | Loopback | [RFC 4291 §2.4][rfc4291-2.4] |
4167
+| `/ip6/100::/ipcidr/64` | Discard-only | [RFC 6666] |
4168
+| `/ip6/2001:2::/ipcidr/48` | Benchmarking | [RFC 5180] |
4169
+| `/ip6/2001:db8::/ipcidr/32` | Documentation | [RFC 3849] |
4170
+| `/ip6/fc00::/ipcidr/7` | Unique local addresses (ULA) | [RFC 4193] |
4171
+| `/ip6/fe80::/ipcidr/10` | Link-local unicast | [RFC 4291] |
4172
+
4173
+#### Overriding specific entries
4174
+
4175
+If you need peering over one of the prefixes above, remove that entry from
4176
+[`Swarm.AddrFilters`](#swarmaddrfilters) and
4177
+[`Addresses.NoAnnounce`](#addressesnoannounce) after applying the profile.
4178
+Or skip the profile and populate those fields manually.
4179
+
4180
+| Scenario | Remove |
4181
+| -------------------------------------------------- | ---------------------------- |
4182
+| LAN peering over `10.0.0.0/8` | `/ip4/10.0.0.0/ipcidr/8` |
4183
+| LAN peering over `172.16.0.0/12` | `/ip4/172.16.0.0/ipcidr/12` |
4184
+| LAN peering over `192.168.0.0/16` | `/ip4/192.168.0.0/ipcidr/16` |
4185
+| [Tailscale] or other CGNAT overlay (`100.64.0.0/10`) | `/ip4/100.64.0.0/ipcidr/10` |
4186
+| IPv6 ULA overlay ([WireGuard], [Tailscale], [Nebula], [ZeroTier], [cjdns]) | `/ip6/fc00::/ipcidr/7` |
4187
+| Link-local IPv6 peering | `/ip6/fe80::/ipcidr/10` |
4188
+| Multiple daemons peering over `127.0.0.1` | `/ip4/127.0.0.0/ipcidr/8` |
4189
+| Multiple daemons peering over IPv6 loopback `::1` | `/ip6/::1/ipcidr/128` and `/ip6/::/ipcidr/3` |
4190
+| [Yggdrasil] mesh peering (`200::/8`, `300::/8`) | `/ip6/::/ipcidr/3` |
4191
+| NAT64 (`64:ff9b::/96`) reachability | `/ip6/::/ipcidr/3` |
4192
+
4193
+#### Notes on `/ip6/::/ipcidr/3`
4194
+
4195
+Added after bogus IPv6 prefixes such as `1e::/16` (unallocated space
4196
+inside `0000::/3`) started leaking into DHT self-records from public
4197
+Kubo nodes with go-libp2p v0.47. See
4198
+[go-libp2p#3460][libp2p/go-libp2p#3460].
4199
+
4200
+Most overlay networks ([WireGuard], [Tailscale], [Nebula], [ZeroTier],
4201
+[cjdns]) use ULA `fc00::/7` and are blocked by the separate
4202
+`/ip6/fc00::/ipcidr/7` entry, not by this one. The notable exception is
4203
+[Yggdrasil], which uses `0200::/7` inside `0000::/3`.
4204
+
4205
+NAT64 translators rarely emit `64:ff9b::` ([RFC 6052]) or
4206
+`64:ff9b:1::/48` ([RFC 8215]) as a source address, so the rule's
4207
+announce-side impact on NAT64 deployments is typically none. Removal is
4208
+warranted only if a `64:ff9b::` address is bound directly to a node
4209
+interface.
4210
+
4211
+[iana-ipv4-special]: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
4212
+[iana-ipv6-special]: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
4213
+[rfc1112-4]: https://datatracker.ietf.org/doc/html/rfc1112#section-4
4214
+[rfc1122-3.2.1.3]: https://datatracker.ietf.org/doc/html/rfc1122#section-3.2.1.3
4215
+[rfc4291-2.4]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.4
4216
+[RFC 1112]: https://datatracker.ietf.org/doc/html/rfc1112
4217
+[RFC 1918]: https://datatracker.ietf.org/doc/html/rfc1918
4218
+[RFC 2544]: https://datatracker.ietf.org/doc/html/rfc2544
4219
+[RFC 3849]: https://datatracker.ietf.org/doc/html/rfc3849
4220
+[RFC 3927]: https://datatracker.ietf.org/doc/html/rfc3927
4221
+[RFC 4193]: https://datatracker.ietf.org/doc/html/rfc4193
4222
+[RFC 4291]: https://datatracker.ietf.org/doc/html/rfc4291
4223
+[RFC 5180]: https://datatracker.ietf.org/doc/html/rfc5180
4224
+[RFC 5737]: https://datatracker.ietf.org/doc/html/rfc5737
4225
+[RFC 6598]: https://datatracker.ietf.org/doc/html/rfc6598
4226
+[RFC 6666]: https://datatracker.ietf.org/doc/html/rfc6666
4227
+[RFC 6890]: https://datatracker.ietf.org/doc/html/rfc6890
4228
+[libp2p/go-libp2p#3460]: https://github.com/libp2p/go-libp2p/issues/3460
4229
+[WireGuard]: https://www.wireguard.com/
4230
+[Tailscale]: https://tailscale.com/
4231
+[Nebula]: https://nebula.defined.net/
4232
+[ZeroTier]: https://www.zerotier.com/
4233
+[cjdns]: https://github.com/cjdelisle/cjdns
4234
+[Yggdrasil]: https://yggdrasil-network.github.io/
4235
+[RFC 6052]: https://datatracker.ietf.org/doc/html/rfc6052
4236
+[RFC 8215]: https://datatracker.ietf.org/doc/html/rfc8215
4237
4238
### `randomports` profile
4239