diff --git a/docs/config.md b/docs/config.md index 8d71dccab75..5989834a987 100644 --- a/docs/config.md +++ b/docs/config.md @@ -5,6 +5,130 @@ is read once at node instantiation, either for an offline command, or when starting the daemon. Commands that execute on a running daemon do not read the config file at runtime. +## Table of Contents + +- [The go-ipfs config file](#the-go-ipfs-config-file) + - [Table of Contents](#table-of-contents) + - [Profiles](#profiles) + - [Types](#types) + - [`flag`](#flag) + - [`priority`](#priority) + - [`strings`](#strings) + - [`duration`](#duration) + - [`optionalInteger`](#optionalinteger) + - [`Addresses`](#addresses) + - [`Addresses.API`](#addressesapi) + - [`Addresses.Gateway`](#addressesgateway) + - [`Addresses.Swarm`](#addressesswarm) + - [`Addresses.Announce`](#addressesannounce) + - [`Addresses.NoAnnounce`](#addressesnoannounce) + - [`API`](#api) + - [`API.HTTPHeaders`](#apihttpheaders) + - [`AutoNAT`](#autonat) + - [`AutoNAT.ServiceMode`](#autonatservicemode) + - [`AutoNAT.Throttle`](#autonatthrottle) + - [`AutoNAT.Throttle.GlobalLimit`](#autonatthrottlegloballimit) + - [`AutoNAT.Throttle.PeerLimit`](#autonatthrottlepeerlimit) + - [`AutoNAT.Throttle.Interval`](#autonatthrottleinterval) + - [`Bootstrap`](#bootstrap) + - [`Datastore`](#datastore) + - [`Datastore.StorageMax`](#datastorestoragemax) + - [`Datastore.StorageGCWatermark`](#datastorestoragegcwatermark) + - [`Datastore.GCPeriod`](#datastoregcperiod) + - [`Datastore.HashOnRead`](#datastorehashonread) + - [`Datastore.BloomFilterSize`](#datastorebloomfiltersize) + - [`Datastore.Spec`](#datastorespec) + - [`Discovery`](#discovery) + - [`Discovery.MDNS`](#discoverymdns) + - [`Discovery.MDNS.Enabled`](#discoverymdnsenabled) + - [`Discovery.MDNS.Interval`](#discoverymdnsinterval) + - [`Gateway`](#gateway) + - [`Gateway.NoFetch`](#gatewaynofetch) + - [`Gateway.NoDNSLink`](#gatewaynodnslink) + - [`Gateway.HTTPHeaders`](#gatewayhttpheaders) + - [`Gateway.RootRedirect`](#gatewayrootredirect) + - [`Gateway.Writable`](#gatewaywritable) + - [`Gateway.PathPrefixes`](#gatewaypathprefixes) + - [`Gateway.PublicGateways`](#gatewaypublicgateways) + - [`Gateway.PublicGateways: Paths`](#gatewaypublicgateways-paths) + - [`Gateway.PublicGateways: UseSubdomains`](#gatewaypublicgateways-usesubdomains) + - [`Gateway.PublicGateways: NoDNSLink`](#gatewaypublicgateways-nodnslink) + - [Implicit defaults of `Gateway.PublicGateways`](#implicit-defaults-of-gatewaypublicgateways) + - [`Gateway` recipes](#gateway-recipes) + - [`Identity`](#identity) + - [`Identity.PeerID`](#identitypeerid) + - [`Identity.PrivKey`](#identityprivkey) + - [`Internal`](#internal) + - [`Internal.Bitswap`](#internalbitswap) + - [`Internal.Bitswap.TaskWorkerCount`](#internalbitswaptaskworkercount) + - [`Internal.Bitswap.EngineBlockstoreWorkerCount`](#internalbitswapengineblockstoreworkercount) + - [`Internal.Bitswap.EngineTaskWorkerCount`](#internalbitswapenginetaskworkercount) + - [`Internal.Bitswap.MaxOutstandingBytesPerPeer`](#internalbitswapmaxoutstandingbytesperpeer) + - [`Ipns`](#ipns) + - [`Ipns.RepublishPeriod`](#ipnsrepublishperiod) + - [`Ipns.RecordLifetime`](#ipnsrecordlifetime) + - [`Ipns.ResolveCacheSize`](#ipnsresolvecachesize) + - [`Migration`](#migration) + - [`Migration.DownloadSources`](#migrationdownloadsources) + - [`Migration.Keep`](#migrationkeep) + - [`Mounts`](#mounts) + - [`Mounts.IPFS`](#mountsipfs) + - [`Mounts.IPNS`](#mountsipns) + - [`Mounts.FuseAllowOther`](#mountsfuseallowother) + - [`Pinning`](#pinning) + - [`Pinning.RemoteServices`](#pinningremoteservices) + - [`Pinning.RemoteServices: API`](#pinningremoteservices-api) + - [`Pinning.RemoteServices: API.Endpoint`](#pinningremoteservices-apiendpoint) + - [`Pinning.RemoteServices: API.Key`](#pinningremoteservices-apikey) + - [`Pinning.RemoteServices: Policies`](#pinningremoteservices-policies) + - [`Pinning.RemoteServices: Policies.MFS`](#pinningremoteservices-policiesmfs) + - [`Pinning.RemoteServices: Policies.MFS.Enabled`](#pinningremoteservices-policiesmfsenabled) + - [`Pinning.RemoteServices: Policies.MFS.PinName`](#pinningremoteservices-policiesmfspinname) + - [`Pinning.RemoteServices: Policies.MFS.RepinInterval`](#pinningremoteservices-policiesmfsrepininterval) + - [`Pubsub`](#pubsub) + - [`Pubsub.Router`](#pubsubrouter) + - [`Pubsub.DisableSigning`](#pubsubdisablesigning) + - [`Peering`](#peering) + - [`Peering.Peers`](#peeringpeers) + - [`Reprovider`](#reprovider) + - [`Reprovider.Interval`](#reproviderinterval) + - [`Reprovider.Strategy`](#reproviderstrategy) + - [`Routing`](#routing) + - [`Routing.Type`](#routingtype) + - [`Swarm`](#swarm) + - [`Swarm.AddrFilters`](#swarmaddrfilters) + - [`Swarm.DisableBandwidthMetrics`](#swarmdisablebandwidthmetrics) + - [`Swarm.DisableNatPortMap`](#swarmdisablenatportmap) + - [`Swarm.DisableRelay`](#swarmdisablerelay) + - [`Swarm.EnableRelayHop`](#swarmenablerelayhop) + - [`Swarm.EnableAutoRelay`](#swarmenableautorelay) + - [Mode 1: `EnableRelayHop` is `false`](#mode-1-enablerelayhop-is-false) + - [Mode 2: `EnableRelayHop` is `true`](#mode-2-enablerelayhop-is-true) + - [`Swarm.EnableAutoNATService`](#swarmenableautonatservice) + - [`Swarm.ConnMgr`](#swarmconnmgr) + - [`Swarm.ConnMgr.Type`](#swarmconnmgrtype) + - [Basic Connection Manager](#basic-connection-manager) + - [`Swarm.ConnMgr.LowWater`](#swarmconnmgrlowwater) + - [`Swarm.ConnMgr.HighWater`](#swarmconnmgrhighwater) + - [`Swarm.ConnMgr.GracePeriod`](#swarmconnmgrgraceperiod) + - [`Swarm.Transports`](#swarmtransports) + - [`Swarm.Transports.Network`](#swarmtransportsnetwork) + - [`Swarm.Transports.Network.TCP`](#swarmtransportsnetworktcp) + - [`Swarm.Transports.Network.Websocket`](#swarmtransportsnetworkwebsocket) + - [`Swarm.Transports.Network.QUIC`](#swarmtransportsnetworkquic) + - [`Swarm.Transports.Network.Relay`](#swarmtransportsnetworkrelay) + - [`Swarm.Transports.Security`](#swarmtransportssecurity) + - [`Swarm.Transports.Security.TLS`](#swarmtransportssecuritytls) + - [`Swarm.Transports.Security.SECIO`](#swarmtransportssecuritysecio) + - [`Swarm.Transports.Security.Noise`](#swarmtransportssecuritynoise) + - [`Swarm.Transports.Multiplexers`](#swarmtransportsmultiplexers) + - [`Swarm.Transports.Multiplexers.Yamux`](#swarmtransportsmultiplexersyamux) + - [`Swarm.Transports.Multiplexers.Mplex`](#swarmtransportsmultiplexersmplex) + - [`DNS`](#dns) + - [`DNS.Resolvers`](#dnsresolvers) + + + ## Profiles Configuration profiles allow to tweak configuration quickly. Profiles can be @@ -129,126 +253,13 @@ of strings, or null: Duration is a type for describing lengths of time, using the same format go does (e.g, `"1d2h4m40.01s"`). -## Table of Contents +### `optionalInteger` -- [The go-ipfs config file](#the-go-ipfs-config-file) - - [Profiles](#profiles) - - [Types](#types) - - [`flag`](#flag) - - [`priority`](#priority) - - [`strings`](#strings) - - [`duration`](#duration) - - [Table of Contents](#table-of-contents) - - [`Addresses`](#addresses) - - [`Addresses.API`](#addressesapi) - - [`Addresses.Gateway`](#addressesgateway) - - [`Addresses.Swarm`](#addressesswarm) - - [`Addresses.Announce`](#addressesannounce) - - [`Addresses.NoAnnounce`](#addressesnoannounce) - - [`API`](#api) - - [`API.HTTPHeaders`](#apihttpheaders) - - [`AutoNAT`](#autonat) - - [`AutoNAT.ServiceMode`](#autonatservicemode) - - [`AutoNAT.Throttle`](#autonatthrottle) - - [`AutoNAT.Throttle.GlobalLimit`](#autonatthrottlegloballimit) - - [`AutoNAT.Throttle.PeerLimit`](#autonatthrottlepeerlimit) - - [`AutoNAT.Throttle.Interval`](#autonatthrottleinterval) - - [`Bootstrap`](#bootstrap) - - [`Datastore`](#datastore) - - [`Datastore.StorageMax`](#datastorestoragemax) - - [`Datastore.StorageGCWatermark`](#datastorestoragegcwatermark) - - [`Datastore.GCPeriod`](#datastoregcperiod) - - [`Datastore.HashOnRead`](#datastorehashonread) - - [`Datastore.BloomFilterSize`](#datastorebloomfiltersize) - - [`Datastore.Spec`](#datastorespec) - - [`Discovery`](#discovery) - - [`Discovery.MDNS`](#discoverymdns) - - [`Discovery.MDNS.Enabled`](#discoverymdnsenabled) - - [`Discovery.MDNS.Interval`](#discoverymdnsinterval) - - [`Gateway`](#gateway) - - [`Gateway.NoFetch`](#gatewaynofetch) - - [`Gateway.NoDNSLink`](#gatewaynodnslink) - - [`Gateway.HTTPHeaders`](#gatewayhttpheaders) - - [`Gateway.RootRedirect`](#gatewayrootredirect) - - [`Gateway.Writable`](#gatewaywritable) - - [`Gateway.PathPrefixes`](#gatewaypathprefixes) - - [`Gateway.PublicGateways`](#gatewaypublicgateways) - - [`Gateway.PublicGateways: Paths`](#gatewaypublicgateways-paths) - - [`Gateway.PublicGateways: UseSubdomains`](#gatewaypublicgateways-usesubdomains) - - [`Gateway.PublicGateways: NoDNSLink`](#gatewaypublicgateways-nodnslink) - - [Implicit defaults of `Gateway.PublicGateways`](#implicit-defaults-of-gatewaypublicgateways) - - [`Gateway` recipes](#gateway-recipes) - - [`Identity`](#identity) - - [`Identity.PeerID`](#identitypeerid) - - [`Identity.PrivKey`](#identityprivkey) - - [`Internal`](#internal) - - [`Internal.Bitswap`](#internalbitswap) - - [`Internal.Bitswap.TaskWorkerCount`](#internalbitswaptaskworkercount) - - [`Internal.Bitswap.EngineBlockstoreWorkerCount`](#internalbitswapengineblockstoreworkercount) - - [`Internal.Bitswap.EngineTaskWorkerCount`](#internalbitswapenginetaskworkercount) - - [`Internal.Bitswap.MaxOutstandingBytesPerPeer`](#internalbitswapmaxoutstandingbytesperpeer) - - [`Ipns`](#ipns) - - [`Ipns.RepublishPeriod`](#ipnsrepublishperiod) - - [`Ipns.RecordLifetime`](#ipnsrecordlifetime) - - [`Ipns.ResolveCacheSize`](#ipnsresolvecachesize) - - [`Migration`](#migration) - - [`Migration.DownloadSources`](#migrationdownloadsources) - - [`Migration.Keep`](#migrationkeep) - - [`Mounts`](#mounts) - - [`Mounts.IPFS`](#mountsipfs) - - [`Mounts.IPNS`](#mountsipns) - - [`Mounts.FuseAllowOther`](#mountsfuseallowother) - - [`Pinning`](#pinning) - - [`Pinning.RemoteServices`](#pinningremoteservices) - - [`Pinning.RemoteServices: API`](#pinningremoteservices-api) - - [`Pinning.RemoteServices: API.Endpoint`](#pinningremoteservices-apiendpoint) - - [`Pinning.RemoteServices: API.Key`](#pinningremoteservices-apikey) - - [`Pinning.RemoteServices: Policies`](#pinningremoteservices-policies) - - [`Pinning.RemoteServices: Policies.MFS`](#pinningremoteservices-policiesmfs) - - [`Pinning.RemoteServices: Policies.MFS.Enabled`](#pinningremoteservices-policiesmfsenabled) - - [`Pinning.RemoteServices: Policies.MFS.PinName`](#pinningremoteservices-policiesmfspinname) - - [`Pinning.RemoteServices: Policies.MFS.RepinInterval`](#pinningremoteservices-policiesmfsrepininterval) - - [`Pubsub`](#pubsub) - - [`Pubsub.Router`](#pubsubrouter) - - [`Pubsub.DisableSigning`](#pubsubdisablesigning) - - [`Peering`](#peering) - - [`Peering.Peers`](#peeringpeers) - - [`Reprovider`](#reprovider) - - [`Reprovider.Interval`](#reproviderinterval) - - [`Reprovider.Strategy`](#reproviderstrategy) - - [`Routing`](#routing) - - [`Routing.Type`](#routingtype) - - [`Swarm`](#swarm) - - [`Swarm.AddrFilters`](#swarmaddrfilters) - - [`Swarm.DisableBandwidthMetrics`](#swarmdisablebandwidthmetrics) - - [`Swarm.DisableNatPortMap`](#swarmdisablenatportmap) - - [`Swarm.DisableRelay`](#swarmdisablerelay) - - [`Swarm.EnableRelayHop`](#swarmenablerelayhop) - - [`Swarm.EnableAutoRelay`](#swarmenableautorelay) - - [Mode 1: `EnableRelayHop` is `false`](#mode-1-enablerelayhop-is-false) - - [Mode 2: `EnableRelayHop` is `true`](#mode-2-enablerelayhop-is-true) - - [`Swarm.EnableAutoNATService`](#swarmenableautonatservice) - - [`Swarm.ConnMgr`](#swarmconnmgr) - - [`Swarm.ConnMgr.Type`](#swarmconnmgrtype) - - [Basic Connection Manager](#basic-connection-manager) - - [`Swarm.ConnMgr.LowWater`](#swarmconnmgrlowwater) - - [`Swarm.ConnMgr.HighWater`](#swarmconnmgrhighwater) - - [`Swarm.ConnMgr.GracePeriod`](#swarmconnmgrgraceperiod) - - [`Swarm.Transports`](#swarmtransports) - - [`Swarm.Transports.Network`](#swarmtransportsnetwork) - - [`Swarm.Transports.Network.TCP`](#swarmtransportsnetworktcp) - - [`Swarm.Transports.Network.Websocket`](#swarmtransportsnetworkwebsocket) - - [`Swarm.Transports.Network.QUIC`](#swarmtransportsnetworkquic) - - [`Swarm.Transports.Network.Relay`](#swarmtransportsnetworkrelay) - - [`Swarm.Transports.Security`](#swarmtransportssecurity) - - [`Swarm.Transports.Security.TLS`](#swarmtransportssecuritytls) - - [`Swarm.Transports.Security.SECIO`](#swarmtransportssecuritysecio) - - [`Swarm.Transports.Security.Noise`](#swarmtransportssecuritynoise) - - [`Swarm.Transports.Multiplexers`](#swarmtransportsmultiplexers) - - [`Swarm.Transports.Multiplexers.Yamux`](#swarmtransportsmultiplexersyamux) - - [`Swarm.Transports.Multiplexers.Mplex`](#swarmtransportsmultiplexersmplex) - - [`DNS`](#dns) - - [`DNS.Resolvers`](#dnsresolvers) +Optional Integers allow specifying some numerical value with have +an implicit default when `null` or missing from the config file: + +- `null`/missing (apply the default value defined in go-ipfs sources) +- an integer between `-9223372036854775808` (`1 - 2^63`) and `9223372036854775807` ## `Addresses` @@ -856,7 +867,7 @@ be hardware limitations like I/O or CPU. Number of threads sending outgoing messages. Used to thottle the number of concurrent send operations. -Type: `OptionalInteger` (thread count, `null` means default which is 8) +Type: `optionalInteger` (thread count, `null` means default which is 8) #### `Internal.Bitswap.EngineBlockstoreWorkerCount` @@ -865,14 +876,14 @@ Used to throttle the number of concurrent requests to the block store. The optimal value can be informed by the metrics `ipfs_bitswap_pending_block_tasks` and `ipfs_bitswap_active_block_tasks`. This would be a number that depends on your hardware (I/O and CPU). -Type: `OptionalInteger` (thread count, `null` means default which is 128) +Type: `optionalInteger` (thread count, `null` means default which is 128) #### `Internal.Bitswap.EngineTaskWorkerCount` Number of worker threads used for preparing and packaging responses before they are sent out. This number should generally be equal to `TaskWorkerCount`. -Type: `OptionalInteger` (thread count, `null` means default which is 8) +Type: `optionalInteger` (thread count, `null` means default which is 8) #### `Internal.Bitswap.MaxOutstandingBytesPerPeer` @@ -882,7 +893,7 @@ dedicated to peers who ask for more). Values below 250Kb could cause thrashing. Values above 10Mb open the potential for aggressively-wanting peers to consume all resources and deteriorate the quality provided to less aggressively-wanting peers. -Type: `OptionalInteger` (byte count, `null` means default which is 1MB) +Type: `optionalInteger` (byte count, `null` means default which is 1MB) ## `Ipns`