@cryptotaxi247 / kubo / commits / 776c21a6d

fix: provider merge conflicts (#10989)

Co-authored-by: Marcin Rataj <lidel@lidel.org>

Guillaume Michel committed Sep 26, 2025 at 03:22 UTC 776c21a6d61592f91121980b772bc89cd7c58096
3 files changed +206 -139
config/provide.go
+8 -8
@@ -19,7 +19,7 @@ const (
19 DefaultProvideDHTDedicatedPeriodicWorkers = 2
20 DefaultProvideDHTDedicatedBurstWorkers = 1
21 DefaultProvideDHTMaxProvideConnsPerWorker = 16
22 - DefaultProvideDHTKeyStoreBatchSize = 1 << 14 // ~544 KiB per batch (1 multihash = 34 bytes)
22 + DefaultProvideDHTKeystoreBatchSize = 1 << 14 // ~544 KiB per batch (1 multihash = 34 bytes)
23 DefaultProvideDHTOfflineDelay = 2 * time.Hour
24 )
25
@@ -79,9 +79,9 @@ type ProvideDHT struct {
79 // Default: DefaultProvideDHTMaxProvideConnsPerWorker
80 MaxProvideConnsPerWorker *OptionalInteger `json:",omitempty"`
81
82 - // KeyStoreBatchSize sets the batch size for keystore operations during reprovide refresh (sweep mode only).
83 - // Default: DefaultProvideDHTKeyStoreBatchSize
84 - KeyStoreBatchSize *OptionalInteger `json:",omitempty"`
82 + // KeystoreBatchSize sets the batch size for keystore operations during reprovide refresh (sweep mode only).
83 + // Default: DefaultProvideDHTKeystoreBatchSize
84 + KeystoreBatchSize *OptionalInteger `json:",omitempty"`
85
86 // OfflineDelay sets the delay after which the provider switches from Disconnected to Offline state (sweep mode only).
87 // Default: DefaultProvideDHTOfflineDelay
@@ -150,11 +150,11 @@ func ValidateProvideConfig(cfg *Provide) error {
150 }
151 }
152
153 - // Validate KeyStoreBatchSize
154 - if !cfg.DHT.KeyStoreBatchSize.IsDefault() {
155 - batchSize := cfg.DHT.KeyStoreBatchSize.WithDefault(DefaultProvideDHTKeyStoreBatchSize)
153 + // Validate KeystoreBatchSize
154 + if !cfg.DHT.KeystoreBatchSize.IsDefault() {
155 + batchSize := cfg.DHT.KeystoreBatchSize.WithDefault(DefaultProvideDHTKeystoreBatchSize)
156 if batchSize <= 0 {
157 - return fmt.Errorf("Provide.DHT.KeyStoreBatchSize must be positive, got %d", batchSize)
157 + return fmt.Errorf("Provide.DHT.KeystoreBatchSize must be positive, got %d", batchSize)
158 }
159 }
160
core/node/provider.go
+48 -20
@@ -24,6 +24,7 @@ import (
24 "github.com/libp2p/go-libp2p-kad-dht/fullrt"
25 dht_pb "github.com/libp2p/go-libp2p-kad-dht/pb"
26 dhtprovider "github.com/libp2p/go-libp2p-kad-dht/provider"
27 + "github.com/libp2p/go-libp2p-kad-dht/provider/buffered"
28 ddhtprovider "github.com/libp2p/go-libp2p-kad-dht/provider/dual"
29 "github.com/libp2p/go-libp2p-kad-dht/provider/keystore"
30 routinghelpers "github.com/libp2p/go-libp2p-routing-helpers"
@@ -84,7 +85,7 @@ type DHTProvider interface {
85 // The keys are not deleted from the keystore, so they will continue to be
86 // reprovided as scheduled.
87 Clear() int
87 - // RefreshSchedule scans the KeyStore for any keys that are not currently
88 + // RefreshSchedule scans the Keystore for any keys that are not currently
89 // scheduled for reproviding. If such keys are found, it schedules their
90 // associated keyspace region to be reprovided.
91 //
@@ -314,13 +315,40 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
315 }
316 sweepingReprovider := fx.Provide(func(in providerInput) (DHTProvider, *keystore.ResettableKeystore, error) {
317 ds := in.Repo.Datastore()
317 - keyStore, err := keystore.NewResettableKeystore(ds,
318 + ks, err := keystore.NewResettableKeystore(ds,
319 keystore.WithPrefixBits(16),
320 keystore.WithDatastorePath("/provider/keystore"),
320 - keystore.WithBatchSize(int(cfg.Provide.DHT.KeyStoreBatchSize.WithDefault(config.DefaultProvideDHTKeyStoreBatchSize))),
321 + keystore.WithBatchSize(int(cfg.Provide.DHT.KeystoreBatchSize.WithDefault(config.DefaultProvideDHTKeystoreBatchSize))),
322 )
323 if err != nil {
323 - return &NoopProvider{}, nil, err
324 + return nil, nil, err
325 + }
326 + // Constants for buffered provider configuration
327 + // These values match the upstream defaults from go-libp2p-kad-dht and have been battle-tested
328 + const (
329 + // bufferedDsName is the datastore namespace used by the buffered provider.
330 + // The dsqueue persists operations here to handle large data additions without
331 + // being memory-bound, allowing operations on hardware with limited RAM and
332 + // enabling core operations to return instantly while processing happens async.
333 + bufferedDsName = "bprov"
334 +
335 + // bufferedBatchSize controls how many operations are dequeued and processed
336 + // together from the datastore queue. The worker processes up to this many
337 + // operations at once, grouping them by type for efficiency.
338 + bufferedBatchSize = 1 << 10 // 1024 items
339 +
340 + // bufferedIdleWriteTime is an implementation detail of go-dsqueue that controls
341 + // how long the datastore buffer waits for new multihashes to arrive before
342 + // flushing in-memory items to the datastore. This does NOT affect providing speed -
343 + // provides happen as fast as possible via a dedicated worker that continuously
344 + // processes the queue regardless of this timing.
345 + bufferedIdleWriteTime = time.Minute
346 + )
347 +
348 + bufferedProviderOpts := []buffered.Option{
349 + buffered.WithBatchSize(bufferedBatchSize),
350 + buffered.WithDsName(bufferedDsName),
351 + buffered.WithIdleWriteTime(bufferedIdleWriteTime),
352 }
353 var impl dhtImpl
354 switch inDht := in.DHT.(type) {
@@ -331,7 +359,7 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
359 case *dual.DHT:
360 if inDht != nil {
361 prov, err := ddhtprovider.New(inDht,
334 - ddhtprovider.WithKeystore(keyStore),
362 + ddhtprovider.WithKeystore(ks),
363
364 ddhtprovider.WithReprovideInterval(reprovideInterval),
365 ddhtprovider.WithMaxReprovideDelay(time.Hour),
@@ -346,8 +374,7 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
374 if err != nil {
375 return nil, nil, err
376 }
349 - _ = prov
350 - return prov, keyStore, nil
377 + return buffered.New(prov, ds, bufferedProviderOpts...), ks, nil
378 }
379 case *fullrt.FullRT:
380 if inDht != nil {
@@ -365,7 +392,7 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
392 selfAddrsFunc = func() []ma.Multiaddr { return impl.Host().Addrs() }
393 }
394 opts := []dhtprovider.Option{
368 - dhtprovider.WithKeystore(keyStore),
395 + dhtprovider.WithKeystore(ks),
396 dhtprovider.WithPeerID(impl.Host().ID()),
397 dhtprovider.WithRouter(impl),
398 dhtprovider.WithMessageSender(impl.MessageSender()),
@@ -387,16 +414,19 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
414 }
415
416 prov, err := dhtprovider.New(opts...)
390 - return prov, keyStore, err
417 + if err != nil {
418 + return nil, nil, err
419 + }
420 + return buffered.New(prov, ds, bufferedProviderOpts...), ks, nil
421 })
422
423 type keystoreInput struct {
424 fx.In
425 Provider DHTProvider
396 - KeyStore *keystore.ResettableKeystore
426 + Keystore *keystore.ResettableKeystore
427 KeyProvider provider.KeyChanFunc
428 }
399 - initKeyStore := fx.Invoke(func(lc fx.Lifecycle, in keystoreInput) {
429 + initKeystore := fx.Invoke(func(lc fx.Lifecycle, in keystoreInput) {
430 // Skip keystore initialization for NoopProvider
431 if _, ok := in.Provider.(*NoopProvider); ok {
432 return
@@ -407,12 +437,12 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
437 done = make(chan struct{})
438 )
439
410 - syncKeyStore := func(ctx context.Context) error {
440 + syncKeystore := func(ctx context.Context) error {
441 kcf, err := in.KeyProvider(ctx)
442 if err != nil {
443 return err
444 }
415 - if err := in.KeyStore.ResetCids(ctx, kcf); err != nil {
445 + if err := in.Keystore.ResetCids(ctx, kcf); err != nil {
446 return err
447 }
448 if err := in.Provider.RefreshSchedule(); err != nil {
@@ -424,7 +454,7 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
454 lc.Append(fx.Hook{
455 OnStart: func(ctx context.Context) error {
456 // Set the KeyProvider as a garbage collection function for the
427 - // keystore. Periodically purge the KeyStore from all its keys and
457 + // keystore. Periodically purge the Keystore from all its keys and
458 // replace them with the keys that needs to be reprovided, coming from
459 // the KeyChanFunc. So far, this is the less worse way to remove CIDs
460 // that shouldn't be reprovided from the provider's state.
@@ -434,7 +464,7 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
464 // which can take a while.
465 strategy := cfg.Provide.Strategy.WithDefault(config.DefaultProvideStrategy)
466 logger.Infow("provider keystore sync started", "strategy", strategy)
437 - if err := syncKeyStore(ctx); err != nil {
467 + if err := syncKeystore(ctx); err != nil {
468 logger.Errorw("provider keystore sync failed", "err", err, "strategy", strategy)
469 } else {
470 logger.Infow("provider keystore sync completed", "strategy", strategy)
@@ -454,7 +484,7 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
484 case <-gcCtx.Done():
485 return
486 case <-ticker.C:
457 - if err := syncKeyStore(gcCtx); err != nil {
487 + if err := syncKeystore(gcCtx); err != nil {
488 logger.Errorw("provider keystore sync", "err", err)
489 }
490 }
@@ -471,18 +501,16 @@ func SweepingProviderOpt(cfg *config.Config) fx.Option {
501 case <-ctx.Done():
502 return ctx.Err()
503 }
474 -
504 // Keystore data isn't purged, on close, but it will be overwritten
505 // when the node starts again.
477 -
478 - return in.KeyStore.Close()
506 + return in.Keystore.Close()
507 },
508 })
509 })
510
511 return fx.Options(
512 sweepingReprovider,
485 - initKeyStore,
513 + initKeystore,
514 )
515 }
516
docs/config.md
+150 -111
@@ -135,7 +135,7 @@ config file at runtime.
135 - [`Provide.DHT.DedicatedPeriodicWorkers`](#providedhtdedicatedperiodicworkers)
136 - [`Provide.DHT.DedicatedBurstWorkers`](#providedhtdedicatedburstworkers)
137 - [`Provide.DHT.MaxProvideConnsPerWorker`](#providedhtmaxprovideconnsperworker)
138 - - [`Provide.DHT.KeyStoreBatchSize`](#providedhtkeystorebatchsize)
138 + - [`Provide.DHT.KeystoreBatchSize`](#providedhtkeystorebatchsize)
139 - [`Provide.DHT.OfflineDelay`](#providedhtofflinedelay)
140 - [`Provider`](#provider)
141 - [`Provider.Enabled`](#providerenabled)
@@ -282,8 +282,8 @@ the local [Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) (`/api/v0`)
282
283 Supported Transports:
284
285 -* tcp/ip{4,6} - `/ipN/.../tcp/...`
286 -* unix - `/unix/path/to/socket`
285 +- tcp/ip{4,6} - `/ipN/.../tcp/...`
286 +- unix - `/unix/path/to/socket`
287
288 > [!CAUTION]
289 > **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET**
@@ -310,8 +310,8 @@ the local [HTTP gateway](https://specs.ipfs.tech/http-gateways/) (`/ipfs`, `/ipn
310
311 Supported Transports:
312
313 -* tcp/ip{4,6} - `/ipN/.../tcp/...`
314 -* unix - `/unix/path/to/socket`
313 +- tcp/ip{4,6} - `/ipN/.../tcp/...`
314 +- unix - `/unix/path/to/socket`
315
316 > [!CAUTION]
317 > **SECURITY CONSIDERATIONS FOR GATEWAY EXPOSURE**
@@ -334,10 +334,10 @@ connections.
334
335 Supported Transports:
336
337 -* tcp/ip{4,6} - `/ipN/.../tcp/...`
338 -* websocket - `/ipN/.../tcp/.../ws`
339 -* quicv1 (RFC9000) - `/ipN/.../udp/.../quic-v1` - can share the same two tuple with `/quic-v1/webtransport`
340 -* webtransport `/ipN/.../udp/.../quic-v1/webtransport` - can share the same two tuple with `/quic-v1`
337 +- tcp/ip{4,6} - `/ipN/.../tcp/...`
338 +- websocket - `/ipN/.../tcp/.../ws`
339 +- quicv1 (RFC9000) - `/ipN/.../udp/.../quic-v1` - can share the same two tuple with `/quic-v1/webtransport`
340 +- webtransport `/ipN/.../udp/.../quic-v1/webtransport` - can share the same two tuple with `/quic-v1`
341
342 > [!IMPORTANT]
343 > Make sure your firewall rules allow incoming connections on both TCP and UDP ports defined here.
@@ -346,6 +346,7 @@ Supported Transports:
346 Note that quic (Draft-29) used to be supported with the format `/ipN/.../udp/.../quic`, but has since been [removed](https://github.com/libp2p/go-libp2p/releases/tag/v0.30.0).
347
348 Default:
349 +
350 ```json
351 [
352 "/ip4/0.0.0.0/tcp/4001",
@@ -401,6 +402,7 @@ Contains information used by the [Kubo RPC API](https://docs.ipfs.tech/reference
402 Map of HTTP headers to set on responses from the RPC (`/api/v0`) HTTP server.
403
404 Example:
405 +
406 ```json
407 {
408 "Foo": ["bar"]
@@ -512,11 +514,11 @@ the rest of the internet.
514 When unset (default), the AutoNAT service defaults to _enabled_. Otherwise, this
515 field can take one of two values:
516
515 -* `enabled` - Enable the V1+V2 service (unless the node determines that it,
517 +- `enabled` - Enable the V1+V2 service (unless the node determines that it,
518 itself, isn't reachable by the public internet).
517 -* `legacy-v1` - **DEPRECATED** Same as `enabled` but only V1 service is enabled. Used for testing
519 +- `legacy-v1` - **DEPRECATED** Same as `enabled` but only V1 service is enabled. Used for testing
520 during as few releases as we [transition to V2](https://github.com/ipfs/kubo/issues/10091), will be removed in the future.
519 -* `disabled` - Disable the service.
521 +- `disabled` - Disable the service.
522
523 Additional modes may be added in the future.
524
@@ -620,6 +622,7 @@ AutoConf can resolve `"auto"` placeholders in the following configuration fields
622 AutoConf supports path-based routing URLs that automatically enable specific routing operations based on the URL path. This allows precise control over which HTTP Routing V1 endpoints are used for different operations:
623
624 **Supported paths:**
625 +
626 - `/routing/v1/providers` - Enables provider record lookups only
627 - `/routing/v1/peers` - Enables peer routing lookups only
628 - `/routing/v1/ipns` - Enables IPNS record operations only
@@ -648,6 +651,7 @@ AutoConf supports path-based routing URLs that automatically enable specific rou
651 ```
652
653 **Node type categories:**
654 +
655 - `mainnet-for-nodes-with-dht`: Mainnet nodes with DHT enabled (typically only need additional provider lookups)
656 - `mainnet-for-nodes-without-dht`: Mainnet nodes without DHT (need comprehensive routing services)
657 - `mainnet-for-ipns-publishers-with-http`: Mainnet nodes that publish IPNS records via HTTP
@@ -822,7 +826,6 @@ Default: [certmagic.LetsEncryptProductionCA](https://pkg.go.dev/github.com/caddy
826
827 Type: `optionalString`
828
825 -
829 ## `Bitswap`
830
831 High level client and server configuration of the [Bitswap Protocol](https://specs.ipfs.tech/bitswap-protocol/) over libp2p.
@@ -861,6 +864,7 @@ Bootstrap peers help your node discover and connect to the IPFS network when sta
864 The special value `"auto"` automatically uses curated, up-to-date bootstrap peers from [AutoConf](#autoconf), ensuring your node can always connect to the healthy network without manual maintenance.
865
866 **What this gives you:**
867 +
868 - **Reliable startup**: Your node can always find the network, even if some bootstrap peers go offline
869 - **Automatic updates**: New bootstrap peers are added as the network evolves
870 - **Custom control**: Add your own trusted peers alongside or instead of the defaults
@@ -963,7 +967,7 @@ cache, which caches block-cids and their block-sizes. Use `0` to disable.
967
968 This cache, once primed, can greatly speed up operations like `ipfs repo stat`
969 as there is no need to read full blocks to know their sizes. Size should be
966 -adjusted depending on the number of CIDs on disk (`NumObjects in `ipfs repo stat`).
970 +adjusted depending on the number of CIDs on disk (`NumObjects in`ipfs repo stat`).
971
972 Default: `65536` (64KiB)
973
@@ -979,6 +983,7 @@ datastores to provide extra functionality (eg metrics, logging, or caching).
983 > For more information on possible values for this configuration option, see [`kubo/docs/datastores.md`](datastores.md)
984
985 Default:
986 +
987 ```
988 {
989 "mounts": [
@@ -1003,6 +1008,7 @@ Default:
1008 ```
1009
1010 With `flatfs-measure` profile:
1011 +
1012 ```
1013 {
1014 "mounts": [
@@ -1063,7 +1069,7 @@ Toggle and configure experimental features of Kubo. Experimental features are li
1069
1070 Options for the HTTP gateway.
1071
1066 -**NOTE:** support for `/api/v0` under the gateway path is now deprecated. It will be removed in future versions: https://github.com/ipfs/kubo/issues/10312.
1072 +**NOTE:** support for `/api/v0` under the gateway path is now deprecated. It will be removed in future versions: <https://github.com/ipfs/kubo/issues/10312>.
1073
1074 ### `Gateway.NoFetch`
1075
@@ -1088,7 +1094,7 @@ Type: `bool`
1094
1095 An optional flag to explicitly configure whether this gateway responds to deserialized
1096 requests, or not. By default, it is enabled. When disabling this option, the gateway
1091 -operates as a Trustless Gateway only: https://specs.ipfs.tech/http-gateways/trustless-gateway/.
1097 +operates as a Trustless Gateway only: <https://specs.ipfs.tech/http-gateways/trustless-gateway/>.
1098
1099 Default: `true`
1100
@@ -1127,10 +1133,12 @@ Type: `flag`
1133 Maximum duration Kubo will wait for content retrieval (new bytes to arrive).
1134
1135 **Timeout behavior:**
1136 +
1137 - **Time to first byte**: Returns 504 Gateway Timeout if the gateway cannot start writing within this duration (e.g., stuck searching for providers)
1138 - **Time between writes**: After first byte, timeout resets with each write. Response terminates if no new data can be written within this duration
1139
1140 **Truncation handling:** When timeout occurs after HTTP 200 headers are sent (e.g., during CAR streams), the gateway:
1141 +
1142 - Appends error message to indicate truncation
1143 - Forces TCP reset (RST) to prevent caching incomplete responses
1144 - Records in metrics with original status code and `truncated=true` flag
@@ -1138,9 +1146,10 @@ Maximum duration Kubo will wait for content retrieval (new bytes to arrive).
1146 **Monitoring:** Track `ipfs_http_gw_retrieval_timeouts_total` by status code and truncation status.
1147
1148 **Tuning guidance:**
1149 +
1150 - Compare timeout rates (`ipfs_http_gw_retrieval_timeouts_total`) with success rates (`ipfs_http_gw_responses_total{status="200"}`)
1151 - High timeout rate: consider increasing timeout or scaling horizontally if hardware is constrained
1143 -- Many 504s may indicate routing problems - check requested CIDs and provider availability using https://check.ipfs.network/
1152 +- Many 504s may indicate routing problems - check requested CIDs and provider availability using <https://check.ipfs.network/>
1153 - `truncated=true` timeouts indicate retrieval stalled mid-file with no new bytes for the timeout duration
1154
1155 A value of 0 disables this timeout.
@@ -1158,6 +1167,7 @@ Protects nodes from traffic spikes and resource exhaustion, especially behind re
1167 **Monitoring:** `ipfs_http_gw_concurrent_requests` tracks current requests in flight.
1168
1169 **Tuning guidance:**
1170 +
1171 - Monitor `ipfs_http_gw_concurrent_requests` gauge for usage patterns
1172 - Track 429s (`ipfs_http_gw_responses_total{status="429"}`) and success rate (`{status="200"}`)
1173 - Near limit with low resource usage → increase value
@@ -1229,6 +1239,7 @@ or limit `verifiable.example.net` to response types defined in [Trustless Gatewa
1239 Hostnames can optionally be defined with one or more wildcards.
1240
1241 Examples:
1242 +
1243 - `*.example.com` will match requests to `http://foo.example.com/ipfs/*` or `http://{cid}.ipfs.bar.example.com/*`.
1244 - `foo-*.example.com` will match requests to `http://foo-bar.example.com/ipfs/*` or `http://{cid}.ipfs.foo-xyz.example.com/*`.
1245
@@ -1237,6 +1248,7 @@ Examples:
1248 An array of paths that should be exposed on the hostname.
1249
1250 Example:
1251 +
1252 ```json
1253 {
1254 "Gateway": {
@@ -1263,8 +1275,9 @@ and provide [Origin isolation](https://developer.mozilla.org/en-US/docs/Web/Secu
1275 between content roots.
1276
1277 - `true` - enables [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://*.{hostname}/`
1266 - - **Requires whitelist:** make sure respective `Paths` are set.
1278 + - **Requires whitelist:** make sure respective `Paths` are set.
1279 For example, `Paths: ["/ipfs", "/ipns"]` are required for `http://{cid}.ipfs.{hostname}` and `http://{foo}.ipns.{hostname}` to work:
1280 +
1281 ```json
1282 "Gateway": {
1283 "PublicGateways": {
@@ -1275,10 +1288,12 @@ between content roots.
1288 }
1289 }
1290 ```
1278 - - **Backward-compatible:** requests for content paths such as `http://{hostname}/ipfs/{cid}` produce redirect to `http://{cid}.ipfs.{hostname}`
1291 +
1292 + - **Backward-compatible:** requests for content paths such as `http://{hostname}/ipfs/{cid}` produce redirect to `http://{cid}.ipfs.{hostname}`
1293
1294 - `false` - enables [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://{hostname}/*`
1295 - Example:
1296 +
1297 ```json
1298 "Gateway": {
1299 "PublicGateways": {
@@ -1317,7 +1332,7 @@ into a single DNS label ([specification](https://specs.ipfs.tech/http-gateways/s
1332 DNSLink name inlining allows for HTTPS on public subdomain gateways with single
1333 label wildcard TLS certs (also enabled when passing `X-Forwarded-Proto: https`),
1334 and provides disjoint Origin per root CID when special rules like
1320 -https://publicsuffix.org, or a custom localhost logic in browsers like Brave
1335 +<https://publicsuffix.org>, or a custom localhost logic in browsers like Brave
1336 has to be applied.
1337
1338 Default: `false`
@@ -1344,6 +1359,7 @@ Type: `flag`
1359
1360 Default entries for `localhost` hostname and loopback IPs are always present.
1361 If additional config is provided for those hostnames, it will be merged on top of implicit values:
1362 +
1363 ```json
1364 {
1365 "Gateway": {
@@ -1363,14 +1379,15 @@ For example, to disable subdomain gateway on `localhost`
1379 and make that hostname act the same as `127.0.0.1`:
1380
1381 ```console
1366 -$ ipfs config --json Gateway.PublicGateways '{"localhost": null }'
1382 +ipfs config --json Gateway.PublicGateways '{"localhost": null }'
1383 ```
1384
1385 ### `Gateway` recipes
1386
1387 Below is a list of the most common gateway setups.
1388
1373 -* Public [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://{cid}.ipfs.dweb.link` (each content root gets its own Origin)
1389 +- Public [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://{cid}.ipfs.dweb.link` (each content root gets its own Origin)
1390 +
1391 ```console
1392 $ ipfs config --json Gateway.PublicGateways '{
1393 "dweb.link": {
@@ -1379,23 +1396,24 @@ Below is a list of the most common gateway setups.
1396 }
1397 }'
1398 ```
1382 - - **Performance:** Consider enabling `Routing.AcceleratedDHTClient=true` to improve content routing lookups. Separately, gateway operators should decide if the gateway node should also co-host and provide (announce) fetched content to the DHT. If providing content, enable `Provide.DHT.SweepEnabled=true` for efficient announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`. For a read-only gateway that doesn't announce content, use `Provide.Enabled=false`.
1383 - - **Backward-compatible:** this feature enables automatic redirects from content paths to subdomains:
1399 +
1400 + - **Performance:** Consider enabling `Routing.AcceleratedDHTClient=true` to improve content routing lookups. Separately, gateway operators should decide if the gateway node should also co-host and provide (announce) fetched content to the DHT. If providing content, enable `Provide.DHT.SweepEnabled=true` for efficient announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`. For a read-only gateway that doesn't announce content, use `Provide.Enabled=false`.
1401 + - **Backward-compatible:** this feature enables automatic redirects from content paths to subdomains:
1402
1403 `http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.dweb.link`
1404
1387 - - **X-Forwarded-Proto:** if you run Kubo behind a reverse proxy that provides TLS, make it add a `X-Forwarded-Proto: https` HTTP header to ensure users are redirected to `https://`, not `http://`. It will also ensure DNSLink names are inlined to fit in a single DNS label, so they work fine with a wildcard TLS cert ([details](https://github.com/ipfs/in-web-browsers/issues/169)). The NGINX directive is `proxy_set_header X-Forwarded-Proto "https";`.:
1405 + - **X-Forwarded-Proto:** if you run Kubo behind a reverse proxy that provides TLS, make it add a `X-Forwarded-Proto: https` HTTP header to ensure users are redirected to `https://`, not `http://`. It will also ensure DNSLink names are inlined to fit in a single DNS label, so they work fine with a wildcard TLS cert ([details](https://github.com/ipfs/in-web-browsers/issues/169)). The NGINX directive is `proxy_set_header X-Forwarded-Proto "https";`.:
1406
1407 `http://dweb.link/ipfs/{cid}` → `https://{cid}.ipfs.dweb.link`
1408
1409 `http://dweb.link/ipns/your-dnslink.site.example.com` → `https://your--dnslink-site-example-com.ipfs.dweb.link`
1410
1393 - - **X-Forwarded-Host:** we also support `X-Forwarded-Host: example.com` if you want to override subdomain gateway host from the original request:
1411 + - **X-Forwarded-Host:** we also support `X-Forwarded-Host: example.com` if you want to override subdomain gateway host from the original request:
1412
1413 `http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.example.com`
1414
1415 +- Public [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://ipfs.io/ipfs/{cid}` (no Origin separation)
1416
1398 -* Public [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://ipfs.io/ipfs/{cid}` (no Origin separation)
1417 ```console
1418 $ ipfs config --json Gateway.PublicGateways '{
1419 "ipfs.io": {
@@ -1404,15 +1422,18 @@ Below is a list of the most common gateway setups.
1422 }
1423 }'
1424 ```
1407 - - **Performance:** Consider enabling `Routing.AcceleratedDHTClient=true` to improve content routing lookups. When running an open, recursive gateway, decide if the gateway should also co-host and provide (announce) fetched content to the DHT. If providing content, enable `Provide.DHT.SweepEnabled=true` for efficient announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`. For a read-only gateway that doesn't announce content, use `Provide.Enabled=false`.
1425
1409 -* Public [DNSLink](https://dnslink.io/) gateway resolving every hostname passed in `Host` header.
1426 + - **Performance:** Consider enabling `Routing.AcceleratedDHTClient=true` to improve content routing lookups. When running an open, recursive gateway, decide if the gateway should also co-host and provide (announce) fetched content to the DHT. If providing content, enable `Provide.DHT.SweepEnabled=true` for efficient announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`. For a read-only gateway that doesn't announce content, use `Provide.Enabled=false`.
1427 +
1428 +- Public [DNSLink](https://dnslink.io/) gateway resolving every hostname passed in `Host` header.
1429 +
1430 ```console
1411 - $ ipfs config --json Gateway.NoDNSLink false
1431 + ipfs config --json Gateway.NoDNSLink false
1432 ```
1413 - * Note that `NoDNSLink: false` is the default (it works out of the box unless set to `true` manually)
1433
1415 -* Hardened, site-specific [DNSLink gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#dnslink-gateway).
1434 + - Note that `NoDNSLink: false` is the default (it works out of the box unless set to `true` manually)
1435 +
1436 +- Hardened, site-specific [DNSLink gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#dnslink-gateway).
1437
1438 Disable fetching of remote data (`NoFetch: true`) and resolving DNSLink at unknown hostnames (`NoDNSLink: true`).
1439 Then, enable DNSLink gateway only for the specific hostname (for which data
@@ -1680,9 +1701,10 @@ When `Ipns.MaxCacheTTL` is set, it defines the upper bound limit of how long a
1701 will be cached and read from cache before checking for updates.
1702
1703 **Examples:**
1683 -* `"1m"` IPNS results are cached 1m or less (good compromise for system where
1704 +
1705 +- `"1m"` IPNS results are cached 1m or less (good compromise for system where
1706 faster updates are desired).
1685 -* `"0s"` IPNS caching is effectively turned off (useful for testing, bad for production use)
1707 +- `"0s"` IPNS caching is effectively turned off (useful for testing, bad for production use)
1708 - **Note:** setting this to `0` will turn off TTL-based caching entirely.
1709 This is discouraged in production environments. It will make IPNS websites
1710 artificially slow because IPNS resolution results will expire as soon as
@@ -1692,7 +1714,6 @@ will be cached and read from cache before checking for updates.
1714
1715 Default: No upper bound, [TTL from IPNS Record](https://specs.ipfs.tech/ipns/ipns-record/#ttl-uint64) (see `ipns name publish --help`) is always respected.
1716
1695 -
1717 Type: `optionalDuration`
1718
1719 ### `Ipns.UsePubsub`
@@ -1782,6 +1803,7 @@ Type: `string` (filesystem path)
1803 Mountpoint for Mutable File System (MFS) behind the `ipfs files` API.
1804
1805 > [!CAUTION]
1806 +>
1807 > - Write support is highly experimental and not recommended for mission-critical deployments.
1808 > - Avoid storing lazy-loaded datasets in MFS. Exposing a partially local, lazy-loaded DAG risks operating system search indexers crawling it, which may trigger unintended network prefetching of non-local DAG components.
1809
@@ -1806,13 +1828,14 @@ A remote pinning service is a remote service that exposes an API for managing
1828 that service's interest in long-term data storage.
1829
1830 The exposed API conforms to the specification defined at
1809 -https://ipfs.github.io/pinning-services-api-spec/
1831 +<https://ipfs.github.io/pinning-services-api-spec/>
1832
1833 #### `Pinning.RemoteServices: API`
1834
1835 Contains information relevant to utilizing the remote pinning service
1836
1837 Example:
1838 +
1839 ```json
1840 {
1841 "Pinning": {
@@ -1832,7 +1855,7 @@ Example:
1855
1856 The HTTP(S) endpoint through which to access the pinning service
1857
1835 -Example: "https://pinningservice.tld:1234/my/api/path"
1858 +Example: "<https://pinningservice.tld:1234/my/api/path>"
1859
1860 Type: `string`
1861
@@ -1884,9 +1907,9 @@ Type: `duration`
1907
1908 ## `Provide`
1909
1887 -Configures CID announcements to the routing system, including both immediate
1888 -announcements for new content (provide) and periodic re-announcements
1889 -(reprovide) on systems that require it, like Amino DHT. While designed to support
1910 +Configures CID announcements to the routing system, including both immediate
1911 +announcements for new content (provide) and periodic re-announcements
1912 +(reprovide) on systems that require it, like Amino DHT. While designed to support
1913 multiple routing systems in the future, the current default configuration only supports providing to the Amino DHT.
1914
1915 ### `Provide.Enabled`
@@ -1918,7 +1941,7 @@ Tells the provide system what should be announced. Valid strategies are:
1941 happens to already be connected to a provider and asks for child CID over
1942 bitswap.
1943 - `"mfs"` - announce only the local CIDs that are part of the MFS (`ipfs files`)
1921 - - Note: MFS is lazy-loaded. Only the MFS blocks present in local datastore are announced.
1944 + - Note: MFS is lazy-loaded. Only the MFS blocks present in local datastore are announced.
1945 - `"pinned+mfs"` - a combination of the `pinned` and `mfs` strategies.
1946 - **ℹ️ NOTE:** This is the suggested strategy for users who run without GC and don't want to provide everything in cache.
1947 - Order: first `pinned` and then the locally available part of `mfs`.
@@ -1945,9 +1968,11 @@ You can monitor the effectiveness of your provide configuration through metrics
1968 Different metrics are available depending on whether you use legacy mode (`SweepEnabled=false`) or sweep mode (`SweepEnabled=true`). See [Provide metrics documentation](https://github.com/ipfs/kubo/blob/master/docs/metrics.md#provide) for details.
1969
1970 To enable detailed debug logging for both providers, set:
1971 +
1972 ```sh
1973 GOLOG_LOG_LEVEL=error,provider=debug,dht/provider=debug
1974 ```
1975 +
1976 - `provider=debug` enables generic logging (legacy provider and any non-dht operations)
1977 - `dht/provider=debug` enables logging for the sweep provider
1978
@@ -1980,11 +2005,13 @@ Type: `optionalDuration` (unset for the default)
2005 Sets the maximum number of _concurrent_ DHT provide operations.
2006
2007 **When `Provide.DHT.SweepEnabled` is false (legacy mode):**
2008 +
2009 - Controls NEW CID announcements only
2010 - Reprovide operations do **not** count against this limit
2011 - A value of `0` allows unlimited provide workers
2012
2013 **When `Provide.DHT.SweepEnabled` is true:**
2014 +
2015 - Controls the total worker pool for both provide and reprovide operations
2016 - Workers are split between periodic reprovides and burst provides
2017 - Use a positive value to control resource usage
@@ -2000,7 +2027,7 @@ connections this setting can generate.
2027 > [!CAUTION]
2028 > For nodes without strict connection limits that need to provide large volumes
2029 > of content, we recommend first trying `Provide.DHT.SweepEnabled=true` for efficient
2003 -> announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`.
2030 +> announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`.
2031 > As a last resort, consider enabling `Routing.AcceleratedDHTClient=true` but be aware that it is very resource hungry.
2032 >
2033 > At the same time, mind that raising this value too high may lead to increased load.
@@ -2018,7 +2045,7 @@ both provides and reprovides.
2045
2046 Provide Sweep is a resource efficient technique for advertising content to
2047 the Amino DHT swarm. The Provide Sweep module tracks the keys that should be periodically reprovided in
2021 -the `KeyStore`. It splits the keys into DHT keyspace regions by proximity (XOR
2048 +the `Keystore`. It splits the keys into DHT keyspace regions by proximity (XOR
2049 distance), and schedules when reprovides should happen in order to spread the
2050 reprovide operation over time to avoid a spike in resource utilization. It
2051 basically sweeps the keyspace _from left to right_ over the
@@ -2030,11 +2057,11 @@ module, and is currently opt-in. You can compare the effectiveness of sweep mode
2057
2058 Whenever new keys should be advertised to the Amino DHT, `kubo` calls
2059 `StartProviding()`, triggering an initial `provide` operation for the given
2033 -keys. The keys will be added to the `KeyStore` tracking which keys should be
2060 +keys. The keys will be added to the `Keystore` tracking which keys should be
2061 reprovided and when they should be reprovided. Calling `StopProviding()`
2035 -removes the keys from the `KeyStore`. However, it is currently tricky for
2062 +removes the keys from the `Keystore`. However, it is currently tricky for
2063 `kubo` to detect when a key should stop being advertised. Hence, `kubo` will
2037 -periodically refresh the `KeyStore` at each [`Provide.DHT.Interval`](#providedhtinterval)
2064 +periodically refresh the `Keystore` at each [`Provide.DHT.Interval`](#providedhtinterval)
2065 by providing it a channel of all the keys it is expected to contain according
2066 to the [`Provide.Strategy`](#providestrategy). During this operation,
2067 all keys in the `Keystore` are purged, and only the given ones remain scheduled.
@@ -2053,7 +2080,6 @@ all keys in the `Keystore` are purged, and only the given ones remain scheduled.
2080 >
2081 > Sweep mode provides similar effectiveness to Accelerated DHT but with steady resource usage - better for machines with limited CPU, memory, or network bandwidth.
2082
2056 -
2083 > [!NOTE]
2084 > This feature is opt-in for now, but will become the default in a future release.
2085 > Eventually, this configuration flag will be removed once the feature is stable.
@@ -2062,15 +2088,14 @@ Default: `false`
2088
2089 Type: `flag`
2090
2065 -
2091 #### `Provide.DHT.DedicatedPeriodicWorkers`
2092
2093 Number of workers dedicated to periodic keyspace region reprovides. Only applies when `Provide.DHT.SweepEnabled` is true.
2094
2095 Among the [`Provide.DHT.MaxWorkers`](#providedhtmaxworkers), this
2071 -number of workers will be dedicated to the periodic region reprovide only. The sum of
2072 -`DedicatedPeriodicWorkers` and `DedicatedBurstWorkers` should not exceed `MaxWorkers`.
2073 -Any remaining workers (MaxWorkers - DedicatedPeriodicWorkers - DedicatedBurstWorkers)
2096 +number of workers will be dedicated to the periodic region reprovide only. The sum of
2097 +`DedicatedPeriodicWorkers` and `DedicatedBurstWorkers` should not exceed `MaxWorkers`.
2098 +Any remaining workers (MaxWorkers - DedicatedPeriodicWorkers - DedicatedBurstWorkers)
2099 form a shared pool that can be used for either type of work as needed.
2100
2101 Default: `2`
@@ -2083,6 +2108,7 @@ operation can be performed by free non-dedicated workers)
2108 Number of workers dedicated to burst provides. Only applies when `Provide.DHT.SweepEnabled` is true.
2109
2110 Burst provides are triggered by:
2111 +
2112 - Manual provide commands (`ipfs routing provide`)
2113 - New content matching your `Provide.Strategy` (blocks from `ipfs add`, bitswap, or trustless gateway requests)
2114 - Catch-up reprovides after being disconnected/offline for a while
@@ -2120,10 +2146,10 @@ Default: `16`
2146
2147 Type: `optionalInteger` (non-negative)
2148
2123 -#### `Provide.DHT.KeyStoreBatchSize`
2149 +#### `Provide.DHT.KeystoreBatchSize`
2150
2125 -During the garbage collection, all keys stored in the KeyStore are removed, and
2126 -the keys are streamed from a channel to fill the KeyStore again with up-to-date
2151 +During the garbage collection, all keys stored in the Keystore are removed, and
2152 +the keys are streamed from a channel to fill the Keystore again with up-to-date
2153 keys. Since a high number of CIDs to reprovide can easily fill up the memory,
2154 keys are read and written in batches to optimize for memory usage.
2155
@@ -2173,6 +2199,7 @@ This field was unused. Use [`Provide.Strategy`](#providestrategy) instead.
2199 **REMOVED**
2200
2201 Replaced with [`Provide.DHT.MaxWorkers`](#providedhtmaxworkers).
2202 +
2203 ## `Pubsub`
2204
2205 **DEPRECATED**: See [#9717](https://github.com/ipfs/kubo/issues/9717)
@@ -2197,9 +2224,9 @@ Type: `flag`
2224
2225 Sets the default router used by pubsub to route messages to peers. This can be one of:
2226
2200 -* `"floodsub"` - floodsub is a basic router that simply _floods_ messages to all
2227 +- `"floodsub"` - floodsub is a basic router that simply _floods_ messages to all
2228 connected peers. This router is extremely inefficient but _very_ reliable.
2202 -* `"gossipsub"` - [gossipsub][] is a more advanced routing algorithm that will
2229 +- `"gossipsub"` - [gossipsub][] is a more advanced routing algorithm that will
2230 build an overlay mesh from a subset of the links in the network.
2231
2232 Default: `"gossipsub"`
@@ -2278,11 +2305,11 @@ improve reliability.
2305
2306 Use-cases:
2307
2281 -* An IPFS gateway connected to an IPFS cluster should peer to ensure that the
2308 +- An IPFS gateway connected to an IPFS cluster should peer to ensure that the
2309 gateway can always fetch content from the cluster.
2283 -* A dapp may peer embedded Kubo nodes with a set of pinning services or
2310 +- A dapp may peer embedded Kubo nodes with a set of pinning services or
2311 textile cafes/hubs.
2285 -* A set of friends may peer to ensure that they can always fetch each other's
2312 +- A set of friends may peer to ensure that they can always fetch each other's
2313 content.
2314
2315 When a node is added to the set of peered nodes, Kubo will:
@@ -2298,9 +2325,9 @@ When a node is added to the set of peered nodes, Kubo will:
2325
2326 Peering can be asymmetric or symmetric:
2327
2301 -* When symmetric, the connection will be protected by both nodes and will likely
2328 +- When symmetric, the connection will be protected by both nodes and will likely
2329 be very stable.
2303 -* When asymmetric, only one node (the node that configured peering) will protect
2330 +- When asymmetric, only one node (the node that configured peering) will protect
2331 the connection and attempt to re-connect to the peered node on disconnect. If
2332 the peered node is under heavy load and/or has a low connection limit, the
2333 connection may flap repeatedly. Be careful when asymmetrically peering to not
@@ -2349,6 +2376,7 @@ Replaced with [`Provide.DHT.Interval`](#providedhtinterval).
2376 **REMOVED**
2377
2378 Replaced with [`Provide.Strategy`](#providestrategy).
2379 +
2380 ## `Routing`
2381
2382 Contains options for content, peer, and IPNS routing mechanisms.
@@ -2357,25 +2385,25 @@ Contains options for content, peer, and IPNS routing mechanisms.
2385
2386 There are multiple routing options: "auto", "autoclient", "none", "dht", "dhtclient", "delegated", and "custom".
2387
2360 -* **DEFAULT:** If unset, or set to "auto", your node will use the public IPFS DHT (aka "Amino")
2388 +- **DEFAULT:** If unset, or set to "auto", your node will use the public IPFS DHT (aka "Amino")
2389 and parallel [`Routing.DelegatedRouters`](#routingdelegatedrouters) for additional speed.
2390
2363 -* If set to "autoclient", your node will behave as in "auto" but without running a DHT server.
2391 +- If set to "autoclient", your node will behave as in "auto" but without running a DHT server.
2392
2365 -* If set to "none", your node will use _no_ routing system. You'll have to
2393 +- If set to "none", your node will use _no_ routing system. You'll have to
2394 explicitly connect to peers that have the content you're looking for.
2395
2368 -* If set to "dht" (or "dhtclient"/"dhtserver"), your node will ONLY use the Amino DHT (no HTTP routers).
2396 +- If set to "dht" (or "dhtclient"/"dhtserver"), your node will ONLY use the Amino DHT (no HTTP routers).
2397
2370 -* If set to "custom", all default routers are disabled, and only ones defined in `Routing.Routers` will be used.
2398 +- If set to "custom", all default routers are disabled, and only ones defined in `Routing.Routers` will be used.
2399
2400 When the DHT is enabled, it can operate in two modes: client and server.
2401
2374 -* In server mode, your node will query other peers for DHT records, and will
2402 +- In server mode, your node will query other peers for DHT records, and will
2403 respond to requests from other peers (both requests to store records and
2404 requests to retrieve records).
2405
2378 -* In client mode, your node will query the DHT as a client but will not respond
2406 +- In client mode, your node will query the DHT as a client but will not respond
2407 to requests from other peers. This mode is less resource-intensive than server
2408 mode.
2409
@@ -2395,7 +2423,7 @@ in addition to the Amino DHT.
2423 When `Routing.Type` is set to `delegated`, your node will use **only** HTTP delegated routers and IPNS publishers,
2424 without initializing the Amino DHT at all. This mode is useful for environments where peer-to-peer DHT connectivity
2425 is not available or desired, while still enabling content routing and IPNS publishing via HTTP APIs.
2398 -This mode requires configuring [`Routing.DelegatedRouters`](#routingdelegatedrouters) for content routing and
2426 +This mode requires configuring [`Routing.DelegatedRouters`](#routingdelegatedrouters) for content routing and
2427 [`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers) for IPNS publishing.
2428
2429 **Note:** `delegated` mode operates as read-only for content providing - your node cannot announce content to the network
@@ -2407,7 +2435,6 @@ Default: `auto` (DHT + [`Routing.DelegatedRouters`](#routingdelegatedrouters))
2435
2436 Type: `optionalString` (`null`/missing means the default)
2437
2410 -
2438 ### `Routing.AcceleratedDHTClient`
2439
2440 This alternative Amino DHT client with a Full-Routing-Table strategy will
@@ -2424,6 +2451,7 @@ This is not compatible with `Routing.Type` `custom`. If you are using composable
2451 you can configure this individually on each router.
2452
2453 When it is enabled:
2454 +
2455 - Client DHT operations (reads and writes) should complete much faster
2456 - The provider will now use a keyspace sweeping mode allowing to keep alive
2457 CID sets that are multiple orders of magnitude larger.
@@ -2437,6 +2465,7 @@ When it is enabled:
2465 - The operations `ipfs stats dht` will default to showing information about the accelerated DHT client
2466
2467 **Caveats:**
2468 +
2469 1. Running the accelerated client likely will result in more resource consumption (connections, RAM, CPU, bandwidth)
2470 - Users that are limited in the number of parallel connections their machines/networks can perform will likely suffer
2471 - The resource usage is not smooth as the client crawls the network in rounds and reproviding is similarly done in rounds
@@ -2540,29 +2569,33 @@ Type: `string`
2569 Parameters needed to create the specified router. Supported params per router type:
2570
2571 HTTP:
2543 - - `Endpoint` (mandatory): URL that will be used to connect to a specified router.
2544 - - `MaxProvideBatchSize`: This number determines the maximum amount of CIDs sent per batch. Servers might not accept more than 100 elements per batch. 100 elements by default.
2545 - - `MaxProvideConcurrency`: It determines the number of threads used when providing content. GOMAXPROCS by default.
2572 +
2573 +- `Endpoint` (mandatory): URL that will be used to connect to a specified router.
2574 +- `MaxProvideBatchSize`: This number determines the maximum amount of CIDs sent per batch. Servers might not accept more than 100 elements per batch. 100 elements by default.
2575 +- `MaxProvideConcurrency`: It determines the number of threads used when providing content. GOMAXPROCS by default.
2576
2577 DHT:
2548 - - `"Mode"`: Mode used by the Amino DHT. Possible values: "server", "client", "auto"
2549 - - `"AcceleratedDHTClient"`: Set to `true` if you want to use the acceleratedDHT.
2550 - - `"PublicIPNetwork"`: Set to `true` to create a `WAN` DHT. Set to `false` to create a `LAN` DHT.
2578 +
2579 +- `"Mode"`: Mode used by the Amino DHT. Possible values: "server", "client", "auto"
2580 +- `"AcceleratedDHTClient"`: Set to `true` if you want to use the acceleratedDHT.
2581 +- `"PublicIPNetwork"`: Set to `true` to create a `WAN` DHT. Set to `false` to create a `LAN` DHT.
2582
2583 Parallel:
2553 - - `Routers`: A list of routers that will be executed in parallel:
2554 - - `Name:string`: Name of the router. It should be one of the previously added to `Routers` list.
2555 - - `Timeout:duration`: Local timeout. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`). Time will start counting when this specific router is called, and it will stop when the router returns, or we reach the specified timeout.
2556 - - `ExecuteAfter:duration`: Providing this param will delay the execution of that router at the specified time. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`).
2557 - - `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred.
2558 - - `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`).
2584 +
2585 +- `Routers`: A list of routers that will be executed in parallel:
2586 + - `Name:string`: Name of the router. It should be one of the previously added to `Routers` list.
2587 + - `Timeout:duration`: Local timeout. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`). Time will start counting when this specific router is called, and it will stop when the router returns, or we reach the specified timeout.
2588 + - `ExecuteAfter:duration`: Providing this param will delay the execution of that router at the specified time. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`).
2589 + - `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred.
2590 +- `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`).
2591
2592 Sequential:
2561 - - `Routers`: A list of routers that will be executed in order:
2562 - - `Name:string`: Name of the router. It should be one of the previously added to `Routers` list.
2563 - - `Timeout:duration`: Local timeout. It accepts strings compatible with Go `time.ParseDuration(string)`. Time will start counting when this specific router is called, and it will stop when the router returns, or we reach the specified timeout.
2564 - - `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred.
2565 - - `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)`.
2593 +
2594 +- `Routers`: A list of routers that will be executed in order:
2595 + - `Name:string`: Name of the router. It should be one of the previously added to `Routers` list.
2596 + - `Timeout:duration`: Local timeout. It accepts strings compatible with Go `time.ParseDuration(string)`. Time will start counting when this specific router is called, and it will stop when the router returns, or we reach the specified timeout.
2597 + - `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred.
2598 +- `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)`.
2599
2600 Default: `{}` (use the safe implicit defaults)
2601
@@ -2580,6 +2613,7 @@ Type: `object[string->string]`
2613 The key will be the name of the method: `"provide"`, `"find-providers"`, `"find-peers"`, `"put-ipns"`, `"get-ipns"`. All methods must be added to the list.
2614
2615 The value will contain:
2616 +
2617 - `RouterName:string`: Name of the router. It should be one of the previously added to `Routing.Routers` list.
2618
2619 Type: `object[string->object]`
@@ -2789,7 +2823,6 @@ Default: `131072` (128 kb)
2823
2824 Type: `optionalInteger`
2825
2792 -
2826 #### `Swarm.RelayService.ReservationTTL`
2827
2828 Duration of a new or refreshed reservation.
@@ -2798,7 +2831,6 @@ Default: `"1h"`
2831
2832 Type: `duration`
2833
2801 -
2834 #### `Swarm.RelayService.MaxReservations`
2835
2836 Maximum number of active relay slots.
@@ -2807,7 +2839,6 @@ Default: `128`
2839
2840 Type: `optionalInteger`
2841
2810 -
2842 #### `Swarm.RelayService.MaxCircuits`
2843
2844 Maximum number of open relay connections for each peer.
@@ -2816,7 +2847,6 @@ Default: `16`
2847
2848 Type: `optionalInteger`
2849
2819 -
2850 #### `Swarm.RelayService.BufferSize`
2851
2852 Size of the relayed connection buffers.
@@ -2825,7 +2855,6 @@ Default: `2048`
2855
2856 Type: `optionalInteger`
2857
2828 -
2858 #### `Swarm.RelayService.MaxReservationsPerPeer`
2859
2860 **REMOVED in kubo 0.32 due to [go-libp2p#2974](https://github.com/libp2p/go-libp2p/pull/2974)**
@@ -2869,8 +2898,8 @@ Please use [`AutoNAT.ServiceMode`](#autonatservicemode).
2898 The connection manager determines which and how many connections to keep and can
2899 be configured to keep. Kubo currently supports two connection managers:
2900
2872 -* none: never close idle connections.
2873 -* basic: the default connection manager.
2901 +- none: never close idle connections.
2902 +- basic: the default connection manager.
2903
2904 By default, this section is empty and the implicit defaults defined below
2905 are used.
@@ -2894,11 +2923,11 @@ connections. The process of closing connections happens every `SilencePeriod`.
2923
2924 The connection manager considers a connection idle if:
2925
2897 -* It has not been explicitly _protected_ by some subsystem. For example, Bitswap
2926 +- It has not been explicitly _protected_ by some subsystem. For example, Bitswap
2927 will protect connections to peers from which it is actively downloading data,
2928 the DHT will protect some peers for routing, and the peering subsystem will
2929 protect all "peered" nodes.
2901 -* It has existed for longer than the `GracePeriod`.
2930 +- It has existed for longer than the `GracePeriod`.
2931
2932 **Example:**
2933
@@ -3037,8 +3066,9 @@ Default: Enabled
3066 Type: `flag`
3067
3068 Listen Addresses:
3040 -* /ip4/0.0.0.0/tcp/4001 (default)
3041 -* /ip6/::/tcp/4001 (default)
3069 +
3070 +- /ip4/0.0.0.0/tcp/4001 (default)
3071 +- /ip6/::/tcp/4001 (default)
3072
3073 #### `Swarm.Transports.Network.Websocket`
3074
@@ -3053,8 +3083,9 @@ Default: Enabled
3083 Type: `flag`
3084
3085 Listen Addresses:
3056 -* /ip4/0.0.0.0/tcp/4001/ws
3057 -* /ip6/::/tcp/4001/ws
3086 +
3087 +- /ip4/0.0.0.0/tcp/4001/ws
3088 +- /ip6/::/tcp/4001/ws
3089
3090 #### `Swarm.Transports.Network.QUIC`
3091
@@ -3072,6 +3103,7 @@ Default: Enabled
3103 Type: `flag`
3104
3105 Listen Addresses:
3106 +
3107 - `/ip4/0.0.0.0/udp/4001/quic-v1` (default)
3108 - `/ip6/::/udp/4001/quic-v1` (default)
3109
@@ -3084,10 +3116,11 @@ Allows IPFS node to connect to other peers using their `/p2p-circuit`
3116 NATs.
3117
3118 See also:
3119 +
3120 - Docs: [Libp2p Circuit Relay](https://docs.libp2p.io/concepts/circuit-relay/)
3121 - [`Swarm.RelayClient.Enabled`](#swarmrelayclientenabled) for getting a public
3089 -- `/p2p-circuit` address when behind a firewall.
3090 - - [`Swarm.EnableHolePunching`](#swarmenableholepunching) for direct connection upgrade through relay
3122 +- `/p2p-circuit` address when behind a firewall.
3123 +- [`Swarm.EnableHolePunching`](#swarmenableholepunching) for direct connection upgrade through relay
3124 - [`Swarm.RelayService.Enabled`](#swarmrelayserviceenabled) for becoming a
3125 limited relay for other peers
3126
@@ -3096,9 +3129,9 @@ Default: Enabled
3129 Type: `flag`
3130
3131 Listen Addresses:
3099 -* This transport is special. Any node that enables this transport can receive
3100 - inbound connections on this transport, without specifying a listen address.
3132
3133 +- This transport is special. Any node that enables this transport can receive
3134 + inbound connections on this transport, without specifying a listen address.
3135
3136 #### `Swarm.Transports.Network.WebTransport`
3137
@@ -3121,6 +3154,7 @@ Default: Enabled
3154 Type: `flag`
3155
3156 Listen Addresses:
3157 +
3158 - `/ip4/0.0.0.0/udp/4001/quic-v1/webtransport` (default)
3159 - `/ip6/::/udp/4001/quic-v1/webtransport` (default)
3160
@@ -3151,6 +3185,7 @@ Default: Enabled
3185 Type: `flag`
3186
3187 Listen Addresses:
3188 +
3189 - `/ip4/0.0.0.0/udp/4001/webrtc-direct` (default)
3190 - `/ip6/::/udp/4001/webrtc-direct` (default)
3191
@@ -3223,7 +3258,7 @@ Type: `priority`
3258
3259 ### `Swarm.Transports.Multiplexers.Mplex`
3260
3226 -**REMOVED**: See https://github.com/ipfs/kubo/issues/9958
3261 +**REMOVED**: See <https://github.com/ipfs/kubo/issues/9958>
3262
3263 Support for Mplex has been [removed from Kubo and go-libp2p](https://github.com/libp2p/specs/issues/553).
3264 Please remove this option from your config.
@@ -3240,6 +3275,7 @@ This allows for overriding the default DNS resolver provided by the operating sy
3275 and using different resolvers per domain or TLD (including ones from alternative, non-ICANN naming systems).
3276
3277 Example:
3278 +
3279 ```json
3280 {
3281 "DNS": {
@@ -3254,9 +3290,10 @@ Example:
3290 ```
3291
3292 Be mindful that:
3293 +
3294 - Currently only `https://` URLs for [DNS over HTTPS (DoH)](https://en.wikipedia.org/wiki/DNS_over_HTTPS) endpoints are supported as values.
3295 - The default catch-all resolver is the cleartext one provided by your operating system. It can be overridden by adding a DoH entry for the DNS root indicated by `.` as illustrated above.
3259 -- Out-of-the-box support for selected non-ICANN TLDs relies on third-party centralized services provided by respective communities on best-effort basis.
3296 +- Out-of-the-box support for selected non-ICANN TLDs relies on third-party centralized services provided by respective communities on best-effort basis.
3297 - The special value `"auto"` uses DNS resolvers from [AutoConf](#autoconf) when enabled. For example: `{".": "auto"}` uses any custom DoH resolver (global or per TLD) provided by AutoConf system.
3298
3299 Default: `{".": "auto"}`
@@ -3273,8 +3310,9 @@ If present, the upper bound is applied to DoH resolvers in [`DNS.Resolvers`](#dn
3310 Note: this does NOT work with Go's default DNS resolver. To make this a global setting, add a `.` entry to `DNS.Resolvers` first.
3311
3312 **Examples:**
3276 -* `"1m"` DNS entries are kept for 1 minute or less.
3277 -* `"0s"` DNS entries expire as soon as they are retrieved.
3313 +
3314 +- `"1m"` DNS entries are kept for 1 minute or less.
3315 +- `"0s"` DNS entries expire as soon as they are retrieved.
3316
3317 Default: Respect DNS Response TTL
3318
@@ -3306,6 +3344,7 @@ and the HTTPS server returns HTTP 200 for the [probe path](https://specs.ipfs.te
3344 > This feature is relatively new. Please report any issues via [Github](https://github.com/ipfs/kubo/issues/new).
3345 >
3346 > Important notes:
3347 +>
3348 > - TLS and HTTP/2 are required. For privacy reasons, and to maintain feature-parity with browsers, unencrypted `http://` providers are ignored and not used.
3349 > - This feature works in the same way as Bitswap: connected HTTP-peers receive optimistic block requests even for content that they are not announcing.
3350 > - For performance reasons, and to avoid loops, the HTTP client does not follow redirects. Providers should keep announcements up to date.
@@ -3332,7 +3371,6 @@ Type: `array[string]`
3371 Optional list of hostnames for which HTTP retrieval is not allowed.
3372 Denylist entries take precedence over Allowlist entries.
3373
3335 -
3374 > [!TIP]
3375 > This denylist operates on HTTP endpoint hostnames.
3376 > To deny specific PeerID, use [`Routing.IgnoreProviders`](#routingignoreproviders) instead.
@@ -3404,6 +3442,7 @@ Type: `flag`
3442 The default UnixFS chunker. Commands affected: `ipfs add`.
3443
3444 Valid formats:
3445 +
3446 - `size-<bytes>` - fixed size chunker
3447 - `rabin-<min>-<avg>-<max>` - rabin fingerprint chunker
3448 - `buzhash` - buzhash chunker
@@ -3515,7 +3554,7 @@ networking stack. At the time of writing this, IPFS peers on the public swarm
3554 tend to ignore requests for blocks bigger than 2MiB.
3555
3556 Uses implementation from `boxo/ipld/unixfs/io/directory`, where the size is not
3518 -the *exact* block size of the encoded directory but just the estimated size
3557 +the _exact_ block size of the encoded directory but just the estimated size
3558 based byte length of DAG-PB Links names and CIDs.
3559
3560 Setting to `1B` is functionally equivalent to always using HAMT (useful in testing).
@@ -3538,7 +3577,7 @@ Optional suffix to the AgentVersion presented by `ipfs id` and exposed via [libp
3577 The value from config takes precedence over value passed via `ipfs daemon --agent-version-suffix`.
3578
3579 > [!NOTE]
3541 -> Setting a custom version suffix helps with ecosystem analysis, such as Amino DHT reports published at https://stats.ipfs.network
3580 +> Setting a custom version suffix helps with ecosystem analysis, such as Amino DHT reports published at <https://stats.ipfs.network>
3581
3582 Default: `""` (no suffix, or value from `ipfs daemon --agent-version-suffix=`)
3583