opensource/kubo
1
0
Fork 0
mirror of https://github.com/ipfs/kubo.git synced 2025-05-17 15:06:47 +08:00
Code Issues Projects Releases Wiki Activity
Files
kubo/docs/changelogs/v0.35.md
Andrew Gillis 472674fd62 feat(pebble): support pinning FormatMajorVersion (#10789) 
* Upgrade to pebble v2.0.3

- Configure latest pebble database format at init
- Do not automatically ratchet database format if set in config
- Daemon messge about new available pebble format
- Document pebble config with formatMajorVersion
- Add warning to users running badger, nudging them to switch to flatfs or pebble
- docs: explain Pebble's `FormatMajorVersion`
- Use pebbleds instead of badgerds in t0060-daemon.sh
- Print badgerds warning message to stderr
2025-04-30 12:13:56 -07:00

10 KiB
Raw Blame History

Kubo changelog v0.35

This release was brought to you by the Shipyard team.

v0.35.0

Overview

🔦 Highlights

Dedicated Reprovider.Strategy for MFS

The Mutable File System (MFS) in Kubo is a UnixFS filesystem managed with ipfs files commands. It supports familiar file operations like cp and mv within a folder-tree structure, automatically updating a MerkleDAG and a "root CID" that reflects the current MFS state. Files in MFS are protected from garbage collection, offering a simpler alternative to ipfs pin. This makes it a popular choice for tools like IPFS Desktop and the WebUI.

Previously, the pinned reprovider strategy required manual pin management: each dataset update meant pinning the new version and unpinning the old one. Now, new strategies—mfs and pinned+mfs—let users limit announcements to data explicitly placed in MFS. This simplifies updating datasets and announcing only the latest version to the Amino DHT.

Users relying on the pinned strategy can switch to pinned+mfs and use MFS alone to manage updates and announcements, eliminating the need for manual pinning and unpinning. We hope this makes it easier to publish just the data that matters to you.

See Reprovider.Strategy for more details.

Additional new configuration options

Grid view in WebUI

The WebUI, accessible at http://127.0.0.1:5001/webui/, now includes support for the grid view on the Files screen:

image

Enhanced DAG-Shaping Controls for ipfs add

This release advances CIDv1 support by introducing fine-grained control over UnixFS DAG shaping during data ingestion with the ipfs add command.

Wider DAG trees (more links per node, higher fanout, larger thresholds) are beneficial for large files and directories with many files, reducing tree depth and lookup latency in high-latency networks, but they increase node size, straining memory and CPU on resource-constrained devices. Narrower trees (lower link count, lower fanout, smaller thresholds) are preferable for smaller directories, frequent updates, or low-power clients, minimizing overhead and ensuring compatibility, though they may increase traversal steps for very large datasets.

Kubo now allows users to act on these tradeoffs and customize the width of the DAG created by ipfs add command.

New ipfs add Options

Three new options allow you to override default settings for specific import operations:

  • --max-file-links: Sets the maximum number of child links for a single file chunk.
  • --max-directory-links: Defines the maximum number of child entries in a "basic" (single-chunk) directory.
    • Note: Directories exceeding this limit or the Import.UnixFSHAMTDirectorySizeThreshold are converted to HAMT-based (sharded across multiple blocks) structures.
  • --max-hamt-fanout: Specifies the maximum number of child nodes for HAMT internal structures.
Persistent Import.* Configuration

You can set default values for these options using the following configuration settings:

Updated Configuration Profiles

The release updated configuration profiles to incorporate these new Import.* settings:

  • Updated Profile: test-cid-v1 now includes current defaults as explicit Import.UnixFSFileMaxLinks=174, Import.UnixFSDirectoryMaxLinks=0, Import.UnixFSHAMTDirectoryMaxFanout=256 and Import.UnixFSHAMTDirectorySizeThreshold=256KiB
  • New Profile: test-cid-v1-wide adopts experimental directory DAG-shaping defaults, increasing the maximum file DAG width from 174 to 1024, HAMT fanout from 256 to 1024, and raising the HAMT directory sharding threshold from 256KiB to 1MiB, aligning with 1MiB file chunks.

Tip

Apply one of CIDv1 test profiles with ipfs config profile apply test-cid-v1[-wide].

Optimized, dedicated queue for providing fresh CIDs

From kubo v0.33.0, Bitswap stopped advertising newly added and received blocks to the DHT. Since then boxo/provider is responsible for the provide and reprovide logic. Prior to v0.35.0, provides and reprovides were handled together in batches, leading to delays in initial advertisements (provides).

Provides and Reprovides now have separate queues, allowing for immediate provide of new CIDs and optimised batching of reprovides.

This change introduces a new configuration option for limiting the number of concurrent provide operations: Provider.WorkerCount.

Tip

Users who need to provide large volumes of content immediately should consider removing the cap on concurrent provide operations and also set Routing.AcceleratedDHTClient to true.

Deprecated ipfs stats provider

Since the ipfs stats provider command was displaying statistics for both provides and reprovides, this command isn't relevant anymore after separating the two queues.

The successor command is ipfs stats reprovide, showing the same statistics, but for reprovides only.

Note

ipfs stats provider still works, but is marked as deprecated and will be removed in a future release. Be mindful that the command provides only statistics about reprovides (similar to ipfs stats reprovide) and not the new provide queue (this will be fixed as a part of wider refactor planned for a future release).

Pebble Database Format Config

This Kubo release provides node operators with more control over Pebble's FormatMajorVersion. This allows testing a new Kubo release without automatically migrating Pebble datastores, keeping the ability to switch back to older Kubo.

When IPFS is initialized to use the pebbleds datastore (opt-in via ipfs init --profile=pebbleds), the latest pebble database format is configured in the pebble datastore config as "formatMajorVersion". Setting this in the datastore config prevents automatically upgrading to the latest available version when Kubo is upgraded. If a later version becomes available, the Kubo daemon prints a startup message to indicate this. The user can them update the config to use the latest format when they are certain a downgrade will not be necessary.

Without the "formatMajorVersion" in the pebble datastore config, the database format is automatically upgraded to the latest version. If this happens, then it is possible a downgrade back to the previous version of Kubo will not work if new format is not compatible with the pebble datastore in the previous version of Kubo.

When installing a new version of Kubo when "formatMajorVersion" is configured, automatic repository migration (ipfs daemon with --migrate=true) does not upgrade this to the latest available version. This is done because a user may have reasons not to upgrade the pebble database format, and may want to be able to downgrade Kubo if something else is not working in the new version. If the configured pebble database format in the old Kubo is not supported in the new Kubo, then the configured version must be updated and the old Kubo run, before installing the new Kubo.

See other caveats and configuration options at kubo/docs/datastores.md#pebbleds

📦️ Important dependency updates

📝 Changelog

👨‍👩‍👧‍👦 Contributors