From 40ffd166eab6877ad997544bac38084da2b9d2e5 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 26 Nov 2025 21:52:55 +0100 Subject: [PATCH] docs: restructure v0.39 changelog for clarity - rewrite overview to lead with user value (self-hosting on consumer hardware) - reorder highlights: provider features together, then UPnP, then housekeeping - simplify titles (drop "Amino", "Fixed", verbose descriptions) - link to Shipyard's sweep provider blogpost --- docs/changelogs/v0.39.md | 91 +++++++++++++++++++++------------------- docs/config.md | 1 + 2 files changed, 49 insertions(+), 43 deletions(-) diff --git a/docs/changelogs/v0.39.md b/docs/changelogs/v0.39.md index 53338fea5..cf73d56a1 100644 --- a/docs/changelogs/v0.39.md +++ b/docs/changelogs/v0.39.md @@ -8,29 +8,33 @@ This release was brought to you by the [Shipyard](https://ipshipyard.com/) team. ## v0.39.0 +[](https://github.com/user-attachments/assets/427702e8-b6b8-4ac2-8425-18069626c321) + - [Overview](#overview) - [๐Ÿ”ฆ Highlights](#-highlights) - - [๐ŸŽฏ Amino DHT Sweep provider is now the default](#-amino-dht-sweep-provider-is-now-the-default) + - [๐ŸŽฏ DHT Sweep provider is now the default](#-dht-sweep-provider-is-now-the-default) - [โšก Fast root CID providing for immediate content discovery](#-fast-root-cid-providing-for-immediate-content-discovery) - - [๐Ÿ“Š Detailed statistics for Sweep provider with `ipfs provide stat`](#-detailed-statistics-for-sweep-provider-with-ipfs-provide-stat) - - [โฏ๏ธ Provider resume cycle for improved reproviding reliability](#provider-resume-cycle-for-improved-reproviding-reliability) - - [๐Ÿ”” Sweep provider slow reprovide warnings](#-sweep-provider-slow-reprovide-warnings) + - [โฏ๏ธ Provider state persists across restarts](#๏ธ-provider-state-persists-across-restarts) + - [๐Ÿ“Š Detailed statistics with `ipfs provide stat`](#-detailed-statistics-with-ipfs-provide-stat) + - [๐Ÿ”” Slow reprovide warnings](#-slow-reprovide-warnings) - [๐Ÿ“Š Metric rename: `provider_provides_total`](#-metric-rename-provider_provides_total) - - [๐Ÿ”ง Fixed UPnP port forwarding after router restarts](#-fixed-upnp-port-forwarding-after-router-restarts) - - [๐Ÿ–ฅ๏ธ RISC-V support with prebuilt binaries](#๏ธ-risc-v-support-with-prebuilt-binaries) - - [๐Ÿšฆ Gateway range request limits for CDN compatibility](#-gateway-range-request-limits-for-cdn-compatibility) + - [๐Ÿ”ง Automatic UPnP recovery after router restarts](#-automatic-upnp-recovery-after-router-restarts) - [๐Ÿชฆ Deprecated `go-ipfs` name no longer published](#-deprecated-go-ipfs-name-no-longer-published) + - [๐Ÿšฆ Gateway range request limits for CDN compatibility](#-gateway-range-request-limits-for-cdn-compatibility) + - [๐Ÿ–ฅ๏ธ RISC-V support with prebuilt binaries](#๏ธ-risc-v-support-with-prebuilt-binaries) - [๐Ÿ“ฆ๏ธ Important dependency updates](#-important-dependency-updates) - [๐Ÿ“ Changelog](#-changelog) - [๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ Contributors](#-contributors) ### Overview -Kubo 0.39.0 graduates the experimental sweep provider to default, bringing efficient content announcement to all nodes. This release adds fast root CID providing for immediate content discovery via `ipfs add`, detailed provider statistics, automatic state persistence for reliable reproviding after restarts, and proactive monitoring alerts for identifying issues early. It also includes important fixes for UPnP port forwarding, RISC-V prebuilt binaries, and finalizes the deprecation of the legacy go-ipfs name. +Kubo 0.39 makes self-hosting practical on consumer hardware and home networks. The DHT sweep provider (now default) announces your content to the network without traffic spikes that overwhelm residential connections. Automatic UPnP recovery means your node stays reachable after router restarts without manual intervention. + +New content becomes findable immediately after `ipfs add`. The provider system persists state across restarts, alerts you when falling behind, and exposes detailed stats for monitoring. This release also finalizes the deprecation of the legacy `go-ipfs` name. ### ๐Ÿ”ฆ Highlights -#### ๐ŸŽฏ Amino DHT Sweep provider is now the default +#### ๐ŸŽฏ DHT Sweep provider is now the default The Amino DHT Sweep provider system, introduced as experimental in v0.38, is now enabled by default (`Provide.DHT.SweepEnabled=true`). @@ -41,16 +45,17 @@ The Amino DHT Sweep provider system, introduced as experimental in v0.38, is now - If you explicitly set `Provide.DHT.SweepEnabled=false` in v0.38, you'll continue using the legacy provider - If you were using the default settings, you'll automatically get the sweep provider - To opt out and return to legacy behavior: `ipfs config --json Provide.DHT.SweepEnabled false` +- Providers with medium to large datasets may need to adjust defaults; see [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning) **New features available with sweep mode:** -- Detailed statistics via `ipfs provide stat` ([see below](#-detailed-statistics-for-sweep-provider-with-ipfs-provide-stat)) -- Automatic resume after restarts with persistent state ([see below](#provider-resume-cycle-for-improved-reproviding-reliability)) -- Proactive alerts when reproviding falls behind ([see below](#-sweep-provider-slow-reprovide-warnings)) +- Detailed statistics via `ipfs provide stat` ([see below](#-detailed-statistics-with-ipfs-provide-stat)) +- Automatic resume after restarts with persistent state ([see below](#๏ธ-provider-state-persists-across-restarts)) +- Proactive alerts when reproviding falls behind ([see below](#-slow-reprovide-warnings)) - Better metrics for monitoring (`provider_provides_total`) ([see below](#-metric-rename-provider_provides_total)) - Fast optimistic provide of new root CIDs ([see below](#-fast-root-cid-providing-for-immediate-content-discovery)) -For background on the sweep provider design and motivations, see [`Provide.DHT.SweepEnabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtsweepenabled) and [ipshipyard.com#8](https://github.com/ipshipyard/ipshipyard.com/pull/8). +For background on the sweep provider design and motivations, see [`Provide.DHT.SweepEnabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtsweepenabled) and Shipyard's blogpost [Provide Sweep: Solving the DHT Provide Bottleneck](https://ipshipyard.com/blog/2025-dht-provide-sweep/). #### โšก Fast root CID providing for immediate content discovery @@ -74,20 +79,7 @@ ipfs dag import file.car # Same for CAR imports This optimization works best with the sweep provider and accelerated DHT client, where provide operations are significantly faster. Automatically skipped when DHT is unavailable (e.g., `Routing.Type=none` or delegated-only configurations). -#### ๐Ÿ“Š Detailed statistics for Sweep provider with `ipfs provide stat` - -The Sweep provider system now exposes detailed statistics through `ipfs provide stat`, helping you monitor provider health and troubleshoot issues. - -Run `ipfs provide stat` for a quick summary, or use `--all` to see complete metrics including connectivity status, queue sizes, reprovide schedules, network statistics, operation rates, and worker utilization. For real-time monitoring, use `watch ipfs provide stat --all --compact` to observe changes in a 2-column layout. Individual sections can be displayed with flags like `--network`, `--operations`, or `--workers`. - -For Dual DHT configurations, use `--lan` to view LAN DHT statistics instead of the default WAN DHT stats. - -For more information, run `ipfs provide stat --help` or see the [Provide Stats documentation](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md). - -> [!NOTE] -> Legacy provider (when `Provide.DHT.SweepEnabled=false`) shows basic statistics without flag support. - -#### โฏ๏ธ Provider resume cycle for improved reproviding reliability +#### โฏ๏ธ Provider state persists across restarts The Sweep provider now persists the reprovide cycle state and automatically resumes where it left off after a restart. This brings several improvements: @@ -98,7 +90,20 @@ The Sweep provider now persists the reprovide cycle state and automatically resu This feature improves reliability for nodes that experience intermittent connectivity or restarts. -#### ๐Ÿ”” Sweep provider slow reprovide warnings +#### ๐Ÿ“Š Detailed statistics with `ipfs provide stat` + +The Sweep provider system now exposes detailed statistics through `ipfs provide stat`, helping you monitor provider health and troubleshoot issues. + +Run `ipfs provide stat` for a quick summary, or use `--all` to see complete metrics including connectivity status, queue sizes, reprovide schedules, network statistics, operation rates, and worker utilization. For real-time monitoring, use `watch ipfs provide stat --all --compact` to observe changes in a 2-column layout. Individual sections can be displayed with flags like `--network`, `--operations`, or `--workers`. + +For Dual DHT configurations, use `--lan` to view LAN DHT statistics instead of the default WAN DHT stats. + +For more information, run `ipfs provide stat --help` or see the [Provide Stats documentation](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md), including [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning). + +> [!NOTE] +> Legacy provider (when `Provide.DHT.SweepEnabled=false`) shows basic statistics without flag support. + +#### ๐Ÿ”” Slow reprovide warnings Kubo now monitors DHT reprovide operations when `Provide.DHT.SweepEnabled=true` and alerts you if your node is falling behind on reprovides. @@ -120,7 +125,7 @@ The Amino DHT Sweep provider metric has been renamed from `total_provide_count_t **Migration:** If you have Prometheus queries, dashboards, or alerts monitoring the old `total_provide_count_total` metric, update them to use `provider_provides_total` instead. This affects all nodes using sweep mode, which is now the default in v0.39 (previously opt-in experimental in v0.38). -#### ๐Ÿ”ง Fixed UPnP port forwarding after router restarts +#### ๐Ÿ”ง Automatic UPnP recovery after router restarts Kubo now automatically recovers UPnP port mappings when routers restart or become temporarily unavailable, fixing a critical connectivity issue that @@ -144,20 +149,6 @@ without manual intervention. This significantly improves reliability for desktop and self-hosted IPFS nodes using UPnP for NAT traversal. -#### ๐Ÿ–ฅ๏ธ RISC-V support with prebuilt binaries - -Kubo provides official `linux-riscv64` prebuilt binaries, bringing IPFS to [RISC-V](https://en.wikipedia.org/wiki/RISC-V) open hardware. - -As RISC-V single-board computers and embedded systems become more accessible, the distributed web is now supported on open hardware architectures - a natural pairing of open technologies. - -Download from or and look for the `linux-riscv64` archive. - -#### ๐Ÿšฆ Gateway range request limits for CDN compatibility - -The new [`Gateway.MaxRangeRequestFileSize`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaymaxrangerequestfilesize) configuration protects against CDN range request limitations that cause bandwidth overcharges on deserialized responses. Some CDNs convert range requests over large files into full file downloads, causing clients requesting small byte ranges to unknowingly download entire multi-gigabyte files. - -This only impacts deserialized responses. Clients using verifiable block requests (`application/vnd.ipld.raw`) are not affected. See the [configuration documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaymaxrangerequestfilesize) for details. - #### ๐Ÿชฆ Deprecated `go-ipfs` name no longer published The `go-ipfs` name was deprecated in 2022 and renamed to `kubo`. Starting with this release, the legacy Docker image name has been replaced with a stub that displays an error message directing users to switch to `ipfs/kubo`. @@ -168,6 +159,20 @@ The `go-ipfs` name was deprecated in 2022 and renamed to `kubo`. Starting with t All users should migrate to the `kubo` name in their scripts and configurations. +#### ๐Ÿšฆ Gateway range request limits for CDN compatibility + +The new [`Gateway.MaxRangeRequestFileSize`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaymaxrangerequestfilesize) configuration protects against CDN range request limitations that cause bandwidth overcharges on deserialized responses. Some CDNs convert range requests over large files into full file downloads, causing clients requesting small byte ranges to unknowingly download entire multi-gigabyte files. + +This only impacts deserialized responses. Clients using verifiable block requests (`application/vnd.ipld.raw`) are not affected. See the [configuration documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaymaxrangerequestfilesize) for details. + +#### ๐Ÿ–ฅ๏ธ RISC-V support with prebuilt binaries + +Kubo provides official `linux-riscv64` prebuilt binaries, bringing IPFS to [RISC-V](https://en.wikipedia.org/wiki/RISC-V) open hardware. + +As RISC-V single-board computers and embedded systems become more accessible, the distributed web is now supported on open hardware architectures - a natural pairing of open technologies. + +Download from or and look for the `linux-riscv64` archive. + ### ๐Ÿ“ฆ๏ธ Important dependency updates - update `go-libp2p` to [v0.45.0](https://github.com/libp2p/go-libp2p/releases/tag/v0.45.0) (incl. [v0.44.0](https://github.com/libp2p/go-libp2p/releases/tag/v0.44.0)) with self-healing UPnP port mappings and go-log/slog interop fixes diff --git a/docs/config.md b/docs/config.md index 0352bd845..256ed9b1d 100644 --- a/docs/config.md +++ b/docs/config.md @@ -2118,6 +2118,7 @@ connections this setting can generate. > users. The system will only use workers as needed - unused resources won't be > consumed. Ensure you adjust the swarm [connection manager](#swarmconnmgr) and > [resource manager](#swarmresourcemgr) configuration accordingly. +> See [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning) for more details. Default: `16`