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