config.md
1 # The Kubo config file 2 3 The Kubo config file is a JSON document located at `$IPFS_PATH/config`. It 4 is read once at node instantiation, either for an offline command, or when 5 starting the daemon. Commands that execute on a running daemon do not read the 6 config file at runtime. 7 8 # Table of Contents 9 10 - [The Kubo config file](#the-kubo-config-file) 11 - [Table of Contents](#table-of-contents) 12 - [`Addresses`](#addresses) 13 - [`Addresses.API`](#addressesapi) 14 - [`Addresses.Gateway`](#addressesgateway) 15 - [`Addresses.Swarm`](#addressesswarm) 16 - [`Addresses.Announce`](#addressesannounce) 17 - [`Addresses.AppendAnnounce`](#addressesappendannounce) 18 - [`Addresses.NoAnnounce`](#addressesnoannounce) 19 - [`API`](#api) 20 - [`API.HTTPHeaders`](#apihttpheaders) 21 - [`API.Authorizations`](#apiauthorizations) 22 - [`API.Authorizations: AuthSecret`](#apiauthorizations-authsecret) 23 - [`API.Authorizations: AllowedPaths`](#apiauthorizations-allowedpaths) 24 - [`AutoNAT`](#autonat) 25 - [`AutoNAT.ServiceMode`](#autonatservicemode) 26 - [`AutoNAT.Throttle`](#autonatthrottle) 27 - [`AutoNAT.Throttle.GlobalLimit`](#autonatthrottlegloballimit) 28 - [`AutoNAT.Throttle.PeerLimit`](#autonatthrottlepeerlimit) 29 - [`AutoNAT.Throttle.Interval`](#autonatthrottleinterval) 30 - [`AutoTLS`](#autotls) 31 - [`AutoTLS.Enabled`](#autotlsenabled) 32 - [`AutoTLS.AutoWSS`](#autotlsautowss) 33 - [`AutoTLS.ShortAddrs`](#autotlsshortaddrs) 34 - [`AutoTLS.DomainSuffix`](#autotlsdomainsuffix) 35 - [`AutoTLS.RegistrationEndpoint`](#autotlsregistrationendpoint) 36 - [`AutoTLS.RegistrationToken`](#autotlsregistrationtoken) 37 - [`AutoTLS.RegistrationDelay`](#autotlsregistrationdelay) 38 - [`AutoTLS.CAEndpoint`](#autotlscaendpoint) 39 - [`AutoConf`](#autoconf) 40 - [`AutoConf.URL`](#autoconfurl) 41 - [`AutoConf.Enabled`](#autoconfenabled) 42 - [`AutoConf.RefreshInterval`](#autoconfrefreshinterval) 43 - [`AutoConf.TLSInsecureSkipVerify`](#autoconftlsinsecureskipverify) 44 - [`Bitswap`](#bitswap) 45 - [`Bitswap.Libp2pEnabled`](#bitswaplibp2penabled) 46 - [`Bitswap.ServerEnabled`](#bitswapserverenabled) 47 - [`Bootstrap`](#bootstrap) 48 - [`Datastore`](#datastore) 49 - [`Datastore.StorageMax`](#datastorestoragemax) 50 - [`Datastore.StorageGCWatermark`](#datastorestoragegcwatermark) 51 - [`Datastore.GCPeriod`](#datastoregcperiod) 52 - [`Datastore.HashOnRead`](#datastorehashonread) 53 - [`Datastore.BloomFilterSize`](#datastorebloomfiltersize) 54 - [`Datastore.WriteThrough`](#datastorewritethrough) 55 - [`Datastore.BlockKeyCacheSize`](#datastoreblockkeycachesize) 56 - [`Datastore.Spec`](#datastorespec) 57 - [`Discovery`](#discovery) 58 - [`Discovery.MDNS`](#discoverymdns) 59 - [`Discovery.MDNS.Enabled`](#discoverymdnsenabled) 60 - [`Discovery.MDNS.Interval`](#discoverymdnsinterval) 61 - [`Experimental`](#experimental) 62 - [`Experimental.Libp2pStreamMounting`](#experimentallibp2pstreammounting) 63 - [`Gateway`](#gateway) 64 - [`Gateway.NoFetch`](#gatewaynofetch) 65 - [`Gateway.NoDNSLink`](#gatewaynodnslink) 66 - [`Gateway.DeserializedResponses`](#gatewaydeserializedresponses) 67 - [`Gateway.AllowCodecConversion`](#gatewayallowcodecconversion) 68 - [`Gateway.DisableHTMLErrors`](#gatewaydisablehtmlerrors) 69 - [`Gateway.ExposeRoutingAPI`](#gatewayexposeroutingapi) 70 - [`Gateway.RetrievalTimeout`](#gatewayretrievaltimeout) 71 - [`Gateway.MaxRequestDuration`](#gatewaymaxrequestduration) 72 - [`Gateway.MaxRangeRequestFileSize`](#gatewaymaxrangerequestfilesize) 73 - [`Gateway.MaxConcurrentRequests`](#gatewaymaxconcurrentrequests) 74 - [`Gateway.HTTPHeaders`](#gatewayhttpheaders) 75 - [`Gateway.RootRedirect`](#gatewayrootredirect) 76 - [`Gateway.DiagnosticServiceURL`](#gatewaydiagnosticserviceurl) 77 - [`Gateway.FastDirIndexThreshold`](#gatewayfastdirindexthreshold) 78 - [`Gateway.Writable`](#gatewaywritable) 79 - [`Gateway.PathPrefixes`](#gatewaypathprefixes) 80 - [`Gateway.PublicGateways`](#gatewaypublicgateways) 81 - [`Gateway.PublicGateways: Paths`](#gatewaypublicgateways-paths) 82 - [`Gateway.PublicGateways: UseSubdomains`](#gatewaypublicgateways-usesubdomains) 83 - [`Gateway.PublicGateways: NoDNSLink`](#gatewaypublicgateways-nodnslink) 84 - [`Gateway.PublicGateways: InlineDNSLink`](#gatewaypublicgateways-inlinednslink) 85 - [`Gateway.PublicGateways: DeserializedResponses`](#gatewaypublicgateways-deserializedresponses) 86 - [Implicit defaults of `Gateway.PublicGateways`](#implicit-defaults-of-gatewaypublicgateways) 87 - [`Gateway` recipes](#gateway-recipes) 88 - [`Identity`](#identity) 89 - [`Identity.PeerID`](#identitypeerid) 90 - [`Identity.PrivKey`](#identityprivkey) 91 - [`Internal`](#internal) 92 - [`Internal.Bitswap`](#internalbitswap) 93 - [`Internal.Bitswap.TaskWorkerCount`](#internalbitswaptaskworkercount) 94 - [`Internal.Bitswap.EngineBlockstoreWorkerCount`](#internalbitswapengineblockstoreworkercount) 95 - [`Internal.Bitswap.EngineTaskWorkerCount`](#internalbitswapenginetaskworkercount) 96 - [`Internal.Bitswap.MaxOutstandingBytesPerPeer`](#internalbitswapmaxoutstandingbytesperpeer) 97 - [`Internal.Bitswap.ProviderSearchDelay`](#internalbitswapprovidersearchdelay) 98 - [`Internal.Bitswap.ProviderSearchMaxResults`](#internalbitswapprovidersearchmaxresults) 99 - [`Internal.Bitswap.BroadcastControl`](#internalbitswapbroadcastcontrol) 100 - [`Internal.Bitswap.BroadcastControl.Enable`](#internalbitswapbroadcastcontrolenable) 101 - [`Internal.Bitswap.BroadcastControl.MaxPeers`](#internalbitswapbroadcastcontrolmaxpeers) 102 - [`Internal.Bitswap.BroadcastControl.LocalPeers`](#internalbitswapbroadcastcontrollocalpeers) 103 - [`Internal.Bitswap.BroadcastControl.PeeredPeers`](#internalbitswapbroadcastcontrolpeeredpeers) 104 - [`Internal.Bitswap.BroadcastControl.MaxRandomPeers`](#internalbitswapbroadcastcontrolmaxrandompeers) 105 - [`Internal.Bitswap.BroadcastControl.SendToPendingPeers`](#internalbitswapbroadcastcontrolsendtopendingpeers) 106 - [`Internal.UnixFSShardingSizeThreshold`](#internalunixfsshardingsizethreshold) 107 - [`Ipns`](#ipns) 108 - [`Ipns.RepublishPeriod`](#ipnsrepublishperiod) 109 - [`Ipns.RecordLifetime`](#ipnsrecordlifetime) 110 - [`Ipns.ResolveCacheSize`](#ipnsresolvecachesize) 111 - [`Ipns.MaxCacheTTL`](#ipnsmaxcachettl) 112 - [`Ipns.UsePubsub`](#ipnsusepubsub) 113 - [`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers) 114 - [`Migration`](#migration) 115 - [`Migration.DownloadSources`](#migrationdownloadsources) 116 - [`Migration.Keep`](#migrationkeep) 117 - [`Mounts`](#mounts) 118 - [`Mounts.IPFS`](#mountsipfs) 119 - [`Mounts.IPNS`](#mountsipns) 120 - [`Mounts.MFS`](#mountsmfs) 121 - [`Mounts.FuseAllowOther`](#mountsfuseallowother) 122 - [`Pinning`](#pinning) 123 - [`Pinning.RemoteServices`](#pinningremoteservices) 124 - [`Pinning.RemoteServices: API`](#pinningremoteservices-api) 125 - [`Pinning.RemoteServices: API.Endpoint`](#pinningremoteservices-apiendpoint) 126 - [`Pinning.RemoteServices: API.Key`](#pinningremoteservices-apikey) 127 - [`Pinning.RemoteServices: Policies`](#pinningremoteservices-policies) 128 - [`Pinning.RemoteServices: Policies.MFS`](#pinningremoteservices-policiesmfs) 129 - [`Pinning.RemoteServices: Policies.MFS.Enabled`](#pinningremoteservices-policiesmfsenabled) 130 - [`Pinning.RemoteServices: Policies.MFS.PinName`](#pinningremoteservices-policiesmfspinname) 131 - [`Pinning.RemoteServices: Policies.MFS.RepinInterval`](#pinningremoteservices-policiesmfsrepininterval) 132 - [`Provide`](#provide) 133 - [`Provide.Enabled`](#provideenabled) 134 - [`Provide.Strategy`](#providestrategy) 135 - [`Provide.DHT`](#providedht) 136 - [`Provide.DHT.MaxWorkers`](#providedhtmaxworkers) 137 - [`Provide.DHT.Interval`](#providedhtinterval) 138 - [`Provide.DHT.SweepEnabled`](#providedhtsweepenabled) 139 - [`Provide.DHT.ResumeEnabled`](#providedhtresumeenabled) 140 - [`Provide.DHT.DedicatedPeriodicWorkers`](#providedhtdedicatedperiodicworkers) 141 - [`Provide.DHT.DedicatedBurstWorkers`](#providedhtdedicatedburstworkers) 142 - [`Provide.DHT.MaxProvideConnsPerWorker`](#providedhtmaxprovideconnsperworker) 143 - [`Provide.DHT.KeystoreBatchSize`](#providedhtkeystorebatchsize) 144 - [`Provide.DHT.OfflineDelay`](#providedhtofflinedelay) 145 - [`Provider`](#provider) 146 - [`Provider.Enabled`](#providerenabled) 147 - [`Provider.Strategy`](#providerstrategy) 148 - [`Provider.WorkerCount`](#providerworkercount) 149 - [`Pubsub`](#pubsub) 150 - [When to use a dedicated pubsub node](#when-to-use-a-dedicated-pubsub-node) 151 - [Message deduplication](#message-deduplication) 152 - [`Pubsub.Enabled`](#pubsubenabled) 153 - [`Pubsub.Router`](#pubsubrouter) 154 - [`Pubsub.DisableSigning`](#pubsubdisablesigning) 155 - [`Pubsub.SeenMessagesTTL`](#pubsubseenmessagesttl) 156 - [`Pubsub.SeenMessagesStrategy`](#pubsubseenmessagesstrategy) 157 - [`Peering`](#peering) 158 - [`Peering.Peers`](#peeringpeers) 159 - [`Reprovider`](#reprovider) 160 - [`Reprovider.Interval`](#reproviderinterval) 161 - [`Reprovider.Strategy`](#providestrategy) 162 - [`Routing`](#routing) 163 - [`Routing.Type`](#routingtype) 164 - [`Routing.DelegatedRouters`](#routingdelegatedrouters) 165 - [`Routing.AcceleratedDHTClient`](#routingaccelerateddhtclient) 166 - [`Routing.LoopbackAddressesOnLanDHT`](#routingloopbackaddressesonlandht) 167 - [`Routing.IgnoreProviders`](#routingignoreproviders) 168 - [`Routing.Routers`](#routingrouters) 169 - [`Routing.Routers.[name].Type`](#routingroutersnametype) 170 - [`Routing.Routers.[name].Parameters`](#routingroutersnameparameters) 171 - [`Routing.Methods`](#routingmethods) 172 - [`Swarm`](#swarm) 173 - [`Swarm.AddrFilters`](#swarmaddrfilters) 174 - [`Swarm.DisableBandwidthMetrics`](#swarmdisablebandwidthmetrics) 175 - [`Swarm.DisableNatPortMap`](#swarmdisablenatportmap) 176 - [`Swarm.EnableHolePunching`](#swarmenableholepunching) 177 - [`Swarm.EnableAutoRelay`](#swarmenableautorelay) 178 - [`Swarm.RelayClient`](#swarmrelayclient) 179 - [`Swarm.RelayClient.Enabled`](#swarmrelayclientenabled) 180 - [`Swarm.RelayClient.StaticRelays`](#swarmrelayclientstaticrelays) 181 - [`Swarm.RelayService`](#swarmrelayservice) 182 - [`Swarm.RelayService.Enabled`](#swarmrelayserviceenabled) 183 - [`Swarm.RelayService.Limit`](#swarmrelayservicelimit) 184 - [`Swarm.RelayService.ConnectionDurationLimit`](#swarmrelayserviceconnectiondurationlimit) 185 - [`Swarm.RelayService.ConnectionDataLimit`](#swarmrelayserviceconnectiondatalimit) 186 - [`Swarm.RelayService.ReservationTTL`](#swarmrelayservicereservationttl) 187 - [`Swarm.RelayService.MaxReservations`](#swarmrelayservicemaxreservations) 188 - [`Swarm.RelayService.MaxCircuits`](#swarmrelayservicemaxcircuits) 189 - [`Swarm.RelayService.BufferSize`](#swarmrelayservicebuffersize) 190 - [`Swarm.RelayService.MaxReservationsPerPeer`](#swarmrelayservicemaxreservationsperpeer) 191 - [`Swarm.RelayService.MaxReservationsPerIP`](#swarmrelayservicemaxreservationsperip) 192 - [`Swarm.RelayService.MaxReservationsPerASN`](#swarmrelayservicemaxreservationsperasn) 193 - [`Swarm.EnableRelayHop`](#swarmenablerelayhop) 194 - [`Swarm.DisableRelay`](#swarmdisablerelay) 195 - [`Swarm.EnableAutoNATService`](#swarmenableautonatservice) 196 - [`Swarm.ConnMgr`](#swarmconnmgr) 197 - [`Swarm.ConnMgr.Type`](#swarmconnmgrtype) 198 - [Basic Connection Manager](#basic-connection-manager) 199 - [`Swarm.ConnMgr.LowWater`](#swarmconnmgrlowwater) 200 - [`Swarm.ConnMgr.HighWater`](#swarmconnmgrhighwater) 201 - [`Swarm.ConnMgr.GracePeriod`](#swarmconnmgrgraceperiod) 202 - [`Swarm.ConnMgr.SilencePeriod`](#swarmconnmgrsilenceperiod) 203 - [`Swarm.ResourceMgr`](#swarmresourcemgr) 204 - [`Swarm.ResourceMgr.Enabled`](#swarmresourcemgrenabled) 205 - [`Swarm.ResourceMgr.MaxMemory`](#swarmresourcemgrmaxmemory) 206 - [`Swarm.ResourceMgr.MaxFileDescriptors`](#swarmresourcemgrmaxfiledescriptors) 207 - [`Swarm.ResourceMgr.Allowlist`](#swarmresourcemgrallowlist) 208 - [`Swarm.Transports`](#swarmtransports) 209 - [`Swarm.Transports.Network`](#swarmtransportsnetwork) 210 - [`Swarm.Transports.Network.TCP`](#swarmtransportsnetworktcp) 211 - [`Swarm.Transports.Network.Websocket`](#swarmtransportsnetworkwebsocket) 212 - [`Swarm.Transports.Network.QUIC`](#swarmtransportsnetworkquic) 213 - [`Swarm.Transports.Network.Relay`](#swarmtransportsnetworkrelay) 214 - [`Swarm.Transports.Network.WebTransport`](#swarmtransportsnetworkwebtransport) 215 - [`Swarm.Transports.Network.WebRTCDirect`](#swarmtransportsnetworkwebrtcdirect) 216 - [`Swarm.Transports.Security`](#swarmtransportssecurity) 217 - [`Swarm.Transports.Security.TLS`](#swarmtransportssecuritytls) 218 - [`Swarm.Transports.Security.SECIO`](#swarmtransportssecuritysecio) 219 - [`Swarm.Transports.Security.Noise`](#swarmtransportssecuritynoise) 220 - [`Swarm.Transports.Multiplexers`](#swarmtransportsmultiplexers) 221 - [`Swarm.Transports.Multiplexers.Yamux`](#swarmtransportsmultiplexersyamux) 222 - [`Swarm.Transports.Multiplexers.Mplex`](#swarmtransportsmultiplexersmplex) 223 - [`DNS`](#dns) 224 - [`DNS.Resolvers`](#dnsresolvers) 225 - [`DNS.MaxCacheTTL`](#dnsmaxcachettl) 226 - [`HTTPRetrieval`](#httpretrieval) 227 - [`HTTPRetrieval.Enabled`](#httpretrievalenabled) 228 - [`HTTPRetrieval.Allowlist`](#httpretrievalallowlist) 229 - [`HTTPRetrieval.Denylist`](#httpretrievaldenylist) 230 - [`HTTPRetrieval.NumWorkers`](#httpretrievalnumworkers) 231 - [`HTTPRetrieval.MaxBlockSize`](#httpretrievalmaxblocksize) 232 - [`HTTPRetrieval.TLSInsecureSkipVerify`](#httpretrievaltlsinsecureskipverify) 233 - [`Import`](#import) 234 - [`Import.CidVersion`](#importcidversion) 235 - [`Import.UnixFSRawLeaves`](#importunixfsrawleaves) 236 - [`Import.UnixFSChunker`](#importunixfschunker) 237 - [`Import.HashFunction`](#importhashfunction) 238 - [`Import.FastProvideRoot`](#importfastprovideroot) 239 - [`Import.FastProvideWait`](#importfastprovidewait) 240 - [`Import.BatchMaxNodes`](#importbatchmaxnodes) 241 - [`Import.BatchMaxSize`](#importbatchmaxsize) 242 - [`Import.UnixFSFileMaxLinks`](#importunixfsfilemaxlinks) 243 - [`Import.UnixFSDirectoryMaxLinks`](#importunixfsdirectorymaxlinks) 244 - [`Import.UnixFSHAMTDirectoryMaxFanout`](#importunixfshamtdirectorymaxfanout) 245 - [`Import.UnixFSHAMTDirectorySizeThreshold`](#importunixfshamtdirectorysizethreshold) 246 - [`Import.UnixFSHAMTDirectorySizeEstimation`](#importunixfshamtdirectorysizeestimation) 247 - [`Import.UnixFSDAGLayout`](#importunixfsdaglayout) 248 - [`Version`](#version) 249 - [`Version.AgentSuffix`](#versionagentsuffix) 250 - [`Version.SwarmCheckEnabled`](#versionswarmcheckenabled) 251 - [`Version.SwarmCheckPercentThreshold`](#versionswarmcheckpercentthreshold) 252 - [Profiles](#profiles) 253 - [`server` profile](#server-profile) 254 - [`randomports` profile](#randomports-profile) 255 - [`default-datastore` profile](#default-datastore-profile) 256 - [`local-discovery` profile](#local-discovery-profile) 257 - [`default-networking` profile](#default-networking-profile) 258 - [`autoconf-on` profile](#autoconf-on-profile) 259 - [`autoconf-off` profile](#autoconf-off-profile) 260 - [`flatfs` profile](#flatfs-profile) 261 - [`flatfs-measure` profile](#flatfs-measure-profile) 262 - [`pebbleds` profile](#pebbleds-profile) 263 - [`pebbleds-measure` profile](#pebbleds-measure-profile) 264 - [`badgerds` profile](#badgerds-profile) 265 - [`badgerds-measure` profile](#badgerds-measure-profile) 266 - [`lowpower` profile](#lowpower-profile) 267 - [`announce-off` profile](#announce-off-profile) 268 - [`announce-on` profile](#announce-on-profile) 269 - [`unixfs-v0-2015` profile](#unixfs-v0-2015-profile) 270 - [`legacy-cid-v0` profile](#legacy-cid-v0-profile) 271 - [`unixfs-v1-2025` profile](#unixfs-v1-2025-profile) 272 - [Security](#security) 273 - [Port and Network Exposure](#port-and-network-exposure) 274 - [Security Best Practices](#security-best-practices) 275 - [Types](#types) 276 - [`flag`](#flag) 277 - [`priority`](#priority) 278 - [`strings`](#strings) 279 - [`duration`](#duration) 280 - [`optionalInteger`](#optionalinteger) 281 - [`optionalBytes`](#optionalbytes) 282 - [`optionalString`](#optionalstring) 283 - [`optionalDuration`](#optionalduration) 284 285 ## `Addresses` 286 287 Contains information about various listener addresses to be used by this node. 288 289 ### `Addresses.API` 290 291 [Multiaddr][multiaddr] or array of multiaddrs describing the addresses to serve 292 the local [Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) (`/api/v0`). 293 294 Supported Transports: 295 296 - tcp/ip{4,6} - `/ipN/.../tcp/...` 297 - unix - `/unix/path/to/socket` 298 299 > [!CAUTION] 300 > **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET** 301 > 302 > The RPC API grants admin-level access to your Kubo IPFS node, including 303 > configuration and secret key management. 304 > 305 > By default, it is bound to localhost for security reasons. Exposing it to LAN 306 > or the public internet is highly risky—similar to exposing a SQL database or 307 > backend service without authentication middleware 308 > 309 > - If you need secure access to a subset of RPC, secure it with [`API.Authorizations`](#apiauthorizations) or custom auth middleware running in front of the localhost-only RPC port defined here. 310 > - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead. 311 > - See [Security section](#security) for network exposure considerations. 312 313 Default: `/ip4/127.0.0.1/tcp/5001` 314 315 Type: `strings` ([multiaddrs][multiaddr]) 316 317 ### `Addresses.Gateway` 318 319 [Multiaddr][multiaddr] or array of multiaddrs describing the address to serve 320 the local [HTTP gateway](https://specs.ipfs.tech/http-gateways/) (`/ipfs`, `/ipns`) on. 321 322 Supported Transports: 323 324 - tcp/ip{4,6} - `/ipN/.../tcp/...` 325 - unix - `/unix/path/to/socket` 326 327 > [!CAUTION] 328 > **SECURITY CONSIDERATIONS FOR GATEWAY EXPOSURE** 329 > 330 > By default, the gateway is bound to localhost for security. If you bind to `0.0.0.0` 331 > or a public IP, anyone with access can trigger retrieval of arbitrary CIDs, causing 332 > bandwidth usage and potential exposure to malicious content. Limit with 333 > [`Gateway.NoFetch`](#gatewaynofetch). Consider firewall rules, authentication, 334 > and [`Gateway.PublicGateways`](#gatewaypublicgateways) for public exposure. 335 > See [Security section](#security) for network exposure considerations. 336 337 Default: `/ip4/127.0.0.1/tcp/8080` 338 339 Type: `strings` ([multiaddrs][multiaddr]) 340 341 ### `Addresses.Swarm` 342 343 An array of [multiaddrs][multiaddr] describing which addresses to listen on for p2p swarm 344 connections. 345 346 Supported Transports: 347 348 - tcp/ip{4,6} - `/ipN/.../tcp/...` 349 - websocket - `/ipN/.../tcp/.../ws` 350 - quicv1 (RFC9000) - `/ipN/.../udp/.../quic-v1` - can share the same two tuple with `/quic-v1/webtransport` 351 - webtransport `/ipN/.../udp/.../quic-v1/webtransport` - can share the same two tuple with `/quic-v1` 352 353 > [!IMPORTANT] 354 > Make sure your firewall rules allow incoming connections on both TCP and UDP ports defined here. 355 > See [Security section](#security) for network exposure considerations. 356 357 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). 358 359 Default: 360 361 ```json 362 [ 363 "/ip4/0.0.0.0/tcp/4001", 364 "/ip6/::/tcp/4001", 365 "/ip4/0.0.0.0/udp/4001/quic-v1", 366 "/ip4/0.0.0.0/udp/4001/quic-v1/webtransport", 367 "/ip6/::/udp/4001/quic-v1", 368 "/ip6/::/udp/4001/quic-v1/webtransport" 369 ] 370 ``` 371 372 Type: `array[string]` ([multiaddrs][multiaddr]) 373 374 ### `Addresses.Announce` 375 376 If non-empty, this array specifies the swarm addresses to announce to the 377 network. If empty, the daemon will announce inferred swarm addresses. 378 379 Default: `[]` 380 381 Type: `array[string]` ([multiaddrs][multiaddr]) 382 383 ### `Addresses.AppendAnnounce` 384 385 Similar to [`Addresses.Announce`](#addressesannounce) except this doesn't 386 override inferred swarm addresses if non-empty. 387 388 Default: `[]` 389 390 Type: `array[string]` ([multiaddrs][multiaddr]) 391 392 ### `Addresses.NoAnnounce` 393 394 An array of swarm addresses not to announce to the network. 395 Takes precedence over `Addresses.Announce` and `Addresses.AppendAnnounce`. 396 397 > [!TIP] 398 > The [`server` configuration profile](#server-profile) fills up this list with sensible defaults, 399 > preventing announcement of non-routable IP addresses (e.g., `/ip4/192.168.0.0/ipcidr/16`, 400 > which is the [multiaddress][multiaddr] representation of `192.168.0.0/16`) but you should always 401 > check settings against your own network and/or hosting provider. 402 403 Default: `[]` 404 405 Type: `array[string]` ([multiaddrs][multiaddr]) 406 407 ## `API` 408 409 Contains information used by the [Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/). 410 411 ### `API.HTTPHeaders` 412 413 Map of HTTP headers to set on responses from the RPC (`/api/v0`) HTTP server. 414 415 Example: 416 417 ```json 418 { 419 "Foo": ["bar"] 420 } 421 ``` 422 423 Default: `null` 424 425 Type: `object[string -> array[string]]` (header names -> array of header values) 426 427 ### `API.Authorizations` 428 429 The `API.Authorizations` field defines user-based access restrictions for the 430 [Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/), which is located at 431 `Addresses.API` under `/api/v0` paths. 432 433 By default, the admin-level RPC API is accessible without restrictions as it is only 434 exposed on `127.0.0.1` and safeguarded with Origin check and implicit 435 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers that 436 block random websites from accessing the RPC. 437 438 When entries are defined in `API.Authorizations`, RPC requests will be declined 439 unless a corresponding secret is present in the HTTP [`Authorization` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization), 440 and the requested path is included in the `AllowedPaths` list for that specific 441 secret. 442 443 > [!CAUTION] 444 > **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET** 445 > 446 > The RPC API is vast. It grants admin-level access to your Kubo IPFS node, including 447 > configuration and secret key management. 448 > 449 > - If you need secure access to a subset of RPC, make sure you understand the risk, block everything by default and allow basic auth access with [`API.Authorizations`](#apiauthorizations) or custom auth middleware running in front of the localhost-only port defined in [`Addresses.API`](#addressesapi). 450 > - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead. 451 452 Default: `null` 453 454 Type: `object[string -> object]` (user name -> authorization object, see below) 455 456 For example, to limit RPC access to Alice (access `id` and MFS `files` commands with HTTP Basic Auth) 457 and Bob (full access with Bearer token): 458 459 ```json 460 { 461 "API": { 462 "Authorizations": { 463 "Alice": { 464 "AuthSecret": "basic:alice:password123", 465 "AllowedPaths": ["/api/v0/id", "/api/v0/files"] 466 }, 467 "Bob": { 468 "AuthSecret": "bearer:secret-token123", 469 "AllowedPaths": ["/api/v0"] 470 } 471 } 472 } 473 } 474 475 ``` 476 477 #### `API.Authorizations: AuthSecret` 478 479 The `AuthSecret` field denotes the secret used by a user to authenticate, 480 usually via HTTP [`Authorization` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). 481 482 Field format is `type:value`, and the following types are supported: 483 484 - `bearer:` For secret Bearer tokens, set as `bearer:token`. 485 - If no known `type:` prefix is present, `bearer:` is assumed. 486 - `basic`: For HTTP Basic Auth introduced in [RFC7617](https://datatracker.ietf.org/doc/html/rfc7617). Value can be: 487 - `basic:user:pass` 488 - `basic:base64EncodedBasicAuth` 489 490 One can use the config value for authentication via the command line: 491 492 ``` 493 ipfs id --api-auth basic:user:pass 494 ``` 495 496 Type: `string` 497 498 #### `API.Authorizations: AllowedPaths` 499 500 The `AllowedPaths` field is an array of strings containing allowed RPC path 501 prefixes. Users authorized with the related `AuthSecret` will only be able to 502 access paths prefixed by the specified prefixes. 503 504 For instance: 505 506 - If set to `["/api/v0"]`, the user will have access to the complete RPC API. 507 - If set to `["/api/v0/id", "/api/v0/files"]`, the user will only have access 508 to the `id` command and all MFS commands under `files`. 509 510 Note that `/api/v0/version` is always permitted access to allow version check 511 to ensure compatibility. 512 513 Default: `[]` 514 515 Type: `array[string]` 516 517 ## `AutoNAT` 518 519 Contains the configuration options for the libp2p's [AutoNAT](https://github.com/libp2p/specs/tree/master/autonat) service. The AutoNAT service 520 helps other nodes on the network determine if they're publicly reachable from 521 the rest of the internet. 522 523 ### `AutoNAT.ServiceMode` 524 525 When unset (default), the AutoNAT service defaults to _enabled_. Otherwise, this 526 field can take one of two values: 527 528 - `enabled` - Enable the V1+V2 service (unless the node determines that it, 529 itself, isn't reachable by the public internet). 530 - `legacy-v1` - **DEPRECATED** Same as `enabled` but only V1 service is enabled. Used for testing 531 during as few releases as we [transition to V2](https://github.com/ipfs/kubo/issues/10091), will be removed in the future. 532 - `disabled` - Disable the service. 533 534 Additional modes may be added in the future. 535 536 > [!IMPORTANT] 537 > We are in the progress of [rolling out AutoNAT V2](https://github.com/ipfs/kubo/issues/10091). 538 > Right now, by default, a publicly dialable Kubo provides both V1 and V2 service to other peers, 539 > and V1 is still used by Kubo for Autorelay feature. In a future release we will remove V1 and switch all features to use V2. 540 541 Default: `enabled` 542 543 Type: `optionalString` 544 545 ### `AutoNAT.Throttle` 546 547 When set, this option configures the AutoNAT services throttling behavior. By 548 default, Kubo will rate-limit the number of NAT checks performed for other 549 nodes to 30 per minute, and 3 per peer. 550 551 ### `AutoNAT.Throttle.GlobalLimit` 552 553 Configures how many AutoNAT requests to service per `AutoNAT.Throttle.Interval`. 554 555 Default: 30 556 557 Type: `integer` (non-negative, `0` means unlimited) 558 559 ### `AutoNAT.Throttle.PeerLimit` 560 561 Configures how many AutoNAT requests per-peer to service per `AutoNAT.Throttle.Interval`. 562 563 Default: 3 564 565 Type: `integer` (non-negative, `0` means unlimited) 566 567 ### `AutoNAT.Throttle.Interval` 568 569 Configures the interval for the above limits. 570 571 Default: 1 Minute 572 573 Type: `duration` (when `0`/unset, the default value is used) 574 575 ## `AutoConf` 576 577 The AutoConf feature enables Kubo nodes to automatically fetch and apply network configuration from a remote JSON endpoint. This system allows dynamic configuration updates for bootstrap peers, DNS resolvers, delegated routing, and IPNS publishing endpoints without requiring manual updates to each node's local config. 578 579 AutoConf works by using special `"auto"` placeholder values in configuration fields. When Kubo encounters these placeholders, it fetches the latest configuration from the specified URL and resolves the placeholders with the appropriate values at runtime. The original configuration file remains unchanged - `"auto"` values are preserved in the JSON and only resolved in memory during node operation. 580 581 ### Key Features 582 583 - **Remote Configuration**: Fetch network defaults from a trusted URL 584 - **Automatic Updates**: Periodic background checks for configuration updates 585 - **Graceful Fallback**: Uses hardcoded IPFS Mainnet bootstrappers when remote config is unavailable 586 - **Validation**: Ensures all fetched configuration values are valid multiaddrs and URLs 587 - **Caching**: Stores multiple versions locally with ETags for efficient updates 588 - **User Notification**: Logs ERROR when new configuration is available requiring node restart 589 - **Debug Logging**: AutoConf operations can be inspected by setting `GOLOG_LOG_LEVEL="error,autoconf=debug"` 590 591 ### Supported Fields 592 593 AutoConf can resolve `"auto"` placeholders in the following configuration fields: 594 595 - `Bootstrap` - Bootstrap peer addresses 596 - `DNS.Resolvers` - DNS-over-HTTPS resolver endpoints 597 - `Routing.DelegatedRouters` - Delegated routing HTTP API endpoints 598 - `Ipns.DelegatedPublishers` - IPNS delegated publishing HTTP API endpoints 599 600 ### Usage Example 601 602 ```json 603 { 604 "AutoConf": { 605 "URL": "https://example.com/autoconf.json", 606 "Enabled": true, 607 "RefreshInterval": "24h" 608 }, 609 "Bootstrap": ["auto"], 610 "DNS": { 611 "Resolvers": { 612 ".": ["auto"], 613 "eth.": ["auto"], 614 "custom.": ["https://dns.example.com/dns-query"] 615 } 616 }, 617 "Routing": { 618 "DelegatedRouters": ["auto", "https://router.example.org/routing/v1"] 619 } 620 } 621 ``` 622 623 **Notes:** 624 625 - Configuration fetching happens at daemon startup and periodically in the background 626 - When new configuration is detected, users must restart their node to apply changes 627 - Mixed configurations are supported: you can use both `"auto"` and static values 628 - If AutoConf is disabled but `"auto"` values exist, daemon startup will fail with validation errors 629 - Cache is stored in `$IPFS_PATH/autoconf/` with up to 3 versions retained 630 631 ### Path-Based Routing Configuration 632 633 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: 634 635 **Supported paths:** 636 637 - `/routing/v1/providers` - Enables provider record lookups only 638 - `/routing/v1/peers` - Enables peer routing lookups only 639 - `/routing/v1/ipns` - Enables IPNS record operations only 640 - No path - Enables all routing operations (backward compatibility) 641 642 **AutoConf JSON structure with path-based routing:** 643 644 ```json 645 { 646 "DelegatedRouters": { 647 "mainnet-for-nodes-with-dht": [ 648 "https://cid.contact/routing/v1/providers" 649 ], 650 "mainnet-for-nodes-without-dht": [ 651 "https://delegated-ipfs.dev/routing/v1/providers", 652 "https://delegated-ipfs.dev/routing/v1/peers", 653 "https://delegated-ipfs.dev/routing/v1/ipns" 654 ] 655 }, 656 "DelegatedPublishers": { 657 "mainnet-for-ipns-publishers-with-http": [ 658 "https://delegated-ipfs.dev/routing/v1/ipns" 659 ] 660 } 661 } 662 ``` 663 664 **Node type categories:** 665 666 - `mainnet-for-nodes-with-dht`: Mainnet nodes with DHT enabled (typically only need additional provider lookups) 667 - `mainnet-for-nodes-without-dht`: Mainnet nodes without DHT (need comprehensive routing services) 668 - `mainnet-for-ipns-publishers-with-http`: Mainnet nodes that publish IPNS records via HTTP 669 670 This design enables efficient, selective routing where each endpoint URL automatically determines its capabilities based on the path, while maintaining semantic grouping by node configuration type. 671 672 Default: `{}` 673 674 Type: `object` 675 676 ### `AutoConf.Enabled` 677 678 Controls whether the AutoConf system is active. When enabled, Kubo will fetch configuration from the specified URL and resolve `"auto"` placeholders at runtime. When disabled, any `"auto"` values in the configuration will cause daemon startup to fail with validation errors. 679 680 This provides a safety mechanism to ensure nodes don't start with unresolved placeholders when AutoConf is intentionally disabled. 681 682 Default: `true` 683 684 Type: `flag` 685 686 ### `AutoConf.URL` 687 688 Specifies the HTTP(S) URL from which to fetch the autoconf JSON. The endpoint should return a JSON document containing Bootstrap peers, DNS resolvers, delegated routing endpoints, and IPNS publishing endpoints that will replace `"auto"` placeholders in the local configuration. 689 690 The URL must serve a JSON document matching the AutoConf schema. Kubo validates all multiaddr and URL values before caching to ensure they are properly formatted. 691 692 When not specified in the configuration, the default mainnet URL is used automatically. 693 694 <a href="https://ipshipyard.com/"><img align="right" src="https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272" /></a> 695 696 > [!NOTE] 697 > Public good autoconf manifest at `conf.ipfs-mainnet.org` is provided by the team at [Shipyard](https://ipshipyard.com). 698 699 Default: `"https://conf.ipfs-mainnet.org/autoconf.json"` (when not specified) 700 701 Type: `optionalString` 702 703 ### `AutoConf.RefreshInterval` 704 705 Specifies how frequently Kubo should refresh autoconf data. This controls both how often cached autoconf data is considered fresh and how frequently the background service checks for new configuration updates. 706 707 When a new configuration version is detected during background updates, Kubo logs an ERROR message informing the user that a node restart is required to apply the changes to any `"auto"` entries in their configuration. 708 709 Default: `24h` 710 711 Type: `optionalDuration` 712 713 ### `AutoConf.TLSInsecureSkipVerify` 714 715 **FOR TESTING ONLY** - Allows skipping TLS certificate verification when fetching autoconf from HTTPS URLs. This should never be enabled in production as it makes the configuration fetching vulnerable to man-in-the-middle attacks. 716 717 Default: `false` 718 719 Type: `flag` 720 721 ## `AutoTLS` 722 723 The [AutoTLS](https://web.archive.org/web/20260112031855/https://blog.libp2p.io/autotls/) feature enables publicly reachable Kubo nodes (those dialable from the public 724 internet) to automatically obtain a wildcard TLS certificate for a DNS name 725 unique to their PeerID at `*.[PeerID].libp2p.direct`. This enables direct 726 libp2p connections and retrieval of IPFS content from browsers [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) 727 using transports such as [Secure WebSockets](https://github.com/libp2p/specs/blob/master/websockets/README.md), 728 without requiring user to do any manual domain registration and certificate configuration. 729 730 Under the hood, [p2p-forge] client uses public utility service at `libp2p.direct` as an [ACME DNS-01 Challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) 731 broker enabling peer to obtain a wildcard TLS certificate tied to public key of their [PeerID](https://web.archive.org/web/20251112181025/https://docs.libp2p.io/concepts/fundamentals/peers/#peer-id). 732 733 By default, the certificates are requested from Let's Encrypt. Origin and rationale for this project can be found in [community.letsencrypt.org discussion](https://community.letsencrypt.org/t/feedback-on-raising-certificates-per-registered-domain-to-enable-peer-to-peer-networking/223003). 734 735 <a href="https://ipshipyard.com/"><img align="right" src="https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272" /></a> 736 737 > [!NOTE] 738 > Public good DNS and [p2p-forge] infrastructure at `libp2p.direct` is run by the team at [Interplanetary Shipyard](https://ipshipyard.com). 739 > 740 [p2p-forge]: https://github.com/ipshipyard/p2p-forge 741 742 Default: `{}` 743 744 Type: `object` 745 746 ### `AutoTLS.Enabled` 747 748 Enables the AutoTLS feature to provide DNS and TLS support for [libp2p Secure WebSocket](https://github.com/libp2p/specs/blob/master/websockets/README.md) over a `/tcp` port, 749 to allow JS clients running in web browser [Secure Context](https://w3c.github.io/webappsec-secure-contexts/) to connect to Kubo directly. 750 751 When activated, together with [`AutoTLS.AutoWSS`](#autotlsautowss) (default) or manually including a `/tcp/{port}/tls/sni/*.libp2p.direct/ws` multiaddr in [`Addresses.Swarm`](#addressesswarm) 752 (with SNI suffix matching [`AutoTLS.DomainSuffix`](#autotlsdomainsuffix)), Kubo retrieves a trusted PKI TLS certificate for `*.{peerid}.libp2p.direct` and configures the `/ws` listener to use it. 753 754 **Note:** 755 756 - This feature requires a publicly reachable node. If behind NAT, manual port forwarding or UPnP (`Swarm.DisableNatPortMap=false`) is required. 757 - The first time AutoTLS is used, it may take 5-15 minutes + [`AutoTLS.RegistrationDelay`](#autotlsregistrationdelay) before `/ws` listener is added. Be patient. 758 - Avoid manual configuration. [`AutoTLS.AutoWSS=true`](#autotlsautowss) should automatically add `/ws` listener to existing, firewall-forwarded `/tcp` ports. 759 - To troubleshoot, use `GOLOG_LOG_LEVEL="error,autotls=debug` for detailed logs, or `GOLOG_LOG_LEVEL="error,autotls=info` for quieter output. 760 - Certificates are stored in `$IPFS_PATH/p2p-forge-certs`; deleting this directory and restarting the daemon forces a certificate rotation. 761 - For now, the TLS cert applies solely to `/ws` libp2p WebSocket connections, not HTTP [`Gateway`](#gateway), which still need separate reverse proxy TLS setup with a custom domain. 762 763 Default: `true` 764 765 Type: `flag` 766 767 ### `AutoTLS.AutoWSS` 768 769 Optional. Controls if Kubo should add `/tls/sni/*.libp2p.direct/ws` listener to every pre-existing `/tcp` port IFF no explicit `/ws` is defined in [`Addresses.Swarm`](#addressesswarm) already. 770 771 Default: `true` (if `AutoTLS.Enabled`) 772 773 Type: `flag` 774 775 ### `AutoTLS.ShortAddrs` 776 777 Optional. Controls if final AutoTLS listeners are announced under shorter `/dnsX/A.B.C.D.peerid.libp2p.direct/tcp/4001/tls/ws` addresses instead of fully resolved `/ip4/A.B.C.D/tcp/4001/tls/sni/A-B-C-D.peerid.libp2p.direct/tls/ws`. 778 779 The main use for AutoTLS is allowing connectivity from Secure Context in a web browser, and DNS lookup needs to happen there anyway, making `/dnsX` a more compact, more interoperable option without obvious downside. 780 781 Default: `true` 782 783 Type: `flag` 784 785 ### `AutoTLS.SkipDNSLookup` 786 787 Optional. Controls whether to skip network DNS lookups for [p2p-forge] domains like `*.libp2p.direct`. 788 789 This applies to DNS resolution performed via [`DNS.Resolvers`](#dnsresolvers), including `/dns*` multiaddrs resolved by go-libp2p (e.g., peer addresses from DHT or delegated routing). 790 791 When enabled (default), A/AAAA queries for hostnames matching [`AutoTLS.DomainSuffix`](#autotlsdomainsuffix) are resolved locally by parsing the IP address directly from the hostname (e.g., `1-2-3-4.peerID.libp2p.direct` resolves to `1.2.3.4` without network I/O). This avoids unnecessary DNS queries since the IP is already encoded in the hostname. 792 793 If the hostname format is invalid (wrong peerID, malformed IP encoding), the resolver falls back to network DNS, ensuring forward compatibility with potential future DNS record types. 794 795 Set to `false` to always use network DNS for these domains. This is primarily useful for debugging or if you need to override resolution behavior via [`DNS.Resolvers`](#dnsresolvers). 796 797 Default: `true` 798 799 Type: `flag` 800 801 ### `AutoTLS.DomainSuffix` 802 803 Optional override of the parent domain suffix that will be used in DNS+TLS+WebSockets multiaddrs generated by [p2p-forge] client. 804 Do not change this unless you self-host [p2p-forge]. 805 806 Default: `libp2p.direct` (public good run by [Interplanetary Shipyard](https://ipshipyard.com)) 807 808 Type: `optionalString` 809 810 ### `AutoTLS.RegistrationEndpoint` 811 812 Optional override of [p2p-forge] HTTP registration API. 813 Do not change this unless you self-host [p2p-forge] under own domain. 814 815 > [!IMPORTANT] 816 > The default endpoint performs [libp2p Peer ID Authentication over HTTP](https://github.com/libp2p/specs/blob/master/http/peer-id-auth.md) 817 > (proving ownership of PeerID), probes if your Kubo node can correctly answer to a [libp2p Identify](https://github.com/libp2p/specs/tree/master/identify) query. 818 > This ensures only a correctly configured, publicly dialable Kubo can initiate [ACME DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) for `peerid.libp2p.direct`. 819 820 Default: `https://registration.libp2p.direct` (public good run by [Interplanetary Shipyard](https://ipshipyard.com)) 821 822 Type: `optionalString` 823 824 ### `AutoTLS.RegistrationToken` 825 826 Optional value for `Forge-Authorization` token sent with request to `RegistrationEndpoint` 827 (useful for private/self-hosted/test instances of [p2p-forge], unset by default). 828 829 Default: `""` 830 831 Type: `optionalString` 832 833 ### `AutoTLS.RegistrationDelay` 834 835 An additional delay applied before sending a request to the `RegistrationEndpoint`. 836 837 The default delay is bypassed if the user explicitly set `AutoTLS.Enabled=true` in the JSON configuration file. 838 This ensures that ephemeral nodes using the default configuration do not spam the`AutoTLS.CAEndpoint` with unnecessary ACME requests. 839 840 Default: `1h` (or `0` if explicit `AutoTLS.Enabled=true`) 841 842 Type: `optionalDuration` 843 844 ### `AutoTLS.CAEndpoint` 845 846 Optional override of CA ACME API used by [p2p-forge] system. 847 Do not change this unless you self-host [p2p-forge] under own domain. 848 849 > [!IMPORTANT] 850 > CAA DNS record at `libp2p.direct` limits CA choice to Let's Encrypt. If you want to use a different CA, use your own domain. 851 852 Default: [certmagic.LetsEncryptProductionCA](https://pkg.go.dev/github.com/caddyserver/certmagic#pkg-constants) (see [community.letsencrypt.org discussion](https://community.letsencrypt.org/t/feedback-on-raising-certificates-per-registered-domain-to-enable-peer-to-peer-networking/223003)) 853 854 Type: `optionalString` 855 856 ## `Bitswap` 857 858 High level client and server configuration of the [Bitswap Protocol](https://specs.ipfs.tech/bitswap-protocol/) over libp2p. 859 860 For internal configuration see [`Internal.Bitswap`](#internalbitswap). 861 862 For HTTP version see [`HTTPRetrieval`](#httpretrieval). 863 864 ### `Bitswap.Libp2pEnabled` 865 866 Determines whether Kubo will use Bitswap over libp2p. 867 868 Disabling this, will remove `/ipfs/bitswap/*` protocol support from [libp2p identify](https://github.com/libp2p/specs/blob/master/identify/README.md) responses, effectively shutting down both Bitswap libp2p client and server. 869 870 > [!WARNING] 871 > Bitswap over libp2p is a core component of Kubo and the oldest way of exchanging blocks. Disabling it completely may cause unpredictable outcomes, such as retrieval failures, if the only providers were libp2p ones. Treat this as experimental and use it solely for testing purposes with `HTTPRetrieval.Enabled`. 872 873 Default: `true` 874 875 Type: `flag` 876 877 ### `Bitswap.ServerEnabled` 878 879 Determines whether Kubo functions as a Bitswap server to host and respond to block requests. 880 881 Disabling the server retains client and protocol support in [libp2p identify](https://github.com/libp2p/specs/blob/master/identify/README.md) responses but causes Kubo to reply with "don't have" to all block requests. 882 883 Default: `true` (requires `Bitswap.Libp2pEnabled`) 884 885 Type: `flag` 886 887 ## `Bootstrap` 888 889 Bootstrap peers help your node discover and connect to the IPFS network when starting up. This array contains [multiaddrs][multiaddr] of trusted nodes that your node contacts first to find other peers and content. 890 891 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. 892 893 **What this gives you:** 894 895 - **Reliable startup**: Your node can always find the network, even if some bootstrap peers go offline 896 - **Automatic updates**: New bootstrap peers are added as the network evolves 897 - **Custom control**: Add your own trusted peers alongside or instead of the defaults 898 899 Default: `["auto"]` 900 901 Type: `array[string]` ([multiaddrs][multiaddr] or `"auto"`) 902 903 ## `Datastore` 904 905 Contains information related to the construction and operation of the on-disk 906 storage system. 907 908 ### `Datastore.StorageMax` 909 910 A soft upper limit for the size of the ipfs repository's datastore. With `StorageGCWatermark`, 911 is used to calculate whether to trigger a gc run (only if `--enable-gc` flag is set). 912 913 > [!NOTE] 914 > This only controls when automatic GC of raw blocks is triggered. It is not a 915 > hard limit on total disk usage. The metadata stored alongside blocks (pins, 916 > MFS, provider system state, pubsub message ID tracking, and other internal 917 > data) is not counted against this limit. Always include extra headroom to 918 > account for metadata overhead. See [datastores.md](datastores.md) for details 919 > on how different datastore backends handle disk space reclamation. 920 921 Default: `"10GB"` 922 923 Type: `string` (size) 924 925 ### `Datastore.StorageGCWatermark` 926 927 The percentage of the `StorageMax` value at which a garbage collection will be 928 triggered automatically if the daemon was run with automatic gc enabled (that 929 option defaults to false currently). 930 931 Default: `90` 932 933 Type: `integer` (0-100%) 934 935 ### `Datastore.GCPeriod` 936 937 A time duration specifying how frequently to run a garbage collection. Only used 938 if automatic gc is enabled. 939 940 Default: `1h` 941 942 Type: `duration` (an empty string means the default value) 943 944 ### `Datastore.HashOnRead` 945 946 A boolean value. If set to true, all block reads from the disk will be hashed and 947 verified. This will cause increased CPU utilization. 948 949 Default: `false` 950 951 Type: `bool` 952 953 ### `Datastore.BloomFilterSize` 954 955 A number representing the size in bytes of the blockstore's [bloom 956 filter](https://en.wikipedia.org/wiki/Bloom_filter). A value of zero represents 957 the feature is disabled. 958 959 This site generates useful graphs for various bloom filter values: 960 <https://hur.st/bloomfilter/?n=1e6&p=0.01&m=&k=7> You may use it to find a 961 preferred optimal value, where `m` is `BloomFilterSize` in bits. Remember to 962 convert the value `m` from bits, into bytes for use as `BloomFilterSize` in the 963 config file. For example, for 1,000,000 blocks, expecting a 1% false-positive 964 rate, you'd end up with a filter size of 9592955 bits, so for `BloomFilterSize` 965 we'd want to use 1199120 bytes. As of writing, [7 hash 966 functions](https://github.com/ipfs/go-ipfs-blockstore/blob/547442836ade055cc114b562a3cc193d4e57c884/caching.go#L22) 967 are used, so the constant `k` is 7 in the formula. 968 969 Enabling the BloomFilter can provide performance improvements specially when 970 responding to many requests for inexistent blocks. It however requires a full 971 sweep of all the datastore keys on daemon start. On very large datastores this 972 can be a very taxing operation, particularly if the datastore does not support 973 querying existing keys without reading their values at the same time (blocks). 974 975 Default: `0` (disabled) 976 977 Type: `integer` (non-negative, bytes) 978 979 ### `Datastore.WriteThrough` 980 981 This option controls whether a block that already exist in the datastore 982 should be written to it. When set to `false`, a `Has()` call is performed 983 against the datastore prior to writing every block. If the block is already 984 stored, the write is skipped. This check happens both on the Blockservice and 985 the Blockstore layers and this setting affects both. 986 987 When set to `true`, no checks are performed and blocks are written to the 988 datastore, which depending on the implementation may perform its own checks. 989 990 This option can affect performance and the strategy should be taken in 991 conjunction with [`BlockKeyCacheSize`](#datastoreblockkeycachesize) and 992 [`BloomFilterSize`](#datastoreboomfiltersize`). 993 994 Default: `true` 995 996 Type: `bool` 997 998 ### `Datastore.BlockKeyCacheSize` 999 1000 A number representing the maximum size in bytes of the blockstore's Two-Queue 1001 cache, which caches block-cids and their block-sizes. Use `0` to disable. 1002 1003 This cache, once primed, can greatly speed up operations like `ipfs repo stat` 1004 as there is no need to read full blocks to know their sizes. Size should be 1005 adjusted depending on the number of CIDs on disk (`NumObjects in`ipfs repo stat`). 1006 1007 Default: `65536` (64KiB) 1008 1009 Type: `optionalInteger` (non-negative, bytes) 1010 1011 ### `Datastore.Spec` 1012 1013 Spec defines the structure of the ipfs datastore. It is a composable structure, 1014 where each datastore is represented by a json object. Datastores can wrap other 1015 datastores to provide extra functionality (eg metrics, logging, or caching). 1016 1017 > [!NOTE] 1018 > For more information on possible values for this configuration option, see [`kubo/docs/datastores.md`](datastores.md) 1019 1020 Default: 1021 1022 ``` 1023 { 1024 "mounts": [ 1025 { 1026 "mountpoint": "/blocks", 1027 "path": "blocks", 1028 "prefix": "flatfs.datastore", 1029 "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2", 1030 "sync": false, 1031 "type": "flatfs" 1032 }, 1033 { 1034 "compression": "none", 1035 "mountpoint": "/", 1036 "path": "datastore", 1037 "prefix": "leveldb.datastore", 1038 "type": "levelds" 1039 } 1040 ], 1041 "type": "mount" 1042 } 1043 ``` 1044 1045 With `flatfs-measure` profile: 1046 1047 ``` 1048 { 1049 "mounts": [ 1050 { 1051 "child": { 1052 "path": "blocks", 1053 "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2", 1054 "sync": true, 1055 "type": "flatfs" 1056 }, 1057 "mountpoint": "/blocks", 1058 "prefix": "flatfs.datastore", 1059 "type": "measure" 1060 }, 1061 { 1062 "child": { 1063 "compression": "none", 1064 "path": "datastore", 1065 "type": "levelds" 1066 }, 1067 "mountpoint": "/", 1068 "prefix": "leveldb.datastore", 1069 "type": "measure" 1070 } 1071 ], 1072 "type": "mount" 1073 } 1074 ``` 1075 1076 Type: `object` 1077 1078 ## `Discovery` 1079 1080 Contains options for configuring IPFS node discovery mechanisms. 1081 1082 ### `Discovery.MDNS` 1083 1084 Options for [ZeroConf](https://github.com/libp2p/zeroconf#readme) Multicast DNS-SD peer discovery. 1085 1086 #### `Discovery.MDNS.Enabled` 1087 1088 A boolean value to activate or deactivate Multicast DNS-SD. 1089 1090 Default: `true` 1091 1092 Type: `bool` 1093 1094 #### `Discovery.MDNS.Interval` 1095 1096 **REMOVED:** this is not configurable anymore 1097 in the [new mDNS implementation](https://github.com/libp2p/zeroconf#readme). 1098 1099 ## `Experimental` 1100 1101 Toggle and configure experimental features of Kubo. Experimental features are listed [here](./experimental-features.md). 1102 1103 ### `Experimental.Libp2pStreamMounting` 1104 1105 Enables the `ipfs p2p` commands for tunneling TCP connections through libp2p 1106 streams, similar to SSH port forwarding. 1107 1108 See [docs/p2p-tunnels.md](p2p-tunnels.md) for usage examples. 1109 1110 Default: `false` 1111 1112 Type: `bool` 1113 1114 ## `Gateway` 1115 1116 Options for the HTTP gateway. 1117 1118 > [!IMPORTANT] 1119 > By default, Kubo's gateway is configured for local use at `127.0.0.1` and `localhost`. 1120 > To run a public gateway, configure your domain names in [`Gateway.PublicGateways`](#gatewaypublicgateways). 1121 > For production deployment considerations (reverse proxy, timeouts, rate limiting, CDN), 1122 > see [Running in Production](gateway.md#running-in-production). 1123 1124 ### `Gateway.NoFetch` 1125 1126 When set to true, the gateway will only serve content already in the local repo 1127 and will not fetch files from the network. 1128 1129 Default: `false` 1130 1131 Type: `bool` 1132 1133 ### `Gateway.NoDNSLink` 1134 1135 A boolean to configure whether DNSLink lookup for value in `Host` HTTP header 1136 should be performed. If DNSLink is present, the content path stored in the DNS TXT 1137 record becomes the `/` and the respective payload is returned to the client. 1138 1139 Default: `false` 1140 1141 Type: `bool` 1142 1143 ### `Gateway.DeserializedResponses` 1144 1145 An optional flag to explicitly configure whether this gateway responds to deserialized 1146 requests, or not. By default, it is enabled. When disabling this option, the gateway 1147 operates as a Trustless Gateway only: <https://specs.ipfs.tech/http-gateways/trustless-gateway/>. 1148 1149 Default: `true` 1150 1151 Type: `flag` 1152 1153 ### `Gateway.AllowCodecConversion` 1154 1155 An optional flag to enable automatic conversion between codecs when the 1156 requested format differs from the block's native codec (e.g., converting 1157 dag-pb or dag-cbor to dag-json). 1158 1159 When disabled (the default), the gateway returns `406 Not Acceptable` for 1160 codec mismatches, following behavior specified in 1161 [IPIP-524](https://specs.ipfs.tech/ipips/ipip-0524/). 1162 1163 Most users should keep this disabled unless legacy 1164 [IPLD Logical Format](https://web.archive.org/web/20260204204727/https://ipld.io/specs/codecs/dag-pb/spec/#logical-format) 1165 support is needed as a stop-gap while switching clients to `?format=raw` 1166 and converting client-side. 1167 1168 Instead of relying on gateway-side conversion, fetch the raw block using 1169 `?format=raw` (`application/vnd.ipld.raw`) and convert client-side. This: 1170 1171 - Allows clients to use any codec without waiting for gateway support 1172 - Enables ecosystem innovation without gateway operator coordination 1173 - Works with libraries like [@helia/verified-fetch](https://www.npmjs.com/package/@helia/verified-fetch) in JavaScript 1174 1175 Default: `false` 1176 1177 Type: `flag` 1178 1179 ### `Gateway.DisableHTMLErrors` 1180 1181 An optional flag to disable the pretty HTML error pages of the gateway. Instead, 1182 a `text/plain` page will be returned with the raw error message from Kubo. 1183 1184 It is useful for whitelabel or middleware deployments that wish to avoid 1185 `text/html` responses with IPFS branding and links on error pages in browsers. 1186 1187 Default: `false` 1188 1189 Type: `flag` 1190 1191 ### `Gateway.ExposeRoutingAPI` 1192 1193 An optional flag to expose Kubo `Routing` system on the gateway port 1194 as an [HTTP `/routing/v1`](https://specs.ipfs.tech/routing/http-routing-v1/) endpoint on `127.0.0.1`. 1195 Use reverse proxy to expose it on a different hostname. 1196 1197 This endpoint can be used by other Kubo instances, as illustrated in 1198 [`delegated_routing_v1_http_proxy_test.go`](https://github.com/ipfs/kubo/blob/master/test/cli/delegated_routing_v1_http_proxy_test.go). 1199 Kubo will filter out routing results which are not actionable, for example, all 1200 graphsync providers will be skipped. If you need a generic pass-through, see 1201 standalone router implementation named [someguy](https://github.com/ipfs/someguy). 1202 1203 Default: `true` 1204 1205 Type: `flag` 1206 1207 ### `Gateway.RetrievalTimeout` 1208 1209 Maximum duration Kubo will wait for content retrieval (new bytes to arrive). 1210 1211 **Timeout behavior:** 1212 1213 - **Time to first byte**: Returns 504 Gateway Timeout if the gateway cannot start writing within this duration (e.g., stuck searching for providers) 1214 - **Time between writes**: After first byte, timeout resets with each write. Response terminates if no new data can be written within this duration 1215 1216 **Truncation handling:** When timeout occurs after HTTP 200 headers are sent (e.g., during CAR streams), the gateway: 1217 1218 - Appends error message to indicate truncation 1219 - Forces TCP reset (RST) to prevent caching incomplete responses 1220 - Records in metrics with original status code and `truncated=true` flag 1221 1222 **Monitoring:** Track `ipfs_http_gw_retrieval_timeouts_total` by status code and truncation status. 1223 1224 **Tuning guidance:** 1225 1226 - Compare timeout rates (`ipfs_http_gw_retrieval_timeouts_total`) with success rates (`ipfs_http_gw_responses_total{status="200"}`) 1227 - High timeout rate: consider increasing timeout or scaling horizontally if hardware is constrained 1228 - Many 504s may indicate routing problems - check requested CIDs and provider availability using <https://check.ipfs.network/> 1229 - `truncated=true` timeouts indicate retrieval stalled mid-file with no new bytes for the timeout duration 1230 1231 A value of 0 disables this timeout. 1232 1233 Default: `30s` 1234 1235 Type: `optionalDuration` 1236 1237 ### `Gateway.MaxRequestDuration` 1238 1239 An absolute deadline for the entire gateway request. Unlike [`RetrievalTimeout`](#gatewayretrievaltimeout) (which resets on each data write and catches stalled transfers), this is a hard limit on the total time a request can take. 1240 1241 Returns 504 Gateway Timeout when exceeded. This protects the gateway from edge cases and slow client attacks. 1242 1243 Default: `1h` 1244 1245 Type: `optionalDuration` 1246 1247 ### `Gateway.MaxRangeRequestFileSize` 1248 1249 Maximum file size for HTTP range requests on deserialized responses. Range requests for files larger than this limit return 501 Not Implemented. 1250 1251 **Why this exists:** 1252 1253 Some CDNs like Cloudflare intercept HTTP range requests and convert them to full file downloads when files exceed their cache bucket limits. Cloudflare's default plan only caches range requests for files up to 5GiB. Files larger than this receive HTTP 200 with the entire file instead of HTTP 206 with the requested byte range. A client requesting 1MB from a 40GiB file would unknowingly download all 40GiB, causing bandwidth overcharges for the gateway operator, unexpected data costs for the client, and potential browser crashes. 1254 1255 This only affects deserialized responses. Clients fetching verifiable blocks as `application/vnd.ipld.raw` are not impacted because they work with small chunks that stay well below CDN cache limits. 1256 1257 **How to use:** 1258 1259 Set this to your CDN's range request cache limit (e.g., `"5GiB"` for Cloudflare's default plan). The gateway returns 501 Not Implemented for range requests over files larger than this limit, with an error message suggesting verifiable block requests as an alternative. 1260 1261 > [!NOTE] 1262 > Cloudflare users running open gateway hosting deserialized responses should deploy additional protection via Cloudflare Snippets (requires Enterprise plan). The Kubo configuration alone is not sufficient because Cloudflare has already intercepted and cached the response by the time it reaches your origin. See [boxo#856](https://github.com/ipfs/boxo/issues/856#issuecomment-3523944976) for a snippet that aborts HTTP 200 responses when Content-Length exceeds the limit. 1263 1264 Default: `0` (no limit) 1265 1266 Type: [`optionalBytes`](#optionalbytes) 1267 1268 ### `Gateway.MaxConcurrentRequests` 1269 1270 Limits concurrent HTTP requests. Requests beyond limit receive 429 Too Many Requests. 1271 1272 Protects nodes from traffic spikes and resource exhaustion, especially behind reverse proxies without rate-limiting. Default (4096) aligns with common reverse proxy configurations (e.g., nginx: 8 workers × 1024 connections). 1273 1274 **Monitoring:** `ipfs_http_gw_concurrent_requests` tracks current requests in flight. 1275 1276 **Tuning guidance:** 1277 1278 - Monitor `ipfs_http_gw_concurrent_requests` gauge for usage patterns 1279 - Track 429s (`ipfs_http_gw_responses_total{status="429"}`) and success rate (`{status="200"}`) 1280 - Near limit with low resource usage → increase value 1281 - Memory pressure or OOMs → decrease value and consider scaling 1282 - Set slightly below reverse proxy limit for graceful degradation 1283 - Start with default, adjust based on observed performance for your hardware 1284 1285 A value of 0 disables the limit. 1286 1287 Default: `4096` 1288 1289 Type: `optionalInteger` 1290 1291 ### `Gateway.HTTPHeaders` 1292 1293 Headers to set on gateway responses. 1294 1295 Default: `{}` + implicit CORS headers from `boxo/gateway#AddAccessControlHeaders` and [ipfs/specs#423](https://github.com/ipfs/specs/issues/423) 1296 1297 Type: `object[string -> array[string]]` 1298 1299 ### `Gateway.RootRedirect` 1300 1301 A URL to redirect requests for `/` to. 1302 1303 Default: `""` 1304 1305 Type: `string` (url) 1306 1307 ### `Gateway.DiagnosticServiceURL` 1308 1309 URL for a service to diagnose CID retrievability issues. When the gateway returns a 504 Gateway Timeout error, an "Inspect retrievability of CID" button will be shown that links to this service with the CID appended as `?cid=<CID-to-diagnose>`. 1310 1311 Set to empty string to disable the button. 1312 1313 Default: `"https://check.ipfs.network"` 1314 1315 Type: `optionalstring` (url) 1316 1317 ### `Gateway.FastDirIndexThreshold` 1318 1319 **REMOVED**: this option is [no longer necessary](https://github.com/ipfs/kubo/pull/9481). Ignored since [Kubo 0.18](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.18.md). 1320 1321 ### `Gateway.Writable` 1322 1323 **REMOVED**: this option no longer available as of [Kubo 0.20](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.20.md). 1324 1325 We are working on developing a modern replacement. To support our efforts, please leave a comment describing your use case in [ipfs/specs#375](https://github.com/ipfs/specs/issues/375). 1326 1327 ### `Gateway.PathPrefixes` 1328 1329 **REMOVED:** see [go-ipfs#7702](https://github.com/ipfs/go-ipfs/issues/7702) 1330 1331 ### `Gateway.PublicGateways` 1332 1333 > [!IMPORTANT] 1334 > This configuration is **NOT** for HTTP Client, it is for HTTP Server – use this ONLY if you want to run your own IPFS gateway. 1335 1336 `PublicGateways` is a configuration map used for dictionary for customizing gateway behavior 1337 on specified hostnames that point at your Kubo instance. 1338 1339 It is useful when you want to run [Path gateway](https://specs.ipfs.tech/http-gateways/path-gateway/) on `example.com/ipfs/cid`, 1340 and [Subdomain gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/) on `cid.ipfs.example.org`, 1341 or limit `verifiable.example.net` to response types defined in [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) specification. 1342 1343 > [!CAUTION] 1344 > Keys (Hostnames) MUST be unique. Do not use the same parent domain for multiple gateway types, it will break origin isolation. 1345 1346 Hostnames can optionally be defined with one or more wildcards. 1347 1348 Examples: 1349 1350 - `*.example.com` will match requests to `http://foo.example.com/ipfs/*` or `http://{cid}.ipfs.bar.example.com/*`. 1351 - `foo-*.example.com` will match requests to `http://foo-bar.example.com/ipfs/*` or `http://{cid}.ipfs.foo-xyz.example.com/*`. 1352 1353 > [!IMPORTANT] 1354 > **Reverse Proxy:** If running behind nginx or another reverse proxy, ensure 1355 > `Host` and `X-Forwarded-*` headers are forwarded correctly. 1356 > See [Reverse Proxy Caveats](gateway.md#reverse-proxy) in gateway documentation. 1357 1358 #### `Gateway.PublicGateways: Paths` 1359 1360 An array of paths that should be exposed on the hostname. 1361 1362 Example: 1363 1364 ```json 1365 { 1366 "Gateway": { 1367 "PublicGateways": { 1368 "example.com": { 1369 "Paths": ["/ipfs"], 1370 } 1371 } 1372 } 1373 } 1374 ``` 1375 1376 Above enables `http://example.com/ipfs/*` but not `http://example.com/ipns/*` 1377 1378 Default: `[]` 1379 1380 Type: `array[string]` 1381 1382 #### `Gateway.PublicGateways: UseSubdomains` 1383 1384 A boolean to configure whether the gateway at the hostname should be 1385 a [Subdomain Gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/) 1386 and provide [Origin isolation](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) 1387 between content roots. 1388 1389 - `true` - enables [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://*.{hostname}/` 1390 - **Requires whitelist:** make sure respective `Paths` are set. 1391 For example, `Paths: ["/ipfs", "/ipns"]` are required for `http://{cid}.ipfs.{hostname}` and `http://{foo}.ipns.{hostname}` to work: 1392 1393 ```json 1394 "Gateway": { 1395 "PublicGateways": { 1396 "dweb.link": { 1397 "UseSubdomains": true, 1398 "Paths": ["/ipfs", "/ipns"] 1399 } 1400 } 1401 } 1402 ``` 1403 1404 - **Backward-compatible:** requests for content paths such as `http://{hostname}/ipfs/{cid}` produce redirect to `http://{cid}.ipfs.{hostname}` 1405 1406 - `false` - enables [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://{hostname}/*` 1407 - Example: 1408 1409 ```json 1410 "Gateway": { 1411 "PublicGateways": { 1412 "ipfs.io": { 1413 "UseSubdomains": false, 1414 "Paths": ["/ipfs", "/ipns"] 1415 } 1416 } 1417 } 1418 ``` 1419 1420 Default: `false` 1421 1422 Type: `bool` 1423 1424 > [!IMPORTANT] 1425 > See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy. 1426 1427 #### `Gateway.PublicGateways: NoDNSLink` 1428 1429 A boolean to configure whether DNSLink for hostname present in `Host` 1430 HTTP header should be resolved. Overrides global setting. 1431 If `Paths` are defined, they take priority over DNSLink. 1432 1433 Default: `false` (DNSLink lookup enabled by default for every defined hostname) 1434 1435 Type: `bool` 1436 1437 > [!IMPORTANT] 1438 > See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy. 1439 1440 #### `Gateway.PublicGateways: InlineDNSLink` 1441 1442 An optional flag to explicitly configure whether subdomain gateway's redirects 1443 (enabled by `UseSubdomains: true`) should always inline a DNSLink name (FQDN) 1444 into a single DNS label ([specification](https://specs.ipfs.tech/http-gateways/subdomain-gateway/#host-request-header)): 1445 1446 ``` 1447 //example.com/ipns/example.net → HTTP 301 → //example-net.ipns.example.com 1448 ``` 1449 1450 DNSLink name inlining allows for HTTPS on public subdomain gateways with single 1451 label wildcard TLS certs (also enabled when passing `X-Forwarded-Proto: https`), 1452 and provides disjoint Origin per root CID when special rules like 1453 <https://publicsuffix.org>, or a custom localhost logic in browsers like Brave 1454 has to be applied. 1455 1456 Default: `false` 1457 1458 Type: `flag` 1459 1460 #### `Gateway.PublicGateways: DeserializedResponses` 1461 1462 An optional flag to explicitly configure whether this gateway responds to deserialized 1463 requests, or not. By default, it is enabled. 1464 1465 When disabled, the gateway operates strictly as a [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/). 1466 1467 > [!TIP] 1468 > Disabling deserialized responses will protect you from acting as a free web hosting, 1469 > while still allowing trustless clients like [@helia/verified-fetch](https://www.npmjs.com/package/@helia/verified-fetch) 1470 > to utilize it for [trustless, verifiable data retrieval](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval). 1471 1472 Default: same as global `Gateway.DeserializedResponses` 1473 1474 Type: `flag` 1475 1476 #### Implicit defaults of `Gateway.PublicGateways` 1477 1478 Default entries for `localhost` hostname and loopback IPs are always present. 1479 If additional config is provided for those hostnames, it will be merged on top of implicit values: 1480 1481 ```json 1482 { 1483 "Gateway": { 1484 "PublicGateways": { 1485 "localhost": { 1486 "Paths": ["/ipfs", "/ipns"], 1487 "UseSubdomains": true 1488 } 1489 } 1490 } 1491 } 1492 ``` 1493 1494 It is also possible to remove a default by setting it to `null`. 1495 1496 For example, to disable subdomain gateway on `localhost` 1497 and make that hostname act the same as `127.0.0.1`: 1498 1499 ```console 1500 ipfs config --json Gateway.PublicGateways '{"localhost": null }' 1501 ``` 1502 1503 ### `Gateway` recipes 1504 1505 Below is a list of the most common gateway setups. 1506 1507 > [!IMPORTANT] 1508 > See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy. 1509 1510 - 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) 1511 1512 ```console 1513 $ ipfs config --json Gateway.PublicGateways '{ 1514 "dweb.link": { 1515 "UseSubdomains": true, 1516 "Paths": ["/ipfs", "/ipns"] 1517 } 1518 }' 1519 ``` 1520 1521 - **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`. 1522 - **Backward-compatible:** this feature enables automatic redirects from content paths to subdomains: 1523 1524 `http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.dweb.link` 1525 1526 - **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";`.: 1527 1528 `http://dweb.link/ipfs/{cid}` → `https://{cid}.ipfs.dweb.link` 1529 1530 `http://dweb.link/ipns/your-dnslink.site.example.com` → `https://your--dnslink-site-example-com.ipfs.dweb.link` 1531 1532 - **X-Forwarded-Host:** we also support `X-Forwarded-Host: example.com` if you want to override subdomain gateway host from the original request: 1533 1534 `http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.example.com` 1535 1536 - Public [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://ipfs.io/ipfs/{cid}` (no Origin separation) 1537 1538 ```console 1539 $ ipfs config --json Gateway.PublicGateways '{ 1540 "ipfs.io": { 1541 "UseSubdomains": false, 1542 "Paths": ["/ipfs", "/ipns"] 1543 } 1544 }' 1545 ``` 1546 1547 - **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`. 1548 1549 - Public [DNSLink](https://dnslink.io/) gateway resolving every hostname passed in `Host` header. 1550 1551 ```console 1552 ipfs config --json Gateway.NoDNSLink false 1553 ``` 1554 1555 - Note that `NoDNSLink: false` is the default (it works out of the box unless set to `true` manually) 1556 1557 - Hardened, site-specific [DNSLink gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#dnslink-gateway). 1558 1559 Disable fetching of remote data (`NoFetch: true`) and resolving DNSLink at unknown hostnames (`NoDNSLink: true`). 1560 Then, enable DNSLink gateway only for the specific hostname (for which data 1561 is already present on the node), without exposing any content-addressing `Paths`: 1562 1563 ```console 1564 $ ipfs config --json Gateway.NoFetch true 1565 $ ipfs config --json Gateway.NoDNSLink true 1566 $ ipfs config --json Gateway.PublicGateways '{ 1567 "en.wikipedia-on-ipfs.org": { 1568 "NoDNSLink": false, 1569 "Paths": [] 1570 } 1571 }' 1572 ``` 1573 1574 ## `Identity` 1575 1576 ### `Identity.PeerID` 1577 1578 The unique PKI identity label for this configs peer. Set on init and never read, 1579 it's merely here for convenience. Ipfs will always generate the peerID from its 1580 keypair at runtime. 1581 1582 Type: `string` (peer ID) 1583 1584 ### `Identity.PrivKey` 1585 1586 The base64 encoded protobuf describing (and containing) the node's private key. 1587 1588 Type: `string` (base64 encoded) 1589 1590 ## `Internal` 1591 1592 This section includes internal knobs for various subsystems to allow advanced users with big or private infrastructures to fine-tune some behaviors without the need to recompile Kubo. 1593 1594 **Be aware that making informed change here requires in-depth knowledge and most users should leave these untouched. All knobs listed here are subject to breaking changes between versions.** 1595 1596 ### `Internal.Bitswap` 1597 1598 `Internal.Bitswap` contains knobs for tuning bitswap resource utilization. 1599 1600 > [!TIP] 1601 > For high level configuration see [`Bitswap`](#bitswap). 1602 1603 The knobs (below) document how their value should related to each other. 1604 Whether their values should be raised or lowered should be determined 1605 based on the metrics `ipfs_bitswap_active_tasks`, `ipfs_bitswap_pending_tasks`, 1606 `ipfs_bitswap_pending_block_tasks` and `ipfs_bitswap_active_block_tasks` 1607 reported by bitswap. 1608 1609 These metrics can be accessed as the Prometheus endpoint at `{Addresses.API}/debug/metrics/prometheus` (default: `http://127.0.0.1:5001/debug/metrics/prometheus`) 1610 1611 The value of `ipfs_bitswap_active_tasks` is capped by `EngineTaskWorkerCount`. 1612 1613 The value of `ipfs_bitswap_pending_tasks` is generally capped by the knobs below, 1614 however its exact maximum value is hard to predict as it depends on task sizes 1615 as well as number of requesting peers. However, as a rule of thumb, 1616 during healthy operation this value should oscillate around a "typical" low value 1617 (without hitting a plateau continuously). 1618 1619 If `ipfs_bitswap_pending_tasks` is growing while `ipfs_bitswap_active_tasks` is at its maximum then 1620 the node has reached its resource limits and new requests are unable to be processed as quickly as they are coming in. 1621 Raising resource limits (using the knobs below) could help, assuming the hardware can support the new limits. 1622 1623 The value of `ipfs_bitswap_active_block_tasks` is capped by `EngineBlockstoreWorkerCount`. 1624 1625 The value of `ipfs_bitswap_pending_block_tasks` is indirectly capped by `ipfs_bitswap_active_tasks`, but can be hard to 1626 predict as it depends on the number of blocks involved in a peer task which can vary. 1627 1628 If the value of `ipfs_bitswap_pending_block_tasks` is observed to grow, 1629 while `ipfs_bitswap_active_block_tasks` is at its maximum, there is indication that the number of 1630 available block tasks is creating a bottleneck (either due to high-latency block operations, 1631 or due to high number of block operations per bitswap peer task). 1632 In such cases, try increasing the `EngineBlockstoreWorkerCount`. 1633 If this adjustment still does not increase the throughput of the node, there might 1634 be hardware limitations like I/O or CPU. 1635 1636 #### `Internal.Bitswap.TaskWorkerCount` 1637 1638 Number of threads (goroutines) sending outgoing messages. 1639 Throttles the number of concurrent send operations. 1640 1641 Type: `optionalInteger` (thread count, `null` means default which is 8) 1642 1643 #### `Internal.Bitswap.EngineBlockstoreWorkerCount` 1644 1645 Number of threads for blockstore operations. 1646 Used to throttle the number of concurrent requests to the block store. 1647 The optimal value can be informed by the metrics `ipfs_bitswap_pending_block_tasks` and `ipfs_bitswap_active_block_tasks`. 1648 This would be a number that depends on your hardware (I/O and CPU). 1649 1650 Type: `optionalInteger` (thread count, `null` means default which is 128) 1651 1652 #### `Internal.Bitswap.EngineTaskWorkerCount` 1653 1654 Number of worker threads used for preparing and packaging responses before they are sent out. 1655 This number should generally be equal to `TaskWorkerCount`. 1656 1657 Type: `optionalInteger` (thread count, `null` means default which is 8) 1658 1659 #### `Internal.Bitswap.MaxOutstandingBytesPerPeer` 1660 1661 Maximum number of bytes (across all tasks) pending to be processed and sent to any individual peer. 1662 This number controls fairness and can vary from 250Kb (very fair) to 10Mb (less fair, with more work 1663 dedicated to peers who ask for more). Values below 250Kb could cause thrashing. 1664 Values above 10Mb open the potential for aggressively-wanting peers to consume all resources and 1665 deteriorate the quality provided to less aggressively-wanting peers. 1666 1667 Type: `optionalInteger` (byte count, `null` means default which is 1MB) 1668 1669 #### `Internal.Bitswap.ProviderSearchDelay` 1670 1671 This parameter determines how long to wait before looking for providers outside of bitswap. 1672 Other routing systems like the Amino DHT are able to provide results in less than a second, so lowering 1673 this number will allow faster peers lookups in some cases. 1674 1675 Type: `optionalDuration` (`null` means default which is 1s) 1676 1677 #### `Internal.Bitswap.ProviderSearchMaxResults` 1678 1679 Maximum number of providers bitswap client should aim at before it stops searching for new ones. 1680 Setting to 0 means unlimited. 1681 1682 Type: `optionalInteger` (`null` means default which is 10) 1683 1684 #### `Internal.Bitswap.BroadcastControl` 1685 1686 `Internal.Bitswap.BroadcastControl` contains settings for the bitswap client's broadcast control functionality. 1687 1688 Broadcast control tries to reduce the number of bitswap broadcast messages sent to peers by choosing a subset of of the peers to send to. Peers are chosen based on whether they have previously responded indicating they have wanted blocks, as well as other configurable criteria. The settings here change how peers are selected as broadcast targets. Broadcast control can also be completely disabled to return bitswap to its previous behavior before broadcast control was introduced. 1689 1690 Enabling broadcast control should generally reduce the number of broadcasts significantly without significantly degrading the ability to discover which peers have wanted blocks. However, if block discovery on your network relies sufficiently on broadcasts to discover peers that have wanted blocks, then adjusting the broadcast control configuration or disabling it altogether, may be helpful. 1691 1692 ##### `Internal.Bitswap.BroadcastControl.Enable` 1693 1694 Enables or disables broadcast control functionality. Setting this to `false` disables broadcast reduction logic and restores the previous (Kubo < 0.36) broadcast behavior of sending broadcasts to all peers. When disabled, all other `Bitswap.BroadcastControl` configuration items are ignored. 1695 1696 Default: `true` (Enabled) 1697 1698 Type: `flag` 1699 1700 ##### `Internal.Bitswap.BroadcastControl.MaxPeers` 1701 1702 Sets a hard limit on the number of peers to send broadcasts to. A value of `0` means no broadcasts are sent. A value of `-1` means there is no limit. 1703 1704 Default: `0` (no limit) 1705 1706 Type: `optionalInteger` (non-negative, 0 means no limit) 1707 1708 ##### `Internal.Bitswap.BroadcastControl.LocalPeers` 1709 1710 Enables or disables broadcast control for peers on the local network. Peers that have private or loopback addresses are considered to be on the local network. If this setting is `false`, than always broadcast to peers on the local network. If `true`, apply broadcast control to local peers. 1711 1712 Default: `false` (Always broadcast to peers on local network) 1713 1714 Type: `flag` 1715 1716 ##### `Internal.Bitswap.BroadcastControl.PeeredPeers` 1717 1718 Enables or disables broadcast reduction for peers configured for peering. If `false`, than always broadcast to peers configured for peering. If `true`, apply broadcast reduction to peered peers. 1719 1720 Default: `false` (Always broadcast to peers configured for peering) 1721 1722 Type: `flag` 1723 1724 ##### `Internal.Bitswap.BroadcastControl.MaxRandomPeers` 1725 1726 Sets the number of peers to broadcast to anyway, even though broadcast control logic has determined that they are not broadcast targets. Setting this to a non-zero value ensures at least this number of random peers receives a broadcast. This may be helpful in cases where peers that are not receiving broadcasts my have wanted blocks. 1727 1728 Default: `0` (do not send broadcasts to peers not already targeted broadcast control) 1729 1730 Type: `optionalInteger` (non-negative, 0 means do not broadcast to any random peers) 1731 1732 ##### `Internal.Bitswap.BroadcastControl.SendToPendingPeers` 1733 1734 Enables or disables sending broadcasts to any peers to which there is a pending message to send. When enabled, this sends broadcasts to many more peers, but does so in a way that does not increase the number of separate broadcast messages. There is still the increased cost of the recipients having to process and respond to the broadcasts. 1735 1736 Default: `false` (Do not send broadcasts to all peers for which there are pending messages) 1737 1738 Type: `flag` 1739 1740 ### `Internal.UnixFSShardingSizeThreshold` 1741 1742 **MOVED:** see [`Import.UnixFSHAMTDirectorySizeThreshold`](#importunixfshamtdirectorysizethreshold) 1743 1744 ### `Internal.MFSNoFlushLimit` 1745 1746 Controls the maximum number of consecutive MFS operations allowed with `--flush=false` 1747 before requiring a manual flush. This prevents unbounded memory growth and ensures 1748 data consistency when using deferred flushing with `ipfs files` commands. 1749 1750 When the limit is reached, further operations will fail with an error message 1751 instructing the user to run `ipfs files flush`, use `--flush=true`, or increase 1752 this limit in the configuration. 1753 1754 **Why operations fail instead of auto-flushing:** Automatic flushing once the limit 1755 is reached was considered but rejected because it can lead to data corruption issues 1756 that are difficult to debug. When the system decides to flush without user knowledge, it can: 1757 1758 - Create partial states that violate user expectations about atomicity 1759 - Interfere with concurrent operations in unexpected ways 1760 - Make debugging and recovery much harder when issues occur 1761 1762 By failing explicitly, users maintain control over when their data is persisted, 1763 allowing them to: 1764 1765 - Batch related operations together before flushing 1766 - Handle errors predictably at natural transaction boundaries 1767 - Understand exactly when and why their data is written to disk 1768 1769 If you expect automatic flushing behavior, simply use the default `--flush=true` 1770 (or omit the flag entirely) instead of `--flush=false`. 1771 1772 **⚠️ WARNING:** Increasing this limit or disabling it (setting to 0) can lead to: 1773 1774 - **Out-of-memory errors (OOM)** - Each unflushed operation consumes memory 1775 - **Data loss** - If the daemon crashes before flushing, all unflushed changes are lost 1776 - **Degraded performance** - Large unflushed caches slow down MFS operations 1777 1778 Default: `256` 1779 1780 Type: `optionalInteger` (0 disables the limit, strongly discouraged) 1781 1782 **Note:** This is an EXPERIMENTAL feature and may change or be removed in future releases. 1783 See [#10842](https://github.com/ipfs/kubo/issues/10842) for more information. 1784 1785 ## `Ipns` 1786 1787 ### `Ipns.RepublishPeriod` 1788 1789 A time duration specifying how frequently to republish ipns records to ensure 1790 they stay fresh on the network. 1791 1792 Default: 4 hours. 1793 1794 Type: `interval` or an empty string for the default. 1795 1796 ### `Ipns.RecordLifetime` 1797 1798 A time duration specifying the value to set on ipns records for their validity 1799 lifetime. 1800 1801 Default: 48 hours. 1802 1803 Type: `interval` or an empty string for the default. 1804 1805 ### `Ipns.ResolveCacheSize` 1806 1807 The number of entries to store in an LRU cache of resolved ipns entries. Entries 1808 will be kept cached until their lifetime is expired. 1809 1810 Default: `128` 1811 1812 Type: `integer` (non-negative, 0 means the default) 1813 1814 ### `Ipns.MaxCacheTTL` 1815 1816 Maximum duration for which entries are valid in the name system cache. Applied 1817 to everything under `/ipns/` namespace, allows you to cap 1818 the [Time-To-Live (TTL)](https://specs.ipfs.tech/ipns/ipns-record/#ttl-uint64) of 1819 [IPNS Records](https://specs.ipfs.tech/ipns/ipns-record/) 1820 AND also DNSLink TXT records (when DoH-specific [`DNS.MaxCacheTTL`](https://github.com/ipfs/kubo/blob/master/docs/config.md#dnsmaxcachettl) 1821 is not set to a lower value). 1822 1823 When `Ipns.MaxCacheTTL` is set, it defines the upper bound limit of how long a 1824 [IPNS Name](https://specs.ipfs.tech/ipns/ipns-record/#ipns-name) lookup result 1825 will be cached and read from cache before checking for updates. 1826 1827 **Examples:** 1828 1829 - `"1m"` IPNS results are cached 1m or less (good compromise for system where 1830 faster updates are desired). 1831 - `"0s"` IPNS caching is effectively turned off (useful for testing, bad for production use) 1832 - **Note:** setting this to `0` will turn off TTL-based caching entirely. 1833 This is discouraged in production environments. It will make IPNS websites 1834 artificially slow because IPNS resolution results will expire as soon as 1835 they are retrieved, forcing expensive IPNS lookup to happen on every 1836 request. If you want near-real-time IPNS, set it to a low, but still 1837 sensible value, such as `1m`. 1838 1839 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. 1840 1841 Type: `optionalDuration` 1842 1843 ### `Ipns.UsePubsub` 1844 1845 Enables [IPNS over PubSub](https://specs.ipfs.tech/ipns/ipns-pubsub-router/) for publishing and resolving IPNS records in real time. 1846 1847 **EXPERIMENTAL:** read about current limitations at [experimental-features.md#ipns-pubsub](./experimental-features.md#ipns-pubsub). 1848 1849 Default: `disabled` 1850 1851 Type: `flag` 1852 1853 ### `Ipns.DelegatedPublishers` 1854 1855 HTTP endpoints for delegated IPNS publishing operations. These endpoints must support the [IPNS API](https://specs.ipfs.tech/routing/http-routing-v1/#ipns-api) from the Delegated Routing V1 HTTP specification. 1856 1857 The special value `"auto"` loads delegated publishers from [AutoConf](#autoconf) when enabled. 1858 1859 **Publishing behavior depends on routing configuration:** 1860 1861 - `Routing.Type=auto` (default): Uses DHT for publishing, `"auto"` resolves to empty list 1862 - `Routing.Type=delegated`: Uses HTTP delegated publishers only, `"auto"` resolves to configured endpoints 1863 1864 When using `"auto"`, inspect the effective publishers with: `ipfs config Ipns.DelegatedPublishers --expand-auto` 1865 1866 **Command flags override publishing behavior:** 1867 1868 - `--allow-offline` - Publishes to local datastore without requiring network connectivity 1869 - `--allow-delegated` - Uses local datastore and HTTP delegated publishers only (no DHT connectivity required) 1870 1871 For self-hosting, you can run your own `/routing/v1/ipns` endpoint using [someguy](https://github.com/ipfs/someguy/). 1872 1873 Default: `["auto"]` 1874 1875 Type: `array[string]` (URLs or `"auto"`) 1876 1877 ## `Migration` 1878 1879 > [!WARNING] 1880 > **DEPRECATED:** Only applies to legacy migrations (repo versions <16). Modern repos (v16+) use embedded migrations. 1881 > This section is optional and will not appear in new configurations. 1882 1883 ### `Migration.DownloadSources` 1884 1885 **DEPRECATED:** Download sources for legacy migrations. Only `"HTTPS"` is supported. 1886 1887 Type: `array[string]` (optional) 1888 1889 Default: `["HTTPS"]` 1890 1891 ### `Migration.Keep` 1892 1893 **DEPRECATED:** Controls retention of legacy migration binaries. Options: `"cache"` (default), `"discard"`, `"keep"`. 1894 1895 Type: `string` (optional) 1896 1897 Default: `"cache"` 1898 1899 ## `Mounts` 1900 1901 > [!CAUTION] 1902 > **EXPERIMENTAL:** 1903 > This feature is disabled by default, requires an explicit opt-in with `ipfs mount` or `ipfs daemon --mount`. 1904 > 1905 > Read about current limitations at [fuse.md](./fuse.md). 1906 1907 FUSE mount point configuration options. 1908 1909 ### `Mounts.IPFS` 1910 1911 Mountpoint for `/ipfs/`. 1912 1913 Default: `/ipfs` 1914 1915 Type: `string` (filesystem path) 1916 1917 ### `Mounts.IPNS` 1918 1919 Mountpoint for `/ipns/`. 1920 1921 Default: `/ipns` 1922 1923 Type: `string` (filesystem path) 1924 1925 ### `Mounts.MFS` 1926 1927 Mountpoint for Mutable File System (MFS) behind the `ipfs files` API. 1928 1929 > [!CAUTION] 1930 > 1931 > - Write support is highly experimental and not recommended for mission-critical deployments. 1932 > - 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. 1933 1934 Default: `/mfs` 1935 1936 Type: `string` (filesystem path) 1937 1938 ### `Mounts.FuseAllowOther` 1939 1940 Sets the 'FUSE allow-other' option on the mount point. 1941 1942 ## `Pinning` 1943 1944 Pinning configures the options available for pinning content 1945 (i.e. keeping content longer-term instead of as temporarily cached storage). 1946 1947 ### `Pinning.RemoteServices` 1948 1949 `RemoteServices` maps a name for a remote pinning service to its configuration. 1950 1951 A remote pinning service is a remote service that exposes an API for managing 1952 that service's interest in long-term data storage. 1953 1954 The exposed API conforms to the specification defined at 1955 <https://ipfs.github.io/pinning-services-api-spec/> 1956 1957 #### `Pinning.RemoteServices: API` 1958 1959 Contains information relevant to utilizing the remote pinning service 1960 1961 Example: 1962 1963 ```json 1964 { 1965 "Pinning": { 1966 "RemoteServices": { 1967 "myPinningService": { 1968 "API" : { 1969 "Endpoint" : "https://pinningservice.tld:1234/my/api/path", 1970 "Key" : "someOpaqueKey" 1971 } 1972 } 1973 } 1974 } 1975 } 1976 ``` 1977 1978 ##### `Pinning.RemoteServices: API.Endpoint` 1979 1980 The HTTP(S) endpoint through which to access the pinning service 1981 1982 Example: "<https://pinningservice.tld:1234/my/api/path>" 1983 1984 Type: `string` 1985 1986 ##### `Pinning.RemoteServices: API.Key` 1987 1988 The key through which access to the pinning service is granted 1989 1990 Type: `string` 1991 1992 #### `Pinning.RemoteServices: Policies` 1993 1994 Contains additional opt-in policies for the remote pinning service. 1995 1996 ##### `Pinning.RemoteServices: Policies.MFS` 1997 1998 When this policy is enabled, it follows changes to MFS 1999 and updates the pin for MFS root on the configured remote service. 2000 2001 A pin request to the remote service is sent only when MFS root CID has changed 2002 and enough time has passed since the previous request (determined by `RepinInterval`). 2003 2004 One can observe MFS pinning details by enabling debug via `ipfs log level remotepinning/mfs debug` and switching back to `error` when done. 2005 2006 ###### `Pinning.RemoteServices: Policies.MFS.Enabled` 2007 2008 Controls if this policy is active. 2009 2010 Default: `false` 2011 2012 Type: `bool` 2013 2014 ###### `Pinning.RemoteServices: Policies.MFS.PinName` 2015 2016 Optional name to use for a remote pin that represents the MFS root CID. 2017 When left empty, a default name will be generated. 2018 2019 Default: `"policy/{PeerID}/mfs"`, e.g. `"policy/12.../mfs"` 2020 2021 Type: `string` 2022 2023 ###### `Pinning.RemoteServices: Policies.MFS.RepinInterval` 2024 2025 Defines how often (at most) the pin request should be sent to the remote service. 2026 If left empty, the default interval will be used. Values lower than `1m` will be ignored. 2027 2028 Default: `"5m"` 2029 2030 Type: `duration` 2031 2032 ## `Provide` 2033 2034 Configures how your node advertises content to make it discoverable by other 2035 peers. 2036 2037 **What is providing?** When your node stores content, it publishes provider 2038 records to the routing system announcing "I have this content". These records 2039 map CIDs to your peer ID, enabling content discovery across the network. 2040 2041 While designed to support multiple routing systems in the future, the current 2042 default configuration only supports [providing to the Amino DHT](#providedht). 2043 2044 ### `Provide.Enabled` 2045 2046 Controls whether Kubo provide and reprovide systems are enabled. 2047 2048 > [!CAUTION] 2049 > Disabling this will prevent other nodes from discovering your content. 2050 > Your node will stop announcing data to the routing system, making it 2051 > inaccessible unless peers connect to you directly. 2052 2053 Default: `true` 2054 2055 Type: `flag` 2056 2057 ### `Provide.Strategy` 2058 2059 Tells the provide system what should be announced. Valid strategies are: 2060 2061 - `"all"` - announce all CIDs of stored blocks 2062 - `"pinned"` - only announce recursively pinned CIDs (`ipfs pin add -r`, both roots and child blocks) 2063 - Order: root blocks of direct and recursive pins are announced first, then the child blocks of recursive pins 2064 - `"roots"` - only announce the root block of explicitly pinned CIDs (`ipfs pin add`) 2065 - **⚠️ BE CAREFUL:** node with `roots` strategy will not announce child blocks. 2066 It makes sense only for use cases where the entire DAG is fetched in full, 2067 and a graceful resume does not have to be guaranteed: the lack of child 2068 announcements means an interrupted retrieval won't be able to find 2069 providers for the missing block in the middle of a file, unless the peer 2070 happens to already be connected to a provider and asks for child CID over 2071 bitswap. 2072 - `"mfs"` - announce only the local CIDs that are part of the MFS (`ipfs files`) 2073 - Note: MFS is lazy-loaded. Only the MFS blocks present in local datastore are announced. 2074 - `"pinned+mfs"` - a combination of the `pinned` and `mfs` strategies. 2075 - **ℹ️ NOTE:** This is the suggested strategy for users who run without GC and don't want to provide everything in cache. 2076 - Order: first `pinned` and then the locally available part of `mfs`. 2077 2078 **Strategy changes automatically clear the provide queue.** When you change `Provide.Strategy` and restart Kubo, the provide queue is automatically cleared to ensure only content matching your new strategy is announced. You can also manually clear the queue using `ipfs provide clear`. 2079 2080 **Memory requirements:** 2081 2082 - Reproviding larger pinsets using the `mfs`, `pinned`, `pinned+mfs` or `roots` strategies requires additional memory, with an estimated ~1 GiB of RAM per 20 million CIDs for reproviding to the Amino DHT. 2083 - This is due to the use of a buffered provider, which loads all CIDs into memory to avoid holding a lock on the entire pinset during the reprovide cycle. 2084 2085 Default: `"all"` 2086 2087 Type: `optionalString` (unset for the default) 2088 2089 ### `Provide.DHT` 2090 2091 Configuration for providing data to Amino DHT peers. 2092 2093 **Provider record lifecycle:** On the Amino DHT, provider records expire after 2094 [`amino.DefaultProvideValidity`](https://github.com/libp2p/go-libp2p-kad-dht/blob/v0.34.0/amino/defaults.go#L40-L43). 2095 Your node must re-announce (reprovide) content periodically to keep it 2096 discoverable. The [`Provide.DHT.Interval`](#providedhtinterval) setting 2097 controls this timing, with the default ensuring records refresh well before 2098 expiration or negative churn effects kick in. 2099 2100 **Two provider systems:** 2101 2102 - **Sweep provider**: Divides the DHT keyspace into regions and systematically 2103 sweeps through them over the reprovide interval. This batches CIDs allocated 2104 to the same DHT servers, dramatically reducing the number of DHT lookups and 2105 PUTs needed. Spreads work evenly over time with predictable resource usage. 2106 2107 - **Legacy provider**: Processes each CID individually with separate DHT 2108 lookups. Works well for small content collections but struggles to complete 2109 reprovide cycles when managing thousands of CIDs. 2110 2111 #### Monitoring Provide Operations 2112 2113 **Quick command-line monitoring:** Use `ipfs provide stat` to view the current 2114 state of the provider system. For real-time monitoring, run 2115 `watch ipfs provide stat --all --compact` to see detailed statistics refreshed 2116 continuously in a 2-column layout. 2117 2118 **Long-term monitoring:** For in-depth or long-term monitoring, metrics are 2119 exposed at the Prometheus endpoint: `{Addresses.API}/debug/metrics/prometheus` 2120 (default: `http://127.0.0.1:5001/debug/metrics/prometheus`). Different metrics 2121 are available depending on whether you use legacy mode (`SweepEnabled=false`) or 2122 sweep mode (`SweepEnabled=true`). See [Provide metrics documentation](https://github.com/ipfs/kubo/blob/master/docs/metrics.md#provide) 2123 for details. 2124 2125 **Debug logging:** For troubleshooting, enable detailed logging by setting: 2126 2127 ```sh 2128 GOLOG_LOG_LEVEL=error,provider=debug,dht/provider=debug 2129 ``` 2130 2131 - `provider=debug` enables generic logging (legacy provider and any non-dht operations) 2132 - `dht/provider=debug` enables logging for the sweep provider 2133 2134 #### `Provide.DHT.Interval` 2135 2136 Sets how often to re-announce content to the DHT. Provider records on Amino DHT 2137 expire after [`amino.DefaultProvideValidity`](https://github.com/libp2p/go-libp2p-kad-dht/blob/v0.34.0/amino/defaults.go#L40-L43). 2138 2139 **Why this matters:** The interval must be shorter than the expiration window to 2140 ensure provider records refresh before they expire. The default value is 2141 approximately half of [`amino.DefaultProvideValidity`](https://github.com/libp2p/go-libp2p-kad-dht/blob/v0.34.0/amino/defaults.go#L40-L43), 2142 which accounts for network churn and ensures records stay alive without 2143 overwhelming the network with unnecessary announcements. 2144 2145 **With sweep mode enabled 2146 ([`Provide.DHT.SweepEnabled`](#providedhtsweepenabled)):** The system spreads 2147 reprovide operations smoothly across this entire interval. Each keyspace region 2148 is reprovided at scheduled times throughout the period, ensuring each region's 2149 announcements complete before records expire. 2150 2151 **With legacy mode:** The system attempts to reprovide all CIDs as quickly as 2152 possible at the start of each interval. If reproviding takes longer than this 2153 interval (common with large datasets), the next cycle is skipped and provider 2154 records may expire. 2155 2156 - If unset, it uses the implicit safe default. 2157 - If set to the value `"0"` it will disable content reproviding to DHT. 2158 2159 > [!CAUTION] 2160 > Disabling this will prevent other nodes from discovering your content via the DHT. 2161 > Your node will stop announcing data to the DHT, making it 2162 > inaccessible unless peers connect to you directly. Since provider 2163 > records expire after `amino.DefaultProvideValidity`, your content will become undiscoverable 2164 > after this period. 2165 2166 Default: `22h` 2167 2168 Type: `optionalDuration` (unset for the default) 2169 2170 #### `Provide.DHT.MaxWorkers` 2171 2172 Sets the maximum number of _concurrent_ DHT provide operations. 2173 2174 **When `Provide.DHT.SweepEnabled` is false (legacy mode):** 2175 2176 - Controls NEW CID announcements only 2177 - Reprovide operations do **not** count against this limit 2178 - A value of `0` allows unlimited provide workers 2179 2180 **When `Provide.DHT.SweepEnabled` is true:** 2181 2182 - Controls the total worker pool for both provide and reprovide operations 2183 - Workers are split between periodic reprovides and burst provides 2184 - Use a positive value to control resource usage 2185 - See [`DedicatedPeriodicWorkers`](#providedhtdedicatedperiodicworkers) and [`DedicatedBurstWorkers`](#providedhtdedicatedburstworkers) for task allocation 2186 2187 If the [accelerated DHT client](#routingaccelerateddhtclient) is enabled, each 2188 provide operation opens ~20 connections in parallel. With the standard DHT 2189 client (accelerated disabled), each provide opens between 20 and 60 2190 connections, with at most 10 active at once. Provides complete more quickly 2191 when using the accelerated client. Be mindful of how many simultaneous 2192 connections this setting can generate. 2193 2194 > [!CAUTION] 2195 > For nodes without strict connection limits that need to provide large volumes 2196 > of content, we recommend first trying `Provide.DHT.SweepEnabled=true` for efficient 2197 > announcements. If announcements are still not fast enough, adjust `Provide.DHT.MaxWorkers`. 2198 > As a last resort, consider enabling `Routing.AcceleratedDHTClient=true` but be aware that it is very resource hungry. 2199 > 2200 > At the same time, mind that raising this value too high may lead to increased load. 2201 > Proceed with caution, ensure proper hardware and networking are in place. 2202 2203 > [!TIP] 2204 > **When `SweepEnabled` is true:** Users providing millions of CIDs or more 2205 > should increase the worker count accordingly. Underprovisioning can lead to 2206 > slow provides (burst workers) and inability to keep up with content 2207 > reproviding (periodic workers). For nodes with sufficient resources (CPU, 2208 > bandwidth, number of connections), dedicating `1024` for [periodic 2209 > workers](#providedhtdedicatedperiodicworkers) and `512` for [burst 2210 > workers](#providedhtdedicatedburstworkers), and `2048` [max 2211 > workers](#providedhtmaxworkers) should be adequate even for the largest 2212 > users. The system will only use workers as needed - unused resources won't be 2213 > consumed. Ensure you adjust the swarm [connection manager](#swarmconnmgr) and 2214 > [resource manager](#swarmresourcemgr) configuration accordingly. 2215 > See [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning) for more details. 2216 2217 Default: `16` 2218 2219 Type: `optionalInteger` (non-negative; `0` means unlimited number of workers) 2220 2221 #### `Provide.DHT.SweepEnabled` 2222 2223 Enables the sweep provider for efficient content announcements. When disabled, 2224 the legacy [`boxo/provider`](https://github.com/ipfs/boxo/tree/main/provider) is 2225 used instead. 2226 2227 **The legacy provider problem:** The legacy system processes CIDs one at a 2228 time, requiring a separate DHT lookup (10-20 seconds each) to find the 20 2229 closest peers for each CID. This sequential approach typically handles less 2230 than 10,000 CID over 22h ([`Provide.DHT.Interval`](#providedhtinterval)). If 2231 your node has more CIDs than can be reprovided within 2232 [`Provide.DHT.Interval`](#providedhtinterval), provider records start expiring 2233 after 2234 [`amino.DefaultProvideValidity`](https://github.com/libp2p/go-libp2p-kad-dht/blob/v0.34.0/amino/defaults.go#L40-L43), 2235 making content undiscoverable. 2236 2237 **How sweep mode works:** The sweep provider divides the DHT keyspace into 2238 regions based on keyspace prefixes. It estimates the Amino DHT size, calculates 2239 how many regions are needed (sized to contain at least 20 peers each), then 2240 schedules region processing evenly across 2241 [`Provide.DHT.Interval`](#providedhtinterval). When processing a region, it 2242 discovers the peers in that region once, then sends all provider records for 2243 CIDs allocated to those peers in a batch. This batching is the key efficiency: 2244 instead of N lookups for N CIDs, the number of lookups is bounded by a constant 2245 fraction of the Amino DHT size (e.g., ~3,000 lookups when there are ~10,000 DHT 2246 servers), regardless of how many CIDs you're providing. 2247 2248 **Efficiency gains:** For a node providing 100,000 CIDs, sweep mode reduces 2249 lookups by 97% compared to legacy. The work spreads smoothly over time rather 2250 than completing in bursts, preventing resource spikes and duplicate 2251 announcements. Long-running nodes reprovide systematically just before records 2252 would expire, keeping content continuously discoverable without wasting 2253 bandwidth. 2254 2255 **Implementation details:** The sweep provider tracks CIDs in a persistent 2256 keystore. New content added via `StartProviding()` enters the provide queue and 2257 gets batched by keyspace region. The keystore is periodically refreshed at each 2258 [`Provide.DHT.Interval`](#providedhtinterval) with CIDs matching 2259 [`Provide.Strategy`](#providestrategy) to ensure only current content remains 2260 scheduled. This handles cases where content is unpinned or removed. 2261 2262 **Persistent reprovide cycle state:** When Provide Sweep is enabled, the 2263 reprovide cycle state is persisted to the datastore by default. On restart, Kubo 2264 automatically resumes from where it left off. If the node was offline for an 2265 extended period, all CIDs that haven't been reprovided within the configured 2266 [`Provide.DHT.Interval`](#providedhtinterval) are immediately queued for 2267 reproviding. Additionally, the provide queue is persisted on shutdown and 2268 restored on startup, ensuring no pending provide operations are lost. If you 2269 don't want to keep the persisted provider state from a previous run, you can 2270 disable this behavior by setting [`Provide.DHT.ResumeEnabled`](#providedhtresumeenabled) 2271 to `false`. 2272 2273 > <picture> 2274 > <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/f6e06b08-7fee-490c-a681-1bf440e16e27"> 2275 > <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/e1662d7c-f1be-4275-a9ed-f2752fcdcabe"> 2276 > <img alt="Reprovide Cycle Comparison" src="https://github.com/user-attachments/assets/e1662d7c-f1be-4275-a9ed-f2752fcdcabe"> 2277 > </picture> 2278 > 2279 > The diagram compares performance patterns: 2280 > 2281 > - **Legacy mode**: Sequential processing, one lookup per CID, struggles with large datasets 2282 > - **Sweep mode**: Smooth distribution over time, batched lookups by keyspace region, predictable resource usage 2283 > - **Accelerated DHT**: Hourly network crawls creating traffic spikes, high resource usage 2284 > 2285 > Sweep mode achieves similar effectiveness to the Accelerated DHT client but with steady resource consumption. 2286 2287 For background on the sweep provider design and motivations, see Shipyard's blogpost [Provide Sweep: Solving the DHT Provide Bottleneck](https://ipshipyard.com/blog/2025-dht-provide-sweep/). 2288 2289 You can compare the effectiveness of sweep mode vs legacy mode by monitoring the appropriate metrics (see [Monitoring Provide Operations](#monitoring-provide-operations) above). 2290 2291 > [!NOTE] 2292 > This is the default provider system as of Kubo v0.39. To use the legacy provider instead, set `Provide.DHT.SweepEnabled=false`. 2293 2294 > [!NOTE] 2295 > When DHT routing is unavailable (e.g., `Routing.Type=custom` with only HTTP routers), the provider automatically falls back to the legacy provider regardless of this setting. 2296 2297 Default: `true` 2298 2299 Type: `flag` 2300 2301 #### `Provide.DHT.ResumeEnabled` 2302 2303 Controls whether the provider resumes from its previous state on restart. Only 2304 applies when `Provide.DHT.SweepEnabled` is true. 2305 2306 When enabled (the default), the provider persists its reprovide cycle state and 2307 provide queue to the datastore, and restores them on restart. This ensures: 2308 2309 - The reprovide cycle continues from where it left off instead of starting over 2310 - Any CIDs in the provide queue during shutdown are restored and provided after 2311 restart 2312 - CIDs that missed their reprovide window while the node was offline are queued 2313 for immediate reproviding 2314 2315 When disabled, the provider starts fresh on each restart, discarding any 2316 previous reprovide cycle state and provide queue. On a fresh start, all CIDs 2317 matching the [`Provide.Strategy`](#providestrategy) will be provided ASAP (as 2318 burst provides), and then keyspace regions are reprovided according to the 2319 regular schedule starting from the beginning of the reprovide cycle. 2320 2321 > [!NOTE] 2322 > Disabling this option means the provider will provide all content matching 2323 > your strategy on every restart (which can be resource-intensive for large 2324 > datasets), then start from the beginning of the reprovide cycle. For nodes 2325 > with large datasets or frequent restarts, keeping this enabled (the default) 2326 > is recommended for better resource efficiency and more consistent reproviding 2327 > behavior. 2328 2329 Default: `true` 2330 2331 Type: `flag` 2332 2333 #### `Provide.DHT.DedicatedPeriodicWorkers` 2334 2335 Number of workers dedicated to periodic keyspace region reprovides. Only 2336 applies when `Provide.DHT.SweepEnabled` is true. 2337 2338 Among the [`Provide.DHT.MaxWorkers`](#providedhtmaxworkers), this 2339 number of workers will be dedicated to the periodic region reprovide only. The sum of 2340 `DedicatedPeriodicWorkers` and `DedicatedBurstWorkers` should not exceed `MaxWorkers`. 2341 Any remaining workers (MaxWorkers - DedicatedPeriodicWorkers - DedicatedBurstWorkers) 2342 form a shared pool that can be used for either type of work as needed. 2343 2344 > [!NOTE] 2345 > If the provider system isn't able to keep up with reproviding all your 2346 > content within the [Provide.DHT.Interval](#providedhtinterval), consider 2347 > increasing this value. 2348 2349 Default: `2` 2350 2351 Type: `optionalInteger` (`0` means there are no dedicated workers, but the 2352 operation can be performed by free non-dedicated workers) 2353 2354 #### `Provide.DHT.DedicatedBurstWorkers` 2355 2356 Number of workers dedicated to burst provides. Only applies when `Provide.DHT.SweepEnabled` is true. 2357 2358 Burst provides are triggered by: 2359 2360 - Manual provide commands (`ipfs routing provide`) 2361 - New content matching your `Provide.Strategy` (blocks from `ipfs add`, bitswap, or trustless gateway requests) 2362 - Catch-up reprovides after being disconnected/offline for a while 2363 2364 Having dedicated burst workers ensures that bulk operations (like adding many CIDs 2365 or reconnecting to the network) don't delay regular periodic reprovides, and vice versa. 2366 2367 Among the [`Provide.DHT.MaxWorkers`](#providedhtmaxworkers), this 2368 number of workers will be dedicated to burst provides only. In addition to 2369 these, if there are available workers in the pool, they can also be used for 2370 burst provides. 2371 2372 > [!NOTE] 2373 > If CIDs aren't provided quickly enough to your taste, and you can afford more 2374 > CPU and bandwidth, consider increasing this value. 2375 2376 Default: `1` 2377 2378 Type: `optionalInteger` (`0` means there are no dedicated workers, but the 2379 operation can be performed by free non-dedicated workers) 2380 2381 #### `Provide.DHT.MaxProvideConnsPerWorker` 2382 2383 Maximum number of connections that a single worker can use to send provider 2384 records over the network. 2385 2386 When reproviding CIDs corresponding to a keyspace region, the reprovider must 2387 send a provider record to the 20 closest peers to the CID (in XOR distance) for 2388 each CID belonging to this keyspace region. 2389 2390 The reprovider opens a connection to a peer from that region, sends it all its 2391 allocated provider records. Once done, it opens a connection to the next peer 2392 from that keyspace region until all provider records are assigned. 2393 2394 This option defines how many such connections can be open concurrently by a 2395 single worker. 2396 2397 > [!NOTE] 2398 > Increasing this value can speed up the provide operation, at the cost of 2399 > opening more simultaneous connections to DHT servers. A keyspace typically 2400 > has less than 60 peers, so you may hit a performance ceiling beyond which 2401 > increasing this value has no effect. 2402 2403 Default: `20` 2404 2405 Type: `optionalInteger` (non-negative) 2406 2407 #### `Provide.DHT.KeystoreBatchSize` 2408 2409 During the garbage collection, all keys stored in the Keystore are removed, and 2410 the keys are streamed from a channel to fill the Keystore again with up-to-date 2411 keys. Since a high number of CIDs to reprovide can easily fill up the memory, 2412 keys are read and written in batches to optimize for memory usage. 2413 2414 This option defines how many multihashes should be contained within a batch. A 2415 multihash is usually represented by 34 bytes. 2416 2417 Default: `16384` (~544 KiB per batch) 2418 2419 Type: `optionalInteger` (non-negative) 2420 2421 #### `Provide.DHT.OfflineDelay` 2422 2423 The `SweepingProvider` has 3 states: `ONLINE`, `DISCONNECTED` and `OFFLINE`. It 2424 starts `OFFLINE`, and as the node bootstraps, it changes its state to `ONLINE`. 2425 2426 When the provider loses connection to all DHT peers, it switches to the 2427 `DISCONNECTED` state. In this state, new provides will be added to the provide 2428 queue, and provided as soon as the node comes back online. 2429 2430 After a node has been `DISCONNECTED` for `OfflineDelay`, it goes to `OFFLINE` 2431 state. When `OFFLINE`, the provider drops the provide queue, and returns errors 2432 to new provide requests. However, when `OFFLINE` the provider still adds the 2433 keys to its state, so keys will eventually be provided in the 2434 [`Provide.DHT.Interval`](#providedhtinterval) after the provider comes back 2435 `ONLINE`. 2436 2437 Default: `2h` 2438 2439 Type: `optionalDuration` 2440 2441 ## `Provider` 2442 2443 ### `Provider.Enabled` 2444 2445 **REMOVED** 2446 2447 Replaced with [`Provide.Enabled`](#provideenabled). 2448 2449 ### `Provider.Strategy` 2450 2451 **REMOVED** 2452 2453 This field was unused. Use [`Provide.Strategy`](#providestrategy) instead. 2454 2455 ### `Provider.WorkerCount` 2456 2457 **REMOVED** 2458 2459 Replaced with [`Provide.DHT.MaxWorkers`](#providedhtmaxworkers). 2460 2461 ## `Pubsub` 2462 2463 Pubsub configures Kubo's opt-in, opinionated [libp2p pubsub](https://web.archive.org/web/20260116065034/https://docs.libp2p.io/concepts/pubsub/overview/) instance. 2464 To enable, set `Pubsub.Enabled` to `true`. 2465 2466 **EXPERIMENTAL:** This is an opt-in feature. Its primary use case is 2467 [IPNS over PubSub](https://specs.ipfs.tech/ipns/ipns-pubsub-router/), which 2468 enables real-time IPNS record propagation. See [`Ipns.UsePubsub`](#ipnsusepubsub) 2469 for details. 2470 2471 The `ipfs pubsub` commands can also be used for basic publish/subscribe 2472 operations, but only if Kubo's built-in message validation (described below) is 2473 acceptable for your use case. 2474 2475 ### When to use a dedicated pubsub node 2476 2477 Kubo's pubsub is optimized for IPNS. It uses opinionated message validation 2478 that may not fit all applications. If you need custom Message ID computation, 2479 different deduplication logic, or validation rules beyond what Kubo provides, 2480 consider building a dedicated pubsub node using 2481 [go-libp2p-pubsub](https://github.com/libp2p/go-libp2p-pubsub) directly. 2482 2483 ### Message deduplication 2484 2485 Kubo uses two layers of message deduplication to handle duplicate messages that 2486 may arrive via different network paths: 2487 2488 **Layer 1: In-memory TimeCache (Message ID)** 2489 2490 When a message arrives, Kubo computes its Message ID (hash of the message 2491 content) and checks an in-memory cache. If the ID was seen recently, the 2492 message is dropped. This cache is controlled by: 2493 2494 - [`Pubsub.SeenMessagesTTL`](#pubsubseenmessagesttl) - how long Message IDs are remembered (default: 120s) 2495 - [`Pubsub.SeenMessagesStrategy`](#pubsubseenmessagesstrategy) - whether TTL resets on each sighting 2496 2497 This cache is fast but limited: it only works within the TTL window and is 2498 cleared on node restart. 2499 2500 **Layer 2: Persistent Seqno Validator (per-peer)** 2501 2502 For stronger deduplication, Kubo tracks the maximum sequence number seen from 2503 each peer and persists it to the datastore. Messages with sequence numbers 2504 lower than the recorded maximum are rejected. This prevents replay attacks and 2505 handles message cycles in large networks where messages may take longer than 2506 the TimeCache TTL to propagate. 2507 2508 This layer survives node restarts. The state can be inspected or cleared using 2509 `ipfs pubsub reset` (for testing/recovery only). 2510 2511 ### `Pubsub.Enabled` 2512 2513 Enables the pubsub system. 2514 2515 Default: `false` 2516 2517 Type: `flag` 2518 2519 ### `Pubsub.Router` 2520 2521 Sets the default router used by pubsub to route messages to peers. This can be one of: 2522 2523 - `"floodsub"` - floodsub is a basic router that simply _floods_ messages to all 2524 connected peers. This router is extremely inefficient but _very_ reliable. 2525 - `"gossipsub"` - [gossipsub][] is a more advanced routing algorithm that will 2526 build an overlay mesh from a subset of the links in the network. 2527 2528 Default: `"gossipsub"` 2529 2530 Type: `string` (one of `"floodsub"`, `"gossipsub"`, or `""` (apply default)) 2531 2532 [gossipsub]: https://github.com/libp2p/specs/tree/master/pubsub/gossipsub 2533 2534 ### `Pubsub.DisableSigning` 2535 2536 Disables message signing and signature verification. 2537 2538 **FOR TESTING ONLY - DO NOT USE IN PRODUCTION** 2539 2540 It is _not_ safe to disable signing even if you don't care _who_ sent the 2541 message because spoofed messages can be used to silence real messages by 2542 intentionally re-using the real message's message ID. 2543 2544 Default: `false` 2545 2546 Type: `bool` 2547 2548 ### `Pubsub.SeenMessagesTTL` 2549 2550 Controls the time window for the in-memory Message ID cache (Layer 1 2551 deduplication). Messages with the same ID seen within this window are dropped. 2552 2553 A smaller value reduces memory usage but may cause more duplicates in networks 2554 with slow nodes. A larger value uses more memory but provides better duplicate 2555 detection within the time window. 2556 2557 Default: see `TimeCacheDuration` from [go-libp2p-pubsub](https://github.com/libp2p/go-libp2p-pubsub) 2558 2559 Type: `optionalDuration` 2560 2561 ### `Pubsub.SeenMessagesStrategy` 2562 2563 Determines how the TTL countdown for the Message ID cache works. 2564 2565 - `last-seen` - Sliding window: TTL resets each time the message is seen again. 2566 Keeps frequently-seen messages in cache longer, preventing continued propagation. 2567 - `first-seen` - Fixed window: TTL counts from first sighting only. Messages are 2568 purged after the TTL regardless of how many times they're seen. 2569 2570 Default: `last-seen` (see [go-libp2p-pubsub](https://github.com/libp2p/go-libp2p-pubsub)) 2571 2572 Type: `optionalString` 2573 2574 ## `Peering` 2575 2576 Configures the peering subsystem. The peering subsystem configures Kubo to 2577 connect to, remain connected to, and reconnect to a set of nodes. Nodes should 2578 use this subsystem to create "sticky" links between frequently useful peers to 2579 improve reliability. 2580 2581 Use-cases: 2582 2583 - An IPFS gateway connected to an IPFS cluster should peer to ensure that the 2584 gateway can always fetch content from the cluster. 2585 - A dapp may peer embedded Kubo nodes with a set of pinning services or 2586 textile cafes/hubs. 2587 - A set of friends may peer to ensure that they can always fetch each other's 2588 content. 2589 2590 When a node is added to the set of peered nodes, Kubo will: 2591 2592 1. Protect connections to this node from the connection manager. That is, 2593 Kubo will never automatically close the connection to this node and 2594 connections to this node will not count towards the connection limit. 2595 2. Connect to this node on startup. 2596 3. Repeatedly try to reconnect to this node if the last connection dies or the 2597 node goes offline. This repeated re-connect logic is governed by a randomized 2598 exponential backoff delay ranging from ~5 seconds to ~10 minutes to avoid 2599 repeatedly reconnect to a node that's offline. 2600 2601 Peering can be asymmetric or symmetric: 2602 2603 - When symmetric, the connection will be protected by both nodes and will likely 2604 be very stable. 2605 - When asymmetric, only one node (the node that configured peering) will protect 2606 the connection and attempt to re-connect to the peered node on disconnect. If 2607 the peered node is under heavy load and/or has a low connection limit, the 2608 connection may flap repeatedly. Be careful when asymmetrically peering to not 2609 overload peers. 2610 2611 ### `Peering.Peers` 2612 2613 The set of peers with which to peer. 2614 2615 ```json 2616 { 2617 "Peering": { 2618 "Peers": [ 2619 { 2620 "ID": "QmPeerID1", 2621 "Addrs": ["/ip4/18.1.1.1/tcp/4001"] 2622 }, 2623 { 2624 "ID": "QmPeerID2", 2625 "Addrs": ["/ip4/18.1.1.2/tcp/4001", "/ip4/18.1.1.2/udp/4001/quic-v1"] 2626 } 2627 ] 2628 } 2629 ... 2630 } 2631 ``` 2632 2633 Where `ID` is the peer ID and `Addrs` is a set of known addresses for the peer. If no addresses are specified, the Amino DHT will be queried. 2634 2635 Additional fields may be added in the future. 2636 2637 Default: empty. 2638 2639 Type: `array[peering]` 2640 2641 ## `Reprovider` 2642 2643 ### `Reprovider.Interval` 2644 2645 **REMOVED** 2646 2647 Replaced with [`Provide.DHT.Interval`](#providedhtinterval). 2648 2649 ### `Reprovider.Strategy` 2650 2651 **REMOVED** 2652 2653 Replaced with [`Provide.Strategy`](#providestrategy). 2654 2655 ## `Routing` 2656 2657 Contains options for content, peer, and IPNS routing mechanisms. 2658 2659 ### `Routing.Type` 2660 2661 Controls how your node discovers content and peers on the network. 2662 2663 **Production options:** 2664 2665 - **`auto`** (default): Uses both the public IPFS DHT (Amino) and HTTP routers 2666 from [`Routing.DelegatedRouters`](#routingdelegatedrouters) for faster lookups. 2667 Your node starts as a DHT client and automatically switches to server mode 2668 when reachable from the public internet. 2669 2670 - **`autoclient`**: Same as `auto`, but never runs a DHT server. 2671 Use this if your node is behind a firewall or NAT. 2672 2673 - **`dht`**: Uses only the Amino DHT (no HTTP routers). Automatically switches 2674 between client and server mode based on reachability. 2675 2676 - **`dhtclient`**: DHT-only, always running as a client. Lower resource usage. 2677 2678 - **`dhtserver`**: DHT-only, always running as a server. 2679 Only use this if your node is reachable from the public internet. 2680 2681 - **`none`**: Disables all routing. You must manually connect to peers. 2682 2683 **About DHT client vs server mode:** 2684 When the DHT is enabled, your node can operate as either a client or server. 2685 In server mode, it queries other peers and responds to their queries - this helps 2686 the network but uses more resources. In client mode, it only queries others without 2687 responding, which is less resource-intensive. With `auto` or `dht`, your node starts 2688 as a client and switches to server when it detects public reachability. 2689 2690 > [!CAUTION] 2691 > **`Routing.Type` Experimental options:** 2692 > 2693 > These modes are for research and testing only, not production use. 2694 > They may change without notice between releases. 2695 > 2696 > - **`delegated`**: Uses only HTTP routers from [`Routing.DelegatedRouters`](#routingdelegatedrouters) 2697 > and IPNS publishers from [`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers), 2698 > without initializing the DHT. Useful when peer-to-peer connectivity is unavailable. 2699 > Note: cannot provide content to the network (no DHT means no provider records). 2700 > 2701 > - **`custom`**: Disables all default routers. You define your own routing in 2702 > [`Routing.Routers`](#routingrouters). See [delegated-routing.md](delegated-routing.md). 2703 2704 Default: `auto` 2705 2706 Type: `optionalString` (`null`/missing means the default) 2707 2708 ### `Routing.DelegatedRouters` 2709 2710 An array of URL hostnames for delegated routers to be queried in addition to the Amino DHT when `Routing.Type` is set to `auto` (default) or `autoclient`. 2711 These endpoints must support the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/). 2712 2713 The special value `"auto"` uses delegated routers from [AutoConf](#autoconf) when enabled. 2714 You can combine `"auto"` with custom URLs (e.g., `["auto", "https://custom.example.com"]`) to query both the default delegated routers and your own endpoints. The first `"auto"` entry gets substituted with autoconf values, and other URLs are preserved. 2715 2716 > [!TIP] 2717 > Delegated routing allows IPFS implementations to offload tasks like content routing, peer routing, and naming to a separate process or server while also benefiting from HTTP caching. 2718 > 2719 > One can run their own delegated router either by implementing the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) themselves, or by using [Someguy](https://github.com/ipfs/someguy), a turn-key implementation that proxies requests to other routing systems. A public utility instance of Someguy is hosted at [`https://delegated-ipfs.dev`](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing). 2720 2721 Default: `["auto"]` 2722 2723 Type: `array[string]` (URLs or `"auto"`) 2724 2725 ### `Routing.AcceleratedDHTClient` 2726 2727 This alternative Amino DHT client with a Full-Routing-Table strategy will 2728 do a complete scan of the DHT every hour and record all nodes found. 2729 Then when a lookup is tried instead of having to go through multiple Kad hops it 2730 is able to find the 20 final nodes by looking up the in-memory recorded network table. 2731 2732 This means sustained higher memory to store the routing table 2733 and extra CPU and network bandwidth for each network scan. 2734 However the latency of individual read/write operations should be ~10x faster 2735 and provide throughput up to 6 million times faster on larger datasets! 2736 2737 This is not compatible with `Routing.Type` `custom`. If you are using composable routers 2738 you can configure this individually on each router. 2739 2740 When it is enabled: 2741 2742 - Client DHT operations (reads and writes) should complete much faster 2743 - The provider will now use a keyspace sweeping mode allowing to keep alive 2744 CID sets that are multiple orders of magnitude larger. 2745 - **Note:** For improved provide/reprovide operations specifically, consider using 2746 [`Provide.DHT.SweepEnabled`](#providedhtsweepenabled) instead, which offers similar 2747 benefits without the hourly traffic spikes. 2748 - The standard Bucket-Routing-Table DHT will still run for the DHT server (if 2749 the DHT server is enabled). This means the classical routing table will 2750 still be used to answer other nodes. 2751 This is critical to maintain to not harm the network. 2752 - The operations `ipfs stats dht` will default to showing information about the accelerated DHT client 2753 2754 > [!CAUTION] 2755 > **`Routing.AcceleratedDHTClient` Caveats:** 2756 > 2757 > 1. Running the accelerated client likely will result in more resource consumption (connections, RAM, CPU, bandwidth) 2758 > - Users that are limited in the number of parallel connections their machines/networks can perform will be most affected 2759 > - The resource usage is not smooth as the client crawls the network in rounds and reproviding is similarly done in rounds 2760 > - Users who previously had a lot of content but were unable to advertise it on the network will see an increase in 2761 > egress bandwidth as their nodes start to advertise all of their CIDs into the network. If you have lots of data 2762 > entering your node that you don't want to advertise, consider using [`Provide.*`](#provide) configuration 2763 > to control which CIDs are reprovided. 2764 > 2. Currently, the DHT is not usable for queries for the first 5-10 minutes of operation as the routing table is being 2765 > prepared. This means operations like searching the DHT for particular peers or content will not work initially. 2766 > - You can see if the DHT has been initially populated by running `ipfs stats dht` 2767 > 3. Currently, the accelerated DHT client is not compatible with LAN-based DHTs and will not perform operations against 2768 > them. 2769 2770 Default: `false` 2771 2772 Type: `flag` 2773 2774 ### `Routing.LoopbackAddressesOnLanDHT` 2775 2776 **EXPERIMENTAL: `Routing.LoopbackAddressesOnLanDHT` configuration may change in future release** 2777 2778 Whether loopback addresses (e.g. 127.0.0.1) should not be ignored on the local LAN DHT. 2779 2780 Most users do not need this setting. It can be useful during testing, when multiple Kubo nodes run on the same machine but some of them do not have `Discovery.MDNS.Enabled`. 2781 2782 Default: `false` 2783 2784 Type: `bool` (missing means `false`) 2785 2786 ### `Routing.IgnoreProviders` 2787 2788 An array of [string-encoded PeerIDs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation). Any provider record associated to one of these peer IDs is ignored. 2789 2790 Apart from ignoring specific providers for reasons like misbehaviour etc. this 2791 setting is useful to ignore providers as a way to indicate preference, when the same provider 2792 is found under different peerIDs (i.e. one for HTTP and one for Bitswap retrieval). 2793 2794 > [!TIP] 2795 > This denylist operates on PeerIDs. 2796 > To deny specific HTTP Provider URL, use [`HTTPRetrieval.Denylist`](#httpretrievaldenylist) instead. 2797 2798 Default: `[]` 2799 2800 Type: `array[string]` 2801 2802 ### `Routing.Routers` 2803 2804 Alternative configuration used when `Routing.Type=custom`. 2805 2806 > [!CAUTION] 2807 > **EXPERIMENTAL: `Routing.Routers` is for research and testing only, not production use.** 2808 > 2809 > - The configuration format and behavior may change without notice between releases. 2810 > - Bugs and regressions may not be prioritized. 2811 > - HTTP-only configurations cannot reliably provide content. See [delegated-routing.md](delegated-routing.md#limitations). 2812 > 2813 > Most users should use `Routing.Type=auto` or `autoclient` with [`Routing.DelegatedRouters`](#routingdelegatedrouters). 2814 2815 Allows for replacing the default routing (Amino DHT) with alternative Router 2816 implementations. 2817 2818 The map key is a name of a Router, and the value is its configuration. 2819 2820 Default: `{}` 2821 2822 Type: `object[string->object]` 2823 2824 #### `Routing.Routers.[name].Type` 2825 2826 **⚠️ EXPERIMENTAL: For research and testing only. May change without notice.** 2827 2828 It specifies the routing type that will be created. 2829 2830 Currently supported types: 2831 2832 - `http` simple delegated routing based on HTTP protocol from [IPIP-337](https://specs.ipfs.tech/ipips/ipip-0337/) 2833 - `dht` provides decentralized routing based on [libp2p's kad-dht](https://github.com/libp2p/specs/tree/master/kad-dht) 2834 - `parallel` and `sequential`: Helpers that can be used to run several routers sequentially or in parallel. 2835 2836 Type: `string` 2837 2838 #### `Routing.Routers.[name].Parameters` 2839 2840 **⚠️ EXPERIMENTAL: For research and testing only. May change without notice.** 2841 2842 Parameters needed to create the specified router. Supported params per router type: 2843 2844 HTTP: 2845 2846 - `Endpoint` (mandatory): URL that will be used to connect to a specified router. 2847 - `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. 2848 - `MaxProvideConcurrency`: It determines the number of threads used when providing content. GOMAXPROCS by default. 2849 2850 DHT: 2851 2852 - `"Mode"`: Mode used by the Amino DHT. Possible values: "server", "client", "auto" 2853 - `"AcceleratedDHTClient"`: Set to `true` if you want to use the acceleratedDHT. 2854 - `"PublicIPNetwork"`: Set to `true` to create a `WAN` DHT. Set to `false` to create a `LAN` DHT. 2855 2856 Parallel: 2857 2858 - `Routers`: A list of routers that will be executed in parallel: 2859 - `Name:string`: Name of the router. It should be one of the previously added to `Routers` list. 2860 - `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. 2861 - `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`). 2862 - `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred. 2863 - `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`). 2864 2865 Sequential: 2866 2867 - `Routers`: A list of routers that will be executed in order: 2868 - `Name:string`: Name of the router. It should be one of the previously added to `Routers` list. 2869 - `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. 2870 - `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred. 2871 - `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)`. 2872 2873 Default: `{}` (use the safe implicit defaults) 2874 2875 Type: `object[string->string]` 2876 2877 ### `Routing.Methods` 2878 2879 `Methods:map` will define which routers will be executed per method used when `Routing.Type=custom`. 2880 2881 > [!CAUTION] 2882 > **EXPERIMENTAL: `Routing.Methods` is for research and testing only, not production use.** 2883 > 2884 > - The configuration format and behavior may change without notice between releases. 2885 > - Bugs and regressions may not be prioritized. 2886 > - HTTP-only configurations cannot reliably provide content. See [delegated-routing.md](delegated-routing.md#limitations). 2887 > 2888 > Most users should use `Routing.Type=auto` or `autoclient` with [`Routing.DelegatedRouters`](#routingdelegatedrouters). 2889 2890 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. 2891 2892 The value will contain: 2893 2894 - `RouterName:string`: Name of the router. It should be one of the previously added to `Routing.Routers` list. 2895 2896 Type: `object[string->object]` 2897 2898 **Examples:** 2899 2900 Complete example using 2 Routers, Amino DHT (LAN/WAN) and parallel. 2901 2902 ``` 2903 $ ipfs config Routing.Type --json '"custom"' 2904 2905 $ ipfs config Routing.Routers.WanDHT --json '{ 2906 "Type": "dht", 2907 "Parameters": { 2908 "Mode": "auto", 2909 "PublicIPNetwork": true, 2910 "AcceleratedDHTClient": false 2911 } 2912 }' 2913 2914 $ ipfs config Routing.Routers.LanDHT --json '{ 2915 "Type": "dht", 2916 "Parameters": { 2917 "Mode": "auto", 2918 "PublicIPNetwork": false, 2919 "AcceleratedDHTClient": false 2920 } 2921 }' 2922 2923 $ ipfs config Routing.Routers.ParallelHelper --json '{ 2924 "Type": "parallel", 2925 "Parameters": { 2926 "Routers": [ 2927 { 2928 "RouterName" : "LanDHT", 2929 "IgnoreErrors" : true, 2930 "Timeout": "3s" 2931 }, 2932 { 2933 "RouterName" : "WanDHT", 2934 "IgnoreErrors" : false, 2935 "Timeout": "5m", 2936 "ExecuteAfter": "2s" 2937 } 2938 ] 2939 } 2940 }' 2941 2942 ipfs config Routing.Methods --json '{ 2943 "find-peers": { 2944 "RouterName": "ParallelHelper" 2945 }, 2946 "find-providers": { 2947 "RouterName": "ParallelHelper" 2948 }, 2949 "get-ipns": { 2950 "RouterName": "ParallelHelper" 2951 }, 2952 "provide": { 2953 "RouterName": "ParallelHelper" 2954 }, 2955 "put-ipns": { 2956 "RouterName": "ParallelHelper" 2957 } 2958 }' 2959 2960 ``` 2961 2962 ## `Swarm` 2963 2964 Options for configuring the swarm. 2965 2966 ### `Swarm.AddrFilters` 2967 2968 An array of addresses (multiaddr netmasks) to not dial. By default, IPFS nodes 2969 advertise _all_ addresses, even internal ones. This makes it easier for nodes on 2970 the same network to reach each other. Unfortunately, this means that an IPFS 2971 node will try to connect to one or more private IP addresses whenever dialing 2972 another node, even if this other node is on a different network. This may 2973 trigger netscan alerts on some hosting providers or cause strain in some setups. 2974 2975 > [!TIP] 2976 > The [`server` configuration profile](#server-profile) fills up this list with sensible defaults, 2977 > preventing dials to all non-routable IP addresses (e.g., `/ip4/192.168.0.0/ipcidr/16`, 2978 > which is the [multiaddress][multiaddr] representation of `192.168.0.0/16`) but you should always 2979 > check settings against your own network and/or hosting provider. 2980 2981 Default: `[]` 2982 2983 Type: `array[string]` 2984 2985 ### `Swarm.DisableBandwidthMetrics` 2986 2987 A boolean value that when set to true, will cause ipfs to not keep track of 2988 bandwidth metrics. Disabling bandwidth metrics can lead to a slight performance 2989 improvement, as well as a reduction in memory usage. 2990 2991 Default: `false` 2992 2993 Type: `bool` 2994 2995 ### `Swarm.DisableNatPortMap` 2996 2997 Disable automatic NAT port forwarding (turn off [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play)). 2998 2999 When not disabled (default), Kubo asks NAT devices (e.g., routers), to open 3000 up an external port and forward it to the port Kubo is running on. When this 3001 works (i.e., when your router supports NAT port forwarding), it makes the local 3002 Kubo node accessible from the public internet. 3003 3004 Default: `false` 3005 3006 Type: `bool` 3007 3008 ### `Swarm.EnableHolePunching` 3009 3010 Enable hole punching for NAT traversal 3011 when port forwarding is not possible. 3012 3013 When enabled, Kubo will coordinate with the counterparty using 3014 a [relayed connection](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md), 3015 to [upgrade to a direct connection](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md) 3016 through a NAT/firewall whenever possible. 3017 This feature requires `Swarm.RelayClient.Enabled` to be set to `true`. 3018 3019 Default: `true` 3020 3021 Type: `flag` 3022 3023 ### `Swarm.EnableAutoRelay` 3024 3025 **REMOVED** 3026 3027 See `Swarm.RelayClient` instead. 3028 3029 ### `Swarm.RelayClient` 3030 3031 Configuration options for the relay client to use relay services. 3032 3033 Default: `{}` 3034 3035 Type: `object` 3036 3037 #### `Swarm.RelayClient.Enabled` 3038 3039 Enables "automatic relay user" mode for this node. 3040 3041 Your node will automatically _use_ public relays from the network if it detects 3042 that it cannot be reached from the public internet (e.g., it's behind a 3043 firewall) and get a `/p2p-circuit` address from a public relay. 3044 3045 Default: `true` 3046 3047 Type: `flag` 3048 3049 #### `Swarm.RelayClient.StaticRelays` 3050 3051 Your node will use these statically configured relay servers 3052 instead of discovering public relays ([Circuit Relay v2](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md)) from the network. 3053 3054 Default: `[]` 3055 3056 Type: `array[string]` 3057 3058 ### `Swarm.RelayService` 3059 3060 Configuration options for the relay service that can be provided to _other_ peers 3061 on the network ([Circuit Relay v2](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md)). 3062 3063 Default: `{}` 3064 3065 Type: `object` 3066 3067 #### `Swarm.RelayService.Enabled` 3068 3069 Enables providing `/p2p-circuit` v2 relay service to other peers on the network. 3070 3071 NOTE: This is the service/server part of the relay system. 3072 Disabling this will prevent this node from running as a relay server. 3073 Use [`Swarm.RelayClient.Enabled`](#swarmrelayclientenabled) for turning your node into a relay user. 3074 3075 Default: `true` 3076 3077 Type: `flag` 3078 3079 #### `Swarm.RelayService.Limit` 3080 3081 Limits are applied to every relayed connection. 3082 3083 Default: `{}` 3084 3085 Type: `object[string -> string]` 3086 3087 ##### `Swarm.RelayService.ConnectionDurationLimit` 3088 3089 Time limit before a relayed connection is reset. 3090 3091 Default: `"2m"` 3092 3093 Type: `duration` 3094 3095 ##### `Swarm.RelayService.ConnectionDataLimit` 3096 3097 Limit of data relayed (in each direction) before a relayed connection is reset. 3098 3099 Default: `131072` (128 kb) 3100 3101 Type: `optionalInteger` 3102 3103 #### `Swarm.RelayService.ReservationTTL` 3104 3105 Duration of a new or refreshed reservation. 3106 3107 Default: `"1h"` 3108 3109 Type: `duration` 3110 3111 #### `Swarm.RelayService.MaxReservations` 3112 3113 Maximum number of active relay slots. 3114 3115 Default: `128` 3116 3117 Type: `optionalInteger` 3118 3119 #### `Swarm.RelayService.MaxCircuits` 3120 3121 Maximum number of open relay connections for each peer. 3122 3123 Default: `16` 3124 3125 Type: `optionalInteger` 3126 3127 #### `Swarm.RelayService.BufferSize` 3128 3129 Size of the relayed connection buffers. 3130 3131 Default: `2048` 3132 3133 Type: `optionalInteger` 3134 3135 #### `Swarm.RelayService.MaxReservationsPerPeer` 3136 3137 **REMOVED in kubo 0.32 due to [go-libp2p#2974](https://github.com/libp2p/go-libp2p/pull/2974)** 3138 3139 #### `Swarm.RelayService.MaxReservationsPerIP` 3140 3141 Maximum number of reservations originating from the same IP. 3142 3143 Default: `8` 3144 3145 Type: `optionalInteger` 3146 3147 #### `Swarm.RelayService.MaxReservationsPerASN` 3148 3149 Maximum number of reservations originating from the same ASN. 3150 3151 Default: `32` 3152 3153 Type: `optionalInteger` 3154 3155 ### `Swarm.EnableRelayHop` 3156 3157 **REMOVED** 3158 3159 Replaced with [`Swarm.RelayService.Enabled`](#swarmrelayserviceenabled). 3160 3161 ### `Swarm.DisableRelay` 3162 3163 **REMOVED** 3164 3165 Set `Swarm.Transports.Network.Relay` to `false` instead. 3166 3167 ### `Swarm.EnableAutoNATService` 3168 3169 **REMOVED** 3170 3171 Please use [`AutoNAT.ServiceMode`](#autonatservicemode). 3172 3173 ### `Swarm.ConnMgr` 3174 3175 The connection manager determines which and how many connections to keep and can 3176 be configured to keep. Kubo currently supports two connection managers: 3177 3178 - none: never close idle connections. 3179 - basic: the default connection manager. 3180 3181 By default, this section is empty and the implicit defaults defined below 3182 are used. 3183 3184 #### `Swarm.ConnMgr.Type` 3185 3186 Sets the type of connection manager to use, options are: `"none"` (no connection 3187 management) and `"basic"`. 3188 3189 Default: "basic". 3190 3191 Type: `optionalString` (default when unset or empty) 3192 3193 #### Basic Connection Manager 3194 3195 The basic connection manager uses a "high water", a "low water", and internal 3196 scoring to periodically close connections to free up resources. When a node 3197 using the basic connection manager reaches `HighWater` idle connections, it 3198 will close the least useful ones until it reaches `LowWater` idle 3199 connections. The process of closing connections happens every `SilencePeriod`. 3200 3201 The connection manager considers a connection idle if: 3202 3203 - It has not been explicitly _protected_ by some subsystem. For example, Bitswap 3204 will protect connections to peers from which it is actively downloading data, 3205 the DHT will protect some peers for routing, and the peering subsystem will 3206 protect all "peered" nodes. 3207 - It has existed for longer than the `GracePeriod`. 3208 3209 **Example:** 3210 3211 ```json 3212 { 3213 "Swarm": { 3214 "ConnMgr": { 3215 "Type": "basic", 3216 "LowWater": 100, 3217 "HighWater": 200, 3218 "GracePeriod": "30s", 3219 "SilencePeriod": "10s" 3220 } 3221 } 3222 } 3223 ``` 3224 3225 ##### `Swarm.ConnMgr.LowWater` 3226 3227 LowWater is the number of connections that the basic connection manager will 3228 trim down to. 3229 3230 Default: `32` 3231 3232 Type: `optionalInteger` 3233 3234 ##### `Swarm.ConnMgr.HighWater` 3235 3236 HighWater is the number of connections that, when exceeded, will trigger a 3237 connection GC operation. Note: protected/recently formed connections don't count 3238 towards this limit. 3239 3240 Default: `96` 3241 3242 Type: `optionalInteger` 3243 3244 ##### `Swarm.ConnMgr.GracePeriod` 3245 3246 GracePeriod is a time duration that new connections are immune from being closed 3247 by the connection manager. 3248 3249 Default: `"20s"` 3250 3251 Type: `optionalDuration` 3252 3253 ##### `Swarm.ConnMgr.SilencePeriod` 3254 3255 SilencePeriod is the time duration between connection manager runs, when connections that are idle are closed. 3256 3257 Default: `"10s"` 3258 3259 Type: `optionalDuration` 3260 3261 ### `Swarm.ResourceMgr` 3262 3263 Learn more about Kubo's usage of libp2p Network Resource Manager 3264 in the [dedicated resource management docs](./libp2p-resource-management.md). 3265 3266 #### `Swarm.ResourceMgr.Enabled` 3267 3268 Enables the libp2p Resource Manager using limits based on the defaults and/or other configuration as discussed in [libp2p resource management](./libp2p-resource-management.md). 3269 3270 Default: `true` 3271 Type: `flag` 3272 3273 #### `Swarm.ResourceMgr.MaxMemory` 3274 3275 This is the max amount of memory to allow go-libp2p to use. 3276 3277 libp2p's resource manager will prevent additional resource creation while this limit is reached. 3278 This value is also used to scale the limit on various resources at various scopes 3279 when the default limits (discussed in [libp2p resource management](./libp2p-resource-management.md)) are used. 3280 For example, increasing this value will increase the default limit for incoming connections. 3281 3282 It is possible to inspect the runtime limits via `ipfs swarm resources --help`. 3283 3284 > [!IMPORTANT] 3285 > `Swarm.ResourceMgr.MaxMemory` is the memory limit for go-libp2p networking stack alone, and not for entire Kubo or Bitswap. 3286 > 3287 > To set memory limit for the entire Kubo process, use [`GOMEMLIMIT` environment variable](http://web.archive.org/web/20240222201412/https://kupczynski.info/posts/go-container-aware/) which all Go programs recognize, and then set `Swarm.ResourceMgr.MaxMemory` to less than your custom `GOMEMLIMIT`. 3288 3289 Default: `[TOTAL_SYSTEM_MEMORY]/2` 3290 Type: [`optionalBytes`](#optionalbytes) 3291 3292 #### `Swarm.ResourceMgr.MaxFileDescriptors` 3293 3294 This is the maximum number of file descriptors to allow libp2p to use. 3295 libp2p's resource manager will prevent additional file descriptor consumption while this limit is reached. 3296 3297 This param is ignored on Windows. 3298 3299 Default `[TOTAL_SYSTEM_FILE_DESCRIPTORS]/2` 3300 Type: `optionalInteger` 3301 3302 #### `Swarm.ResourceMgr.Allowlist` 3303 3304 A list of [multiaddrs][libp2p-multiaddrs] that can bypass normal system limits (but are still limited by the allowlist scope). 3305 Convenience config around [go-libp2p-resource-manager#Allowlist.Add](https://pkg.go.dev/github.com/libp2p/go-libp2p/p2p/host/resource-manager#Allowlist.Add). 3306 3307 Default: `[]` 3308 3309 Type: `array[string]` ([multiaddrs][multiaddr]) 3310 3311 ### `Swarm.Transports` 3312 3313 Configuration section for libp2p transports. An empty configuration will apply 3314 the defaults. 3315 3316 ### `Swarm.Transports.Network` 3317 3318 Configuration section for libp2p _network_ transports. Transports enabled in 3319 this section will be used for dialing. However, to receive connections on these 3320 transports, multiaddrs for these transports must be added to `Addresses.Swarm`. 3321 3322 Supported transports are: QUIC, TCP, WS, Relay, WebTransport and WebRTCDirect. 3323 3324 > [!CAUTION] 3325 > **SECURITY CONSIDERATIONS FOR NETWORK TRANSPORTS** 3326 > 3327 > Enabling network transports allows your node to accept connections from the internet. 3328 > Ensure your firewall rules and [`Addresses.Swarm`](#addressesswarm) configuration 3329 > align with your security requirements. 3330 > See [Security section](#security) for network exposure considerations. 3331 3332 Each field in this section is a `flag`. 3333 3334 #### `Swarm.Transports.Network.TCP` 3335 3336 [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) is a simple 3337 and widely deployed transport, it should be compatible with most implementations 3338 and network configurations. TCP doesn't directly support encryption and/or 3339 multiplexing, so libp2p will layer a security & multiplexing transport over it. 3340 3341 Default: Enabled 3342 3343 Type: `flag` 3344 3345 Listen Addresses: 3346 3347 - /ip4/0.0.0.0/tcp/4001 (default) 3348 - /ip6/::/tcp/4001 (default) 3349 3350 #### `Swarm.Transports.Network.Websocket` 3351 3352 [Websocket](https://en.wikipedia.org/wiki/WebSocket) is a transport usually used 3353 to connect to non-browser-based IPFS nodes from browser-based js-ipfs nodes. 3354 3355 While it's enabled by default for dialing, Kubo doesn't listen on this 3356 transport by default. 3357 3358 Default: Enabled 3359 3360 Type: `flag` 3361 3362 Listen Addresses: 3363 3364 - /ip4/0.0.0.0/tcp/4001/ws 3365 - /ip6/::/tcp/4001/ws 3366 3367 #### `Swarm.Transports.Network.QUIC` 3368 3369 [QUIC](https://en.wikipedia.org/wiki/QUIC) is the most widely used transport by 3370 Kubo nodes. It is a UDP-based transport with built-in encryption and 3371 multiplexing. The primary benefits over TCP are: 3372 3373 1. It takes 1 round trip to establish a connection (our TCP transport 3374 currently takes 4). 3375 2. No [Head-of-Line blocking](https://en.wikipedia.org/wiki/Head-of-line_blocking). 3376 3. It doesn't require a file descriptor per connection, easing the load on the OS. 3377 3378 Default: Enabled 3379 3380 Type: `flag` 3381 3382 Listen Addresses: 3383 3384 - `/ip4/0.0.0.0/udp/4001/quic-v1` (default) 3385 - `/ip6/::/udp/4001/quic-v1` (default) 3386 3387 #### `Swarm.Transports.Network.Relay` 3388 3389 [Libp2p Relay](https://github.com/libp2p/specs/tree/master/relay) proxy 3390 transport that forms connections by hopping between multiple libp2p nodes. 3391 Allows IPFS node to connect to other peers using their `/p2p-circuit` 3392 [multiaddrs][libp2p-multiaddrs]. This transport is primarily useful for bypassing firewalls and 3393 NATs. 3394 3395 See also: 3396 3397 - Docs: [Libp2p Circuit Relay](https://web.archive.org/web/20260128152445/https://docs.libp2p.io/concepts/nat/circuit-relay/) 3398 - [`Swarm.RelayClient.Enabled`](#swarmrelayclientenabled) for getting a public 3399 - `/p2p-circuit` address when behind a firewall. 3400 - [`Swarm.EnableHolePunching`](#swarmenableholepunching) for direct connection upgrade through relay 3401 - [`Swarm.RelayService.Enabled`](#swarmrelayserviceenabled) for becoming a 3402 limited relay for other peers 3403 3404 Default: Enabled 3405 3406 Type: `flag` 3407 3408 Listen Addresses: 3409 3410 - This transport is special. Any node that enables this transport can receive 3411 inbound connections on this transport, without specifying a listen address. 3412 3413 #### `Swarm.Transports.Network.WebTransport` 3414 3415 A new feature of [`go-libp2p`](https://github.com/libp2p/go-libp2p/releases/tag/v0.23.0) 3416 is the [WebTransport](https://github.com/libp2p/go-libp2p/issues/1717) transport. 3417 3418 This is a spiritual descendant of WebSocket but over `HTTP/3`. 3419 Since this runs on top of `HTTP/3` it uses `QUIC` under the hood. 3420 We expect it to perform worst than `QUIC` because of the extra overhead, 3421 this transport is really meant at agents that cannot do `TCP` or `QUIC` (like browsers). 3422 3423 WebTransport is a new transport protocol currently under development by the IETF and the W3C, and already implemented by Chrome. 3424 Conceptually, it’s like WebSocket run over QUIC instead of TCP. Most importantly, it allows browsers to establish (secure!) connections to WebTransport servers without the need for CA-signed certificates, 3425 thereby enabling any js-libp2p node running in a browser to connect to any kubo node, with zero manual configuration involved. 3426 3427 The previous alternative is websocket secure, which require installing a reverse proxy and TLS certificates manually. 3428 3429 Default: Enabled 3430 3431 Type: `flag` 3432 3433 Listen Addresses: 3434 3435 - `/ip4/0.0.0.0/udp/4001/quic-v1/webtransport` (default) 3436 - `/ip6/::/udp/4001/quic-v1/webtransport` (default) 3437 3438 #### `Swarm.Transports.Network.WebRTCDirect` 3439 3440 [WebRTC Direct](https://github.com/libp2p/specs/blob/master/webrtc/webrtc-direct.md) 3441 is a transport protocol that provides another way for browsers to 3442 connect to the rest of the libp2p network. WebRTC Direct allows for browser 3443 nodes to connect to other nodes without special configuration, such as TLS 3444 certificates. This can be useful for browser nodes that do not yet support 3445 [WebTransport](https://web.archive.org/web/20260107053250/https://blog.libp2p.io/2022-12-19-libp2p-webtransport/), 3446 which is still relatively new and has [known issues](https://github.com/libp2p/js-libp2p/issues/2572). 3447 3448 Enabling this transport allows Kubo node to act on `/udp/4001/webrtc-direct` 3449 listeners defined in `Addresses.Swarm`, `Addresses.Announce` or 3450 `Addresses.AppendAnnounce`. 3451 3452 > [!NOTE] 3453 > WebRTC Direct is browser-to-node. It cannot be used to connect a browser 3454 > node to a node that is behind a NAT or firewall (without UPnP port mapping). 3455 > The browser-to-private requires using normal 3456 > [WebRTC](https://github.com/libp2p/specs/blob/master/webrtc/webrtc.md), 3457 > which is currently being worked on in 3458 > [go-libp2p#2009](https://github.com/libp2p/go-libp2p/issues/2009). 3459 3460 Default: Enabled 3461 3462 Type: `flag` 3463 3464 Listen Addresses: 3465 3466 - `/ip4/0.0.0.0/udp/4001/webrtc-direct` (default) 3467 - `/ip6/::/udp/4001/webrtc-direct` (default) 3468 3469 ### `Swarm.Transports.Security` 3470 3471 Configuration section for libp2p _security_ transports. Transports enabled in 3472 this section will be used to secure unencrypted connections. 3473 3474 This does not concern all the QUIC transports which use QUIC's builtin encryption. 3475 3476 Security transports are configured with the `priority` type. 3477 3478 When establishing an _outbound_ connection, Kubo will try each security 3479 transport in priority order (lower first), until it finds a protocol that the 3480 receiver supports. When establishing an _inbound_ connection, Kubo will let 3481 the initiator choose the protocol, but will refuse to use any of the disabled 3482 transports. 3483 3484 Supported transports are: TLS (priority 100) and Noise (priority 200). 3485 3486 No default priority will ever be less than 100. Lower values have precedence. 3487 3488 #### `Swarm.Transports.Security.TLS` 3489 3490 [TLS](https://github.com/libp2p/specs/tree/master/tls) (1.3) is the default 3491 security transport as of Kubo 0.5.0. It's also the most scrutinized and 3492 trusted security transport. 3493 3494 Default: `100` 3495 3496 Type: `priority` 3497 3498 #### `Swarm.Transports.Security.SECIO` 3499 3500 **REMOVED**: support for SECIO has been removed. Please remove this option from your config. 3501 3502 #### `Swarm.Transports.Security.Noise` 3503 3504 [Noise](https://github.com/libp2p/specs/tree/master/noise) is slated to replace 3505 TLS as the cross-platform, default libp2p protocol due to ease of 3506 implementation. It is currently enabled by default but with low priority as it's 3507 not yet widely supported. 3508 3509 Default: `200` 3510 3511 Type: `priority` 3512 3513 ### `Swarm.Transports.Multiplexers` 3514 3515 Configuration section for libp2p _multiplexer_ transports. Transports enabled in 3516 this section will be used to multiplex duplex connections. 3517 3518 This does not concern all the QUIC transports which use QUIC's builtin muxing. 3519 3520 Multiplexer transports are configured the same way security transports are, with 3521 the `priority` type. Like with security transports, the initiator gets their 3522 first choice. 3523 3524 Supported transport is only: Yamux (priority 100) 3525 3526 No default priority will ever be less than 100. 3527 3528 ### `Swarm.Transports.Multiplexers.Yamux` 3529 3530 Yamux is the default multiplexer used when communicating between Kubo nodes. 3531 3532 Default: `100` 3533 3534 Type: `priority` 3535 3536 ### `Swarm.Transports.Multiplexers.Mplex` 3537 3538 **REMOVED**: See <https://github.com/ipfs/kubo/issues/9958> 3539 3540 Support for Mplex has been [removed from Kubo and go-libp2p](https://github.com/libp2p/specs/issues/553). 3541 Please remove this option from your config. 3542 3543 ## `DNS` 3544 3545 Options for configuring DNS resolution for [DNSLink](https://docs.ipfs.tech/concepts/dnslink/) and `/dns*` [Multiaddrs][libp2p-multiaddrs] (including peer addresses discovered via DHT or delegated routing). 3546 3547 ### `DNS.Resolvers` 3548 3549 Map of [FQDNs](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) to custom resolver URLs. 3550 3551 This allows for overriding the default DNS resolver provided by the operating system, 3552 and using different resolvers per domain or TLD (including ones from alternative, non-ICANN naming systems). 3553 3554 Example: 3555 3556 ```json 3557 { 3558 "DNS": { 3559 "Resolvers": { 3560 "eth.": "https://dns.eth.limo/dns-query", 3561 "crypto.": "https://resolver.unstoppable.io/dns-query", 3562 "libre.": "https://ns1.iriseden.fr/dns-query", 3563 ".": "https://cloudflare-dns.com/dns-query" 3564 } 3565 } 3566 } 3567 ``` 3568 3569 Be mindful that: 3570 3571 - Currently only `https://` URLs for [DNS over HTTPS (DoH)](https://en.wikipedia.org/wiki/DNS_over_HTTPS) endpoints are supported as values. 3572 - 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. 3573 - Out-of-the-box support for selected non-ICANN TLDs relies on third-party centralized services provided by respective communities on best-effort basis. 3574 - 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. 3575 - When [`AutoTLS.SkipDNSLookup`](#autotlsskipdnslookup) is enabled (default), domains matching [`AutoTLS.DomainSuffix`](#autotlsdomainsuffix) (default: `libp2p.direct`) are resolved locally by parsing the IP directly from the hostname. Set `AutoTLS.SkipDNSLookup=false` to force network DNS lookups for these domains. 3576 3577 Default: `{".": "auto"}` 3578 3579 Type: `object[string -> string]` 3580 3581 ### `DNS.MaxCacheTTL` 3582 3583 Maximum duration for which entries are valid in the DoH cache. 3584 3585 This allows you to cap the Time-To-Live suggested by the DNS response ([RFC2181](https://datatracker.ietf.org/doc/html/rfc2181#section-8)). 3586 If present, the upper bound is applied to DoH resolvers in [`DNS.Resolvers`](#dnsresolvers). 3587 3588 Note: this does NOT work with Go's default DNS resolver. To make this a global setting, add a `.` entry to `DNS.Resolvers` first. 3589 3590 **Examples:** 3591 3592 - `"1m"` DNS entries are kept for 1 minute or less. 3593 - `"0s"` DNS entries expire as soon as they are retrieved. 3594 3595 Default: Respect DNS Response TTL 3596 3597 Type: `optionalDuration` 3598 3599 ## `HTTPRetrieval` 3600 3601 `HTTPRetrieval` is configuration for pure HTTP retrieval based on Trustless HTTP Gateways' 3602 [Block Responses (`application/vnd.ipld.raw`)](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw) 3603 which can be used in addition to or instead of retrieving blocks with [Bitswap over Libp2p](#bitswap). 3604 3605 Default: `{}` 3606 3607 Type: `object` 3608 3609 ### `HTTPRetrieval.Enabled` 3610 3611 Controls whether HTTP-based block retrieval is enabled. 3612 3613 When enabled, Kubo will act on `/tls/http` (HTTP/2) providers ([Trustless HTTP Gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/)) returned by the [`Routing.DelegatedRouters`](#routingdelegatedrouters) 3614 to perform pure HTTP [block retrievals](https://specs.ipfs.tech/http-gateways/trustless-gateway/#block-responses-application-vnd-ipld-raw) 3615 (`/ipfs/cid?format=raw`, `Accept: application/vnd.ipld.raw`) 3616 alongside [Bitswap over Libp2p](#bitswap). 3617 3618 HTTP requests for `application/vnd.ipld.raw` will be made instead of Bitswap when a peer has a `/tls/http` multiaddr 3619 and the HTTPS server returns HTTP 200 for the [probe path](https://specs.ipfs.tech/http-gateways/trustless-gateway/#dedicated-probe-paths). 3620 3621 > [!IMPORTANT] 3622 > This feature is relatively new. Please report any issues via [Github](https://github.com/ipfs/kubo/issues/new). 3623 > 3624 > Important notes: 3625 > 3626 > - TLS and HTTP/2 are required. For privacy reasons, and to maintain feature-parity with browsers, unencrypted `http://` providers are ignored and not used. 3627 > - This feature works in the same way as Bitswap: connected HTTP-peers receive optimistic block requests even for content that they are not announcing. 3628 > - For performance reasons, and to avoid loops, the HTTP client does not follow redirects. Providers should keep announcements up to date. 3629 > - IPFS ecosystem is working towards [supporting HTTP providers on Amino DHT](https://github.com/ipfs/specs/issues/496). Currently, HTTP providers are mostly limited to results from [`Routing.DelegatedRouters`](#routingdelegatedrouters) endpoints and requires `Routing.Type=auto|autoclient`. 3630 3631 Default: `true` 3632 3633 Type: `flag` 3634 3635 ### `HTTPRetrieval.Allowlist` 3636 3637 Optional list of hostnames for which HTTP retrieval is allowed for. 3638 If this list is not empty, only hosts matching these entries will be allowed for HTTP retrieval. 3639 3640 > [!TIP] 3641 > To limit HTTP retrieval to a provider at `/dns4/example.com/tcp/443/tls/http` (which would serve `HEAD|GET https://example.com/ipfs/cid?format=raw`), set this to `["example.com"]` 3642 3643 Default: `[]` 3644 3645 Type: `array[string]` 3646 3647 ### `HTTPRetrieval.Denylist` 3648 3649 Optional list of hostnames for which HTTP retrieval is not allowed. 3650 Denylist entries take precedence over Allowlist entries. 3651 3652 > [!TIP] 3653 > This denylist operates on HTTP endpoint hostnames. 3654 > To deny specific PeerID, use [`Routing.IgnoreProviders`](#routingignoreproviders) instead. 3655 3656 Default: `[]` 3657 3658 Type: `array[string]` 3659 3660 ### `HTTPRetrieval.NumWorkers` 3661 3662 The number of worker goroutines to use for concurrent HTTP retrieval operations. 3663 This setting controls the level of parallelism for HTTP-based block retrieval operations. 3664 Higher values can improve performance when retrieving many blocks but may increase resource usage. 3665 3666 Default: `16` 3667 3668 Type: `optionalInteger` 3669 3670 ### `HTTPRetrieval.MaxBlockSize` 3671 3672 Sets the maximum size of a block that the HTTP retrieval client will accept. 3673 3674 > [!NOTE] 3675 > This setting is a security feature designed to protect Kubo from malicious providers who might send excessively large or invalid data. 3676 > Increasing this value allows Kubo to retrieve larger blocks from compatible HTTP providers, but doing so reduces interoperability with Bitswap, and increases potential security risks. 3677 > 3678 > Learn more: [Supporting Large IPLD Blocks: Why block limits?](https://discuss.ipfs.tech/t/supporting-large-ipld-blocks/15093#why-block-limits-5) 3679 3680 Default: `2MiB` (matching [Bitswap size limit](https://specs.ipfs.tech/bitswap-protocol/#block-sizes)) 3681 3682 Type: `optionalString` 3683 3684 ### `HTTPRetrieval.TLSInsecureSkipVerify` 3685 3686 Disables TLS certificate validation. 3687 Allows making HTTPS connections to HTTP/2 test servers with self-signed TLS certificates. 3688 Only for testing, do not use in production. 3689 3690 Default: `false` 3691 3692 Type: `flag` 3693 3694 ## `Import` 3695 3696 Options to configure the default parameters used for ingesting data, in commands such as `ipfs add` or `ipfs block put`. All affected commands are detailed per option. 3697 3698 These options implement [IPIP-499: UnixFS CID Profiles](https://specs.ipfs.tech/ipips/ipip-0499/) for reproducible CID generation across IPFS implementations. Instead of configuring individual options, you can apply a predefined profile with `ipfs config profile apply <profile-name>`. See [Profiles](#profiles) for available options like `unixfs-v1-2025`. 3699 3700 Note that using CLI flags will override the options defined here. 3701 3702 ### `Import.CidVersion` 3703 3704 The default CID version. Commands affected: `ipfs add`. 3705 3706 Must be either 0 or 1. CIDv0 uses SHA2-256 only, while CIDv1 supports multiple hash functions. 3707 3708 Default: `0` 3709 3710 Type: `optionalInteger` 3711 3712 ### `Import.UnixFSRawLeaves` 3713 3714 The default UnixFS raw leaves option. Commands affected: `ipfs add`, `ipfs files write`. 3715 3716 Default: `false` if `CidVersion=0`; `true` if `CidVersion=1` 3717 3718 Type: `flag` 3719 3720 ### `Import.UnixFSChunker` 3721 3722 The default UnixFS chunker. Commands affected: `ipfs add`. 3723 3724 Valid formats: 3725 3726 - `size-<bytes>` - fixed size chunker 3727 - `rabin-<min>-<avg>-<max>` - rabin fingerprint chunker 3728 - `buzhash` - buzhash chunker 3729 3730 The maximum accepted value for `size-<bytes>` and rabin `max` parameter is 3731 `2MiB - 256 bytes` (2096896 bytes). The 256-byte overhead budget is reserved 3732 for protobuf/UnixFS framing so that serialized blocks stay within the 2MiB 3733 block size limit defined by the 3734 [bitswap spec](https://specs.ipfs.tech/bitswap-protocol/#block-sizes). 3735 The `buzhash` chunker uses a fixed internal maximum of 512KiB and is not 3736 affected by this limit. 3737 3738 Only the fixed-size chunker (`size-<bytes>`) guarantees that the same data 3739 will always produce the same CID. The `rabin` and `buzhash` chunkers may 3740 change their internal parameters in a future release. 3741 3742 Default: `size-262144` 3743 3744 Type: `optionalString` 3745 3746 ### `Import.HashFunction` 3747 3748 The default hash function. Commands affected: `ipfs add`, `ipfs block put`, `ipfs dag put`. 3749 3750 Must be a valid multihash name (e.g., `sha2-256`, `blake3`) and must be allowed for use in IPFS according to security constraints. 3751 3752 Run `ipfs cid hashes --supported` to see the full list of allowed hash functions. 3753 3754 Default: `sha2-256` 3755 3756 Type: `optionalString` 3757 3758 ### `Import.FastProvideRoot` 3759 3760 Immediately provide root CIDs to the DHT in addition to the regular provide queue. 3761 3762 This complements the sweep provider system: fast-provide handles the urgent case (root CIDs that users share and reference), while the sweep provider efficiently provides all blocks according to the `Provide.Strategy` over time. Together, they optimize for both immediate discoverability of newly imported content and efficient resource usage for complete DAG provides. 3763 3764 When disabled, only the sweep provider's queue is used. 3765 3766 This setting applies to both `ipfs add` and `ipfs dag import` commands and can be overridden per-command with the `--fast-provide-root` flag. 3767 3768 Ignored when DHT is not available for routing (e.g., `Routing.Type=none` or delegated-only configurations). 3769 3770 Default: `true` 3771 3772 Type: `flag` 3773 3774 ### `Import.FastProvideWait` 3775 3776 Wait for the immediate root CID provide to complete before returning. 3777 3778 When enabled, the command blocks until the provide completes, ensuring guaranteed discoverability before returning. When disabled (default), the provide happens asynchronously in the background without blocking the command. 3779 3780 Use this when you need certainty that content is discoverable before the command returns (e.g., sharing a link immediately after adding). 3781 3782 This setting applies to both `ipfs add` and `ipfs dag import` commands and can be overridden per-command with the `--fast-provide-wait` flag. 3783 3784 Ignored when DHT is not available for routing (e.g., `Routing.Type=none` or delegated-only configurations). 3785 3786 Default: `false` 3787 3788 Type: `flag` 3789 3790 ### `Import.BatchMaxNodes` 3791 3792 The maximum number of nodes in a write-batch. The total size of the batch is limited by `BatchMaxnodes` and `BatchMaxSize`. 3793 3794 Increasing this will batch more items together when importing data with `ipfs dag import`, which can speed things up. 3795 3796 Must be positive (> 0). Setting to 0 would cause immediate batching after each node, which is inefficient. 3797 3798 Default: `128` 3799 3800 Type: `optionalInteger` 3801 3802 ### `Import.BatchMaxSize` 3803 3804 The maximum size of a single write-batch (computed as the sum of the sizes of the blocks). The total size of the batch is limited by `BatchMaxnodes` and `BatchMaxSize`. 3805 3806 Increasing this will batch more items together when importing data with `ipfs dag import`, which can speed things up. 3807 3808 Must be positive (> 0). Setting to 0 would cause immediate batching after any data, which is inefficient. 3809 3810 Default: `20971520` (20MiB) 3811 3812 Type: `optionalInteger` 3813 3814 ### `Import.UnixFSFileMaxLinks` 3815 3816 The maximum number of links that a node part of a UnixFS File can have 3817 when building the DAG while importing. 3818 3819 This setting controls both the fanout in files that are chunked into several 3820 blocks and grouped as a Unixfs (dag-pb) DAG. 3821 3822 Must be positive (> 0). Zero or negative values would break file DAG construction. 3823 3824 Default: `174` 3825 3826 Type: `optionalInteger` 3827 3828 ### `Import.UnixFSDirectoryMaxLinks` 3829 3830 The maximum number of links that a node part of a UnixFS basic directory can 3831 have when building the DAG while importing. 3832 3833 This setting controls both the fanout for basic, non-HAMT folder nodes. It 3834 sets a limit after which directories are converted to a HAMT-based structure. 3835 3836 When unset (0), no limit exists for children. Directories will be converted to 3837 HAMTs based on their estimated size only. 3838 3839 This setting will cause basic directories to be converted to HAMTs when they 3840 exceed the maximum number of children. This happens transparently during the 3841 add process. The fanout of HAMT nodes is controlled by `MaxHAMTFanout`. 3842 3843 Must be non-negative (>= 0). Zero means no limit, negative values are invalid. 3844 3845 Commands affected: `ipfs add` 3846 3847 Default: `0` (no limit, because [`Import.UnixFSHAMTDirectorySizeThreshold`](#importunixfshamtdirectorysizethreshold) triggers controls when to switch to HAMT sharding when a directory grows too big) 3848 3849 Type: `optionalInteger` 3850 3851 ### `Import.UnixFSHAMTDirectoryMaxFanout` 3852 3853 The maximum number of children that a node part of a UnixFS HAMT directory 3854 (aka sharded directory) can have. 3855 3856 HAMT directories have unlimited children and are used when basic directories 3857 become too big or reach `MaxLinks`. A HAMT is a structure made of UnixFS 3858 nodes that store the list of elements in the folder. This option controls the 3859 maximum number of children that the HAMT nodes can have. 3860 3861 According to the [UnixFS specification](https://specs.ipfs.tech/unixfs/#hamt-structure-and-parameters), this value must be a power of 2, between 8 (for byte-aligned bitfields) and 1024 (to prevent denial-of-service attacks). 3862 3863 Commands affected: `ipfs add`, `ipfs daemon` (globally overrides [`boxo/ipld/unixfs/io.DefaultShardWidth`](https://github.com/ipfs/boxo/blob/6c5a07602aed248acc86598f30ab61923a54a83e/ipld/unixfs/io/directory.go#L30C5-L30C22)) 3864 3865 Default: `256` 3866 3867 Type: `optionalInteger` 3868 3869 ### `Import.UnixFSHAMTDirectorySizeThreshold` 3870 3871 The sharding threshold to decide whether a basic UnixFS directory 3872 should be sharded (converted into HAMT Directory) or not. 3873 3874 This value is not strictly related to the size of the UnixFS directory block 3875 and any increases in the threshold should come with being careful that block 3876 sizes stay under 2MiB in order for them to be reliably transferable through the 3877 networking stack. At the time of writing this, IPFS peers on the public swarm 3878 tend to ignore requests for blocks bigger than 2MiB. 3879 3880 Uses implementation from `boxo/ipld/unixfs/io/directory`, where the size is not 3881 the _exact_ block size of the encoded directory but just the estimated size 3882 based byte length of DAG-PB Links names and CIDs. 3883 3884 Setting to `1B` is functionally equivalent to always using HAMT (useful in testing). 3885 3886 Commands affected: `ipfs add`, `ipfs daemon` (globally overrides [`boxo/ipld/unixfs/io.HAMTShardingSize`](https://github.com/ipfs/boxo/blob/6c5a07602aed248acc86598f30ab61923a54a83e/ipld/unixfs/io/directory.go#L26)) 3887 3888 Default: `256KiB` (may change, inspect `DefaultUnixFSHAMTDirectorySizeThreshold` to confirm) 3889 3890 Type: [`optionalBytes`](#optionalbytes) 3891 3892 ### `Import.UnixFSHAMTDirectorySizeEstimation` 3893 3894 Controls how directory size is estimated when deciding whether to switch 3895 from a basic UnixFS directory to HAMT sharding. 3896 3897 Accepted values: 3898 3899 - `links` (default): Legacy estimation using sum of link names and CID byte lengths. 3900 - `block`: Full serialized dag-pb block size for accurate threshold decisions. 3901 - `disabled`: Disable HAMT sharding entirely (directories always remain basic). 3902 3903 The `block` estimation is recommended for new profiles as it provides more 3904 accurate threshold decisions and better cross-implementation consistency. 3905 See [IPIP-499](https://specs.ipfs.tech/ipips/ipip-0499/) for more details. 3906 3907 Commands affected: `ipfs add` 3908 3909 Default: `links` 3910 3911 Type: `optionalString` 3912 3913 ### `Import.UnixFSDAGLayout` 3914 3915 Controls the DAG layout used when chunking files. 3916 3917 Accepted values: 3918 3919 - `balanced` (default): Balanced DAG layout with uniform leaf depth. 3920 - `trickle`: Trickle DAG layout optimized for streaming. 3921 3922 Commands affected: `ipfs add` 3923 3924 Default: `balanced` 3925 3926 Type: `optionalString` 3927 3928 ## `Version` 3929 3930 Options to configure agent version announced to the swarm, and leveraging 3931 other peers version for detecting when there is time to update. 3932 3933 ### `Version.AgentSuffix` 3934 3935 Optional suffix to the AgentVersion presented by `ipfs id` and exposed via [libp2p identify protocol](https://github.com/libp2p/specs/blob/master/identify/README.md#agentversion). 3936 3937 The value from config takes precedence over value passed via `ipfs daemon --agent-version-suffix`. 3938 3939 > [!NOTE] 3940 > Setting a custom version suffix helps with ecosystem analysis, such as Amino DHT reports published at <https://stats.ipfs.network> 3941 3942 Default: `""` (no suffix, or value from `ipfs daemon --agent-version-suffix=`) 3943 3944 Type: `optionalString` 3945 3946 ### `Version.SwarmCheckEnabled` 3947 3948 Observe the AgentVersion of swarm peers and log warning when 3949 `SwarmCheckPercentThreshold` of peers runs version higher than this node. 3950 3951 Default: `true` 3952 3953 Type: `flag` 3954 3955 ### `Version.SwarmCheckPercentThreshold` 3956 3957 Control the percentage of `kubo/` peers running new version required to 3958 trigger update warning. 3959 3960 Default: `5` 3961 3962 Type: `optionalInteger` (1-100) 3963 3964 ## Profiles 3965 3966 Configuration profiles allow to tweak configuration quickly. Profiles can be 3967 applied with the `--profile` flag to `ipfs init` or with the `ipfs config profile 3968 apply` command. When a profile is applied a backup of the configuration file 3969 will be created in `$IPFS_PATH`. 3970 3971 Configuration profiles can be applied additively. For example, both the `unixfs-v1-2025` and `lowpower` profiles can be applied one after the other. 3972 The available configuration profiles are listed below. You can also find them 3973 documented in `ipfs config profile --help`. 3974 3975 ### `server` profile 3976 3977 Disables local [`Discovery.MDNS`](#discoverymdns), [turns off uPnP NAT port mapping](#swarmdisablenatportmap), and blocks connections to 3978 IPv4 and IPv6 prefixes that are [private, local only, or unrouteable](https://github.com/ipfs/kubo/blob/b71cf0d15904bdef21fe2eee5f1118a274309a4d/config/profile.go#L24-L43). 3979 3980 Recommended when running IPFS on machines with public IPv4 addresses (no NAT, no uPnP) 3981 at providers that interpret local IPFS discovery and traffic as netscan abuse ([example](https://github.com/ipfs/kubo/issues/10327)). 3982 3983 ### `randomports` profile 3984 3985 Use a random port number for the incoming swarm connections. 3986 Used for testing. 3987 3988 ### `default-datastore` profile 3989 3990 Configures the node to use the default datastore (flatfs). 3991 3992 Read the "flatfs" profile description for more information on this datastore. 3993 3994 This profile may only be applied when first initializing the node. 3995 3996 ### `local-discovery` profile 3997 3998 Enables local [`Discovery.MDNS`](#discoverymdns) (enabled by default). 3999 4000 Useful to re-enable local discovery after it's disabled by another profile 4001 (e.g., the server profile). 4002 4003 `test` profile 4004 4005 Reduces external interference of IPFS daemon, this 4006 is useful when using the daemon in test environments. 4007 4008 ### `default-networking` profile 4009 4010 Restores default network settings. 4011 Inverse profile of the test profile. 4012 4013 ### `autoconf-on` profile 4014 4015 Safe default for joining the public IPFS Mainnet swarm with automatic configuration. 4016 Can also be used with custom AutoConf.URL for other networks. 4017 4018 ### `autoconf-off` profile 4019 4020 Disables AutoConf and clears all networking fields for manual configuration. 4021 Use this for private networks or when you want explicit control over all endpoints. 4022 4023 ### `flatfs` profile 4024 4025 Configures the node to use the flatfs datastore. 4026 Flatfs is the default, most battle-tested and reliable datastore. 4027 4028 You should use this datastore if: 4029 4030 - You need a very simple and very reliable datastore, and you trust your 4031 filesystem. This datastore stores each block as a separate file in the 4032 underlying filesystem so it's unlikely to lose data unless there's an issue 4033 with the underlying file system. 4034 - You need to run garbage collection in a way that reclaims free space as soon as possible. 4035 - You want to minimize memory usage. 4036 - You are ok with the default speed of data import, or prefer to use `--nocopy`. 4037 4038 > [!WARNING] 4039 > This profile may only be applied when first initializing the node via `ipfs init --profile flatfs` 4040 4041 > [!NOTE] 4042 > See caveats and configuration options at [`datastores.md#flatfs`](datastores.md#flatfs) 4043 4044 ### `flatfs-measure` profile 4045 4046 Configures the node to use the flatfs datastore with metrics. This is the same as [`flatfs` profile](#flatfs-profile) with the addition of the `measure` datastore wrapper. 4047 4048 ### `pebbleds` profile 4049 4050 Configures the node to use the pebble high-performance datastore. 4051 4052 Pebble is a LevelDB/RocksDB inspired key-value store focused on performance and internal usage by CockroachDB. 4053 You should use this datastore if: 4054 4055 - You need a datastore that is focused on performance. 4056 - You need a datastore that is good for multi-terabyte data sets. 4057 - You need reliability by default, but may choose to disable WAL for maximum performance when reliability is not critical. 4058 - You want a datastore that does not need GC cycles and does not use more space than necessary 4059 - You want a datastore that does not take several minutes to start with large repositories 4060 - You want a datastore that performs well even with default settings, but can optimized by setting configuration to tune it for your specific needs. 4061 4062 > [!WARNING] 4063 > This profile may only be applied when first initializing the node via `ipfs init --profile pebbleds` 4064 4065 > [!NOTE] 4066 > See other caveats and configuration options at [`datastores.md#pebbleds`](datastores.md#pebbleds) 4067 4068 ### `pebbleds-measure` profile 4069 4070 Configures the node to use the pebble datastore with metrics. This is the same as [`pebbleds` profile](#pebble-profile) with the addition of the `measure` datastore wrapper. 4071 4072 ### `badgerds` profile 4073 4074 Configures the node to use the **legacy** badgerv1 datastore. 4075 4076 > [!CAUTION] 4077 > **Badger v1 datastore is deprecated and will be removed in a future Kubo release.** 4078 > 4079 > This is based on very old badger 1.x, which has not been maintained by its 4080 > upstream maintainers for years and has known bugs (startup timeouts, shutdown 4081 > hangs, file descriptor 4082 > exhaustion, and more). Do not use it for new deployments. 4083 > 4084 > **To migrate:** create a new `IPFS_PATH` with `flatfs` 4085 > (`ipfs init --profile=flatfs`), move pinned data via 4086 > `ipfs dag export/import` or `ipfs pin ls -t recursive|add`, and decommission the 4087 > old badger-based node. When it comes to block storage, use experimental 4088 > `pebbleds` only if you are sure modern `flatfs` does not serve your use case 4089 > (most users will be perfectly fine with `flatfs`, it is also possible to keep 4090 > `flatfs` for blocks and replace `leveldb` with `pebble` if preferred over 4091 > `leveldb`). 4092 4093 Also, be aware that: 4094 4095 - This datastore will not properly reclaim space when your datastore is 4096 smaller than several gigabytes. If you run IPFS with `--enable-gc`, you plan on storing very little data in 4097 your IPFS node, and disk usage is more critical than performance, consider using 4098 `flatfs`. 4099 - This datastore uses up to several gigabytes of memory. 4100 - Good for medium-size datastores, but may run into performance issues if your dataset is bigger than a terabyte. 4101 4102 > [!WARNING] 4103 > This profile may only be applied when first initializing the node via `ipfs init --profile badgerds` 4104 4105 > [!NOTE] 4106 > See other caveats and configuration options at [`datastores.md#badgerds`](datastores.md#badgerds) 4107 4108 ### `badgerds-measure` profile 4109 4110 Configures the node to use the **legacy** badgerv1 datastore with metrics. This is the same as [`badgerds` profile](#badger-profile) with the addition of the `measure` datastore wrapper. This profile will be removed in a future Kubo release. 4111 4112 ### `lowpower` profile 4113 4114 Reduces daemon overhead on the system by disabling optional swarm services. 4115 4116 - [`Routing.Type`](#routingtype) set to `autoclient` (no DHT server, only client). 4117 - `Swarm.ConnMgr` set to maintain minimum number of p2p connections at a time. 4118 - Disables [`AutoNAT`](#autonat). 4119 - Disables [`Swam.RelayService`](#swarmrelayservice). 4120 4121 > [!NOTE] 4122 > This profile is provided for legacy reasons. 4123 > With modern Kubo setting the above should not be necessary. 4124 4125 ### `announce-off` profile 4126 4127 Disables [Provide](#provide) system (and announcing to Amino DHT). 4128 4129 > [!CAUTION] 4130 > The main use case for this is setups with manual Peering.Peers config. 4131 > Data from this node will not be announced on the DHT. This will make 4132 > DHT-based routing an data retrieval impossible if this node is the only 4133 > one hosting it, and other peers are not already connected to it. 4134 4135 ### `announce-on` profile 4136 4137 (Re-)enables [Provide](#provide) system (reverts [`announce-off` profile](#announce-off-profile)). 4138 4139 ### `unixfs-v0-2015` profile 4140 4141 Legacy UnixFS import profile for backward-compatible CID generation. 4142 Produces CIDv0 with no raw leaves, sha2-256, 256 KiB chunks, and 4143 link-based HAMT size estimation. 4144 4145 See <https://github.com/ipfs/kubo/blob/master/config/profile.go> for exact [`Import.*`](#import) settings. 4146 4147 > [!NOTE] 4148 > Use only when legacy CIDs are required. For new projects, use [`unixfs-v1-2025`](#unixfs-v1-2025-profile). 4149 > 4150 > See [IPIP-499](https://specs.ipfs.tech/ipips/ipip-0499/) for more details. 4151 4152 ### `legacy-cid-v0` profile 4153 4154 Alias for [`unixfs-v0-2015`](#unixfs-v0-2015-profile) profile. 4155 4156 ### `unixfs-v1-2025` profile 4157 4158 Recommended UnixFS import profile for cross-implementation CID determinism. 4159 Uses CIDv1, raw leaves, sha2-256, 1 MiB chunks, 1024 links per file node, 4160 256 HAMT fanout, and block-based size estimation for HAMT threshold. 4161 4162 See <https://github.com/ipfs/kubo/blob/master/config/profile.go> for exact [`Import.*`](#import) settings. 4163 4164 > [!NOTE] 4165 > This profile ensures CID consistency across different IPFS implementations. 4166 > 4167 > See [IPIP-499](https://specs.ipfs.tech/ipips/ipip-0499/) for more details. 4168 4169 ## Security 4170 4171 This section provides an overview of security considerations for configurations that expose network services. 4172 4173 ### Port and Network Exposure 4174 4175 Several configuration options expose TCP or UDP ports that can make your Kubo node accessible from the network: 4176 4177 - **[`Addresses.API`](#addressesapi)** - Exposes the admin RPC API (default: localhost:5001) 4178 - **[`Addresses.Gateway`](#addressesgateway)** - Exposes the HTTP gateway (default: localhost:8080) 4179 - **[`Addresses.Swarm`](#addressesswarm)** - Exposes P2P connectivity (default: 0.0.0.0:4001, both UDP and TCP) 4180 - **[`Swarm.Transports.Network`](#swarmtransportsnetwork)** - Controls which P2P transport protocols are enabled over TCP and UDP 4181 4182 ### Security Best Practices 4183 4184 - Keep admin services ([`Addresses.API`](#addressesapi)) bound to localhost unless authentication ([`API.Authorizations`](#apiauthorizations)) is configured 4185 - Use [`Gateway.NoFetch`](#gatewaynofetch) to prevent arbitrary CID retrieval if Kubo is acting as a public gateway available to anyone 4186 - Configure firewall rules to restrict access to exposed ports. Note that [`Addresses.Swarm`](#addressesswarm) is special - all incoming traffic to swarm ports should be allowed to ensure proper P2P connectivity 4187 - Control which public-facing addresses are announced to other peers using [`Addresses.NoAnnounce`](#addressesnoannounce), [`Addresses.Announce`](#addressesannounce), and [`Addresses.AppendAnnounce`](#addressesappendannounce) 4188 - Consider using the [`server` profile](#server-profile) for production deployments 4189 4190 ## Types 4191 4192 This document refers to the standard JSON types (e.g., `null`, `string`, 4193 `number`, etc.), as well as a few custom types, described below. 4194 4195 ### `flag` 4196 4197 Flags allow enabling and disabling features. However, unlike simple booleans, 4198 they can also be `null` (or omitted) to indicate that the default value should 4199 be chosen. This makes it easier for Kubo to change the defaults in the 4200 future unless the user _explicitly_ sets the flag to either `true` (enabled) or 4201 `false` (disabled). Flags have three possible states: 4202 4203 - `null` or missing (apply the default value). 4204 - `true` (enabled) 4205 - `false` (disabled) 4206 4207 ### `priority` 4208 4209 Priorities allow specifying the priority of a feature/protocol and disabling the 4210 feature/protocol. Priorities can take one of the following values: 4211 4212 - `null`/missing (apply the default priority, same as with flags) 4213 - `false` (disabled) 4214 - `1 - 2^63` (priority, lower is preferred) 4215 4216 ### `strings` 4217 4218 Strings is a special type for conveniently specifying a single string, an array 4219 of strings, or null: 4220 4221 - `null` 4222 - `"a single string"` 4223 - `["an", "array", "of", "strings"]` 4224 4225 ### `duration` 4226 4227 Duration is a type for describing lengths of time, using the same format go 4228 does (e.g, `"1d2h4m40.01s"`). 4229 4230 ### `optionalInteger` 4231 4232 Optional integers allow specifying some numerical value which has 4233 an implicit default when missing from the config file: 4234 4235 - `null`/missing will apply the default value defined in Kubo sources (`.WithDefault(value)`) 4236 - an integer between `-2^63` and `2^63-1` (i.e. `-9223372036854775808` to `9223372036854775807`) 4237 4238 ### `optionalBytes` 4239 4240 Optional Bytes allow specifying some number of bytes which has 4241 an implicit default when missing from the config file: 4242 4243 - `null`/missing (apply the default value defined in Kubo sources) 4244 - a string value indicating the number of bytes, including human readable representations: 4245 - [SI sizes](https://en.wikipedia.org/wiki/Metric_prefix#List_of_SI_prefixes) (metric units, powers of 1000), e.g. `1B`, `2kB`, `3MB`, `4GB`, `5TB`, …) 4246 - [IEC sizes](https://en.wikipedia.org/wiki/Binary_prefix#IEC_prefixes) (binary units, powers of 1024), e.g. `1B`, `2KiB`, `3MiB`, `4GiB`, `5TiB`, …) 4247 - a raw number (will be interpreted as bytes, e.g. `1048576` for 1MiB) 4248 4249 ### `optionalString` 4250 4251 Optional strings allow specifying some string value which has 4252 an implicit default when missing from the config file: 4253 4254 - `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("value")`) 4255 - a string 4256 4257 ### `optionalDuration` 4258 4259 Optional durations allow specifying some duration value which has 4260 an implicit default when missing from the config file: 4261 4262 - `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("1h2m3s")`) 4263 - a string with a valid [go duration](#duration) (e.g, `"1d2h4m40.01s"`). 4264 4265 ---- 4266 4267 [multiaddr]: https://docs.ipfs.tech/concepts/glossary/#multiaddr