config

package
v0.33.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 20, 2024 License: Apache-2.0, MIT, Apache-2.0, + 1 more Imports: 20 Imported by: 66

Documentation

Overview

package config implements the ipfs config file datastructures and utilities.

Index

Constants

View Source 
const (
	APITag           = "API"
	AuthorizationTag = "Authorizations"
)
View Source 
const (
	DefaultAutoTLSEnabled       = false // experimental, opt-in for now (https://github.com/ipfs/kubo/pull/10521)
	DefaultDomainSuffix         = p2pforge.DefaultForgeDomain
	DefaultRegistrationEndpoint = p2pforge.DefaultForgeEndpoint
	DefaultCAEndpoint           = p2pforge.DefaultCAEndpoint
	DefaultAutoWSS              = true // requires AutoTLS.Enabled
)
View Source 
const (
	// DefaultPathName is the default config dir name.
	DefaultPathName = ".ipfs"
	// DefaultPathRoot is the path to the default config dir location.
	DefaultPathRoot = "~/" + DefaultPathName
	// DefaultConfigFile is the filename of the configuration file.
	DefaultConfigFile = "config"
	// EnvDir is the environment variable used to change the path root.
	EnvDir = "IPFS_PATH"
)
View Source 
const (
	// DefaultDataStoreDirectory is the directory to store all the local IPFS data.
	DefaultDataStoreDirectory = "datastore"

	// DefaultBlockKeyCacheSize is the size for the blockstore two-queue
	// cache which caches block keys and sizes.
	DefaultBlockKeyCacheSize = 64 << 10

	// DefaultWriteThrough specifies whether to use a "write-through"
	// Blockstore and Blockservice. This means that they will write
	// without performing any reads to check if the incoming blocks are
	// already present in the datastore. Enable for datastores with fast
	// writes and slower reads.
	DefaultWriteThrough bool = true
)
View Source 
const (
	DefaultInlineDNSLink         = false
	DefaultDeserializedResponses = true
	DefaultDisableHTMLErrors     = false
	DefaultExposeRoutingAPI      = false
)
View Source 
const (
	IdentityTag     = "Identity"
	PrivKeyTag      = "PrivKey"
	PrivKeySelector = IdentityTag + "." + PrivKeyTag
)
View Source 
const (
	DefaultCidVersion      = 0
	DefaultUnixFSRawLeaves = false
	DefaultUnixFSChunker   = "size-262144"
	DefaultHashFunction    = "sha2-256"

	// DefaultBatchMaxNodes controls the maximum number of nodes in a
	// write-batch. The total size of the batch is limited by
	// BatchMaxnodes and BatchMaxSize.
	DefaultBatchMaxNodes = 128
	// DefaultBatchMaxSize controls the maximum size of a single
	// write-batch. The total size of the batch is limited by
	// BatchMaxnodes and BatchMaxSize.
	DefaultBatchMaxSize = 100 << 20 // 20MiB
)
View Source 
const (
	// LastSeenMessagesStrategy is a strategy that calculates the TTL countdown
	// based on the last time a Pubsub message is seen. This means that if a message
	// is received and then seen again within the specified TTL window, it
	// won't be emitted until the TTL countdown expires from the last time the
	// message was seen.
	LastSeenMessagesStrategy = "last-seen"

	// FirstSeenMessagesStrategy is a strategy that calculates the TTL
	// countdown based on the first time a Pubsub message is seen. This means that if
	// a message is received and then seen again within the specified TTL
	// window, it won't be emitted.
	FirstSeenMessagesStrategy = "first-seen"

	// DefaultSeenMessagesStrategy is the strategy that is used by default if
	// no Pubsub.SeenMessagesStrategy is specified.
	DefaultSeenMessagesStrategy = LastSeenMessagesStrategy
)
View Source 
const (
	DefaultReproviderInterval = time.Hour * 22 // https://github.com/ipfs/kubo/pull/9326
	DefaultReproviderStrategy = "all"
)
View Source 
const (
	DefaultAcceleratedDHTClient      = false
	DefaultLoopbackAddressesOnLanDHT = false
)
View Source 
const (
	ResourceMgrSystemScope         = "system"
	ResourceMgrTransientScope      = "transient"
	ResourceMgrServiceScopePrefix  = "svc:"
	ResourceMgrProtocolScopePrefix = "proto:"
	ResourceMgrPeerScopePrefix     = "peer:"
)
View Source 
const DefaultConnMgrGracePeriod = time.Second * 20

DefaultConnMgrGracePeriod is the default value for the connection managers grace period.

View Source 
const DefaultConnMgrHighWater = 96

DefaultConnMgrHighWater is the default value for the connection managers 'high water' mark.

View Source 
const DefaultConnMgrLowWater = 32

DefaultConnMgrLowWater is the default value for the connection managers 'low water' mark.

View Source 
const DefaultConnMgrType = "basic"

DefaultConnMgrType is the default value for the connection managers type.

View Source 
const (
	DefaultIpnsMaxCacheTTL = time.Duration(math.MaxInt64)
)
View Source 
const DefaultMigrationKeep = "cache"
View Source 
const DefaultResourceMgrMinInboundConns = 800

DefaultResourceMgrMinInboundConns is a MAGIC number that probably a good enough number of inbound conns to be a good network citizen.

View Source 
const DefaultSwarmCheckPercentThreshold = 5

Variables

View Source 
var (
	RemoteServicesPath     = "Pinning.RemoteServices"
	PinningConcealSelector = []string{"Pinning", "RemoteServices", "*", "API", "Key"}
)
View Source 
var (
	// Default HTTP routers used in parallel to DHT when Routing.Type = "auto"
	DefaultHTTPRouters = getEnvOrDefault("IPFS_HTTP_ROUTERS", []string{
		"https://cid.contact",
	})

	// Default filter-protocols to pass along with delegated routing requests (as defined in IPIP-484)
	// and also filter out locally
	DefaultHTTPRoutersFilterProtocols = getEnvOrDefault("IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS", []string{
		"unknown",
		"transport-bitswap",
	})
)
View Source 
var DefaultBootstrapAddresses = []string{
	"/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
	"/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa",
	"/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb",
	"/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt",
	"/dnsaddr/va1.bootstrap.libp2p.io/p2p/12D3KooWKnDdG3iXw9eTFijk3EWSunZcFi54Zka4wmtqtt6rPxc8",
	"/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
	"/ip4/104.131.131.82/udp/4001/quic-v1/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
}

DefaultBootstrapAddresses are the hardcoded bootstrap addresses for IPFS. they are nodes run by the IPFS team. docs on these later. As with all p2p networks, bootstrap is an important security concern.

NOTE: This is here -- and not inside cmd/ipfs/init.go -- because of an import dependency issue. TODO: move this into a config/default/ package.

View Source 
var DefaultMigrationDownloadSources = []string{"HTTPS", "IPFS"}
View Source 
var ErrInvalidPeerAddr = errors.New("invalid peer address")

ErrInvalidPeerAddr signals an address is not a valid peer address.

View Source 
var MethodNameList = []MethodName{MethodNameProvide, MethodNameFindPeers, MethodNameFindProviders, MethodNameGetIPNS, MethodNamePutIPNS}
View Source 
var Profiles = map[string]Profile{
	"server": {
		Description: `Disables local host discovery, recommended when
running IPFS on machines with public IPv4 addresses.`,

		Transform: func(c *Config) error {
			c.Addresses.NoAnnounce = appendSingle(c.Addresses.NoAnnounce, defaultServerFilters)
			c.Swarm.AddrFilters = appendSingle(c.Swarm.AddrFilters, defaultServerFilters)
			c.Discovery.MDNS.Enabled = false
			c.Swarm.DisableNatPortMap = true
			return nil
		},
	},

	"local-discovery": {
		Description: `Sets default values to fields affected by the server
profile, enables discovery in local networks.`,

		Transform: func(c *Config) error {
			c.Addresses.NoAnnounce = deleteEntries(c.Addresses.NoAnnounce, defaultServerFilters)
			c.Swarm.AddrFilters = deleteEntries(c.Swarm.AddrFilters, defaultServerFilters)
			c.Discovery.MDNS.Enabled = true
			c.Swarm.DisableNatPortMap = false
			return nil
		},
	},
	"test": {
		Description: `Reduces external interference of IPFS daemon, this
is useful when using the daemon in test environments.`,

		Transform: func(c *Config) error {
			c.Addresses.API = Strings{"/ip4/127.0.0.1/tcp/0"}
			c.Addresses.Gateway = Strings{"/ip4/127.0.0.1/tcp/0"}
			c.Addresses.Swarm = []string{
				"/ip4/127.0.0.1/tcp/0",
			}

			c.Swarm.DisableNatPortMap = true
			c.Routing.LoopbackAddressesOnLanDHT = True

			c.Bootstrap = []string{}
			c.Discovery.MDNS.Enabled = false
			return nil
		},
	},
	"default-networking": {
		Description: `Restores default network settings.
Inverse profile of the test profile.`,

		Transform: func(c *Config) error {
			c.Addresses = addressesConfig()

			bootstrapPeers, err := DefaultBootstrapPeers()
			if err != nil {
				return err
			}
			c.Bootstrap = appendSingle(c.Bootstrap, BootstrapPeerStrings(bootstrapPeers))

			c.Swarm.DisableNatPortMap = false
			c.Discovery.MDNS.Enabled = true
			return nil
		},
	},
	"default-datastore": {
		Description: `Configures the node to use the default datastore (flatfs).

Read the "flatfs" profile description for more information on this datastore.

This profile may only be applied when first initializing the node.
`,

		InitOnly: true,
		Transform: func(c *Config) error {
			c.Datastore.Spec = flatfsSpec()
			return nil
		},
	},
	"flatfs": {
		Description: `Configures the node to use the flatfs datastore.

This is the most battle-tested and reliable datastore.
You should use this datastore if:

* You need a very simple and very reliable datastore, and you trust your
  filesystem. This datastore stores each block as a separate file in the
  underlying filesystem so it's unlikely to loose data unless there's an issue
  with the underlying file system.
* You need to run garbage collection in a way that reclaims free space as soon as possible.
* You want to minimize memory usage.
* You are ok with the default speed of data import, or prefer to use --nocopy.

See configuration documentation at:
https://github.com/ipfs/kubo/blob/master/docs/datastores.md#flatfs

NOTE: This profile may only be applied when first initializing node at IPFS_PATH
      via 'ipfs init --profile flatfs'
`,

		InitOnly: true,
		Transform: func(c *Config) error {
			c.Datastore.Spec = flatfsSpec()
			return nil
		},
	},
	"pebbleds": {
		Description: `Configures the node to use the pebble high-performance datastore.

Pebble is a LevelDB/RocksDB inspired key-value store focused on performance
and internal usage by CockroachDB.
You should use this datastore if:

- You need a datastore that is focused on performance.
- You need reliability by default, but may choose to disable WAL for maximum performance when reliability is not critical.
- This datastore is good for multi-terabyte data sets.
- May benefit from tuning depending on read/write patterns and throughput.
- Performance is helped significantly by running on a system with plenty of memory.

See configuration documentation at:
https://github.com/ipfs/kubo/blob/master/docs/datastores.md#pebbleds

NOTE: This profile may only be applied when first initializing node at IPFS_PATH
      via 'ipfs init --profile pebbleds'
`,

		InitOnly: true,
		Transform: func(c *Config) error {
			c.Datastore.Spec = pebbleSpec()
			return nil
		},
	},
	"badgerds": {
		Description: `Configures the node to use the legacy badgerv1 datastore.

NOTE: this is badger 1.x, which has known bugs and is no longer supported by the upstream team.
It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore.

Other caveats:

* This datastore will not properly reclaim space when your datastore is
  smaller than several gigabytes.  If you run IPFS with --enable-gc, you plan
  on storing very little data in your IPFS node, and disk usage is more
  critical than performance, consider using flatfs.
* This datastore uses up to several gigabytes of memory.
* Good for medium-size datastores, but may run into performance issues
  if your dataset is bigger than a terabyte.

See configuration documentation at:
https://github.com/ipfs/kubo/blob/master/docs/datastores.md#badgerds

NOTE: This profile may only be applied when first initializing node at IPFS_PATH
      via 'ipfs init --profile badgerds'
`,

		InitOnly: true,
		Transform: func(c *Config) error {
			c.Datastore.Spec = badgerSpec()
			return nil
		},
	},
	"lowpower": {
		Description: `Reduces daemon overhead on the system. May affect node
functionality - performance of content discovery and data
fetching may be degraded.
`,
		Transform: func(c *Config) error {

			c.Routing.Type = NewOptionalString("autoclient")
			c.AutoNAT.ServiceMode = AutoNATServiceDisabled
			c.Swarm.RelayService.Enabled = False

			lowWater := int64(20)
			highWater := int64(40)
			gracePeriod := time.Minute
			c.Swarm.ConnMgr.Type = NewOptionalString("basic")
			c.Swarm.ConnMgr.LowWater = &OptionalInteger{value: &lowWater}
			c.Swarm.ConnMgr.HighWater = &OptionalInteger{value: &highWater}
			c.Swarm.ConnMgr.GracePeriod = &OptionalDuration{&gracePeriod}
			return nil
		},
	},
	"announce-off": {
		Description: `Disables Reprovide system (and announcing to Amino DHT).

		USE WITH CAUTION:
		The main use case for this is setups with manual Peering.Peers config.
		Data from this node will not be announced on the DHT. This will make
		DHT-based routing an data retrieval impossible if this node is the only
		one hosting it, and other peers are not already connected to it.
`,
		Transform: func(c *Config) error {
			c.Reprovider.Interval = NewOptionalDuration(0)
			c.Experimental.StrategicProviding = true
			return nil
		},
	},
	"announce-on": {
		Description: `Re-enables Reprovide system (reverts announce-off profile).`,
		Transform: func(c *Config) error {
			c.Reprovider.Interval = NewOptionalDuration(DefaultReproviderInterval)
			c.Experimental.StrategicProviding = false
			return nil
		},
	},
	"randomports": {
		Description: `Use a random port number for swarm.`,

		Transform: func(c *Config) error {
			port, err := getAvailablePort()
			if err != nil {
				return err
			}
			c.Addresses.Swarm = []string{
				fmt.Sprintf("/ip4/0.0.0.0/tcp/%d", port),
				fmt.Sprintf("/ip6/::/tcp/%d", port),
			}
			return nil
		},
	},
	"legacy-cid-v0": {
		Description: `Makes UnixFS import produce legacy CIDv0 with no raw leaves, sha2-256 and 256 KiB chunks.`,

		Transform: func(c *Config) error {
			c.Import.CidVersion = *NewOptionalInteger(0)
			c.Import.UnixFSRawLeaves = False
			c.Import.UnixFSChunker = *NewOptionalString("size-262144")
			c.Import.HashFunction = *NewOptionalString("sha2-256")
			return nil
		},
	},
	"test-cid-v1": {
		Description: `Makes UnixFS import produce modern CIDv1 with raw leaves, sha2-256 and 1 MiB chunks.`,

		Transform: func(c *Config) error {
			c.Import.CidVersion = *NewOptionalInteger(1)
			c.Import.UnixFSRawLeaves = True
			c.Import.UnixFSChunker = *NewOptionalString("size-1048576")
			c.Import.HashFunction = *NewOptionalString("sha2-256")
			return nil
		},
	},
}

Profiles is a map holding configuration transformers. Docs are in docs/config.md.

Functions

func BootstrapPeerStrings 

func BootstrapPeerStrings(bps []peer.AddrInfo) []string

BootstrapPeerStrings formats a list of AddrInfos as a bootstrap peer list suitable for serialization.

func ConvertAuthSecret added in v0.25.0 

func ConvertAuthSecret(secret string) string

ConvertAuthSecret converts the given secret in the format "type:value" into an HTTP Authorization header value. It can handle 'bearer' and 'basic' as type. If type exists and is not known, an empty string is returned. If type does not exist, 'bearer' type is assumed.

func DataStorePath 

func DataStorePath(configroot string) (string, error)

DataStorePath returns the default data store path given a configuration root (set an empty string to have the default configuration root).

func DefaultBootstrapPeers 

func DefaultBootstrapPeers() ([]peer.AddrInfo, error)

DefaultBootstrapPeers returns the (parsed) set of default bootstrap peers. if it fails, it returns a meaningful error for the user. This is here (and not inside cmd/ipfs/init) because of module dependency problems.

func Filename 

func Filename(configroot, userConfigFile string) (string, error)

Filename returns the configuration file path given a configuration root directory and a user-provided configuration file path argument with the following rules:

  • If the user-provided configuration file path is empty, use the default one.
  • If the configuration root directory is empty, use the default one.
  • If the user-provided configuration file path is only a file name, use the configuration root directory, otherwise use only the user-provided path and ignore the configuration root.

func HumanOutput 

func HumanOutput(value interface{}) ([]byte, error)

HumanOutput gets a config value ready for printing.

func Marshal 

func Marshal(value interface{}) ([]byte, error)

Marshal configuration with JSON.

func ParseBootstrapPeers 

func ParseBootstrapPeers(addrs []string) ([]peer.AddrInfo, error)

ParseBootstrapPeer parses a bootstrap list into a list of AddrInfos.

func Path 

func Path(configroot, extension string) (string, error)

Path returns the path `extension` relative to the configuration root. If an empty string is provided for `configroot`, the default root is used.

func PathRoot 

func PathRoot() (string, error)

PathRoot returns the default configuration root directory.

func ToMap 

func ToMap(conf *Config) (map[string]interface{}, error)

Types

type API 

type API struct {
	// HTTPHeaders are the HTTP headers to return with the API.
	HTTPHeaders map[string][]string

	// Authorization is a map of authorizations used to authenticate in the API.
	// If the map is empty, then the RPC API is exposed to everyone. Check the
	// documentation for more details.
	Authorizations map[string]*RPCAuthScope `json:",omitempty"`
}

type Addresses 

type Addresses struct {
	Swarm          []string // addresses for the swarm to listen on
	Announce       []string // swarm addresses to announce to the network, if len > 0 replaces auto detected addresses
	AppendAnnounce []string // similar to Announce but doesn't overwrite auto detected addresses, they are just appended
	NoAnnounce     []string // swarm addresses not to announce to the network
	API            Strings  // address for the local API (RPC)
	Gateway        Strings  // address to listen on for IPFS HTTP object gateway
}

Addresses stores the (string) multiaddr addresses for the node.

type AutoNATConfig 

type AutoNATConfig struct {
	// ServiceMode configures the node's AutoNAT service mode.
	ServiceMode AutoNATServiceMode `json:",omitempty"`

	// Throttle configures AutoNAT dialback throttling.
	//
	// If unset, the conservative libp2p defaults will be unset. To help the
	// network, please consider setting this and increasing the limits.
	//
	// By default, the limits will be a total of 30 dialbacks, with a
	// per-peer max of 3 peer, resetting every minute.
	Throttle *AutoNATThrottleConfig `json:",omitempty"`
}

AutoNATConfig configures the node's AutoNAT subsystem.

type AutoNATServiceMode 

type AutoNATServiceMode int

AutoNATServiceMode configures the ipfs node's AutoNAT service. 

const (
	// AutoNATServiceUnset indicates that the user has not set the
	// AutoNATService mode.
	//
	// When unset, nodes configured to be public DHT nodes will _also_
	// perform limited AutoNAT dialbacks.
	AutoNATServiceUnset AutoNATServiceMode = iota
	// AutoNATServiceEnabled indicates that the user has enabled the
	// AutoNATService.
	AutoNATServiceEnabled
	// AutoNATServiceDisabled indicates that the user has disabled the
	// AutoNATService.
	AutoNATServiceDisabled
	// AutoNATServiceEnabledV1Only forces use of V1 and disables V2
	// (used for testing)
	AutoNATServiceEnabledV1Only
)

func (AutoNATServiceMode) MarshalText 

func (m AutoNATServiceMode) MarshalText() ([]byte, error)

func (*AutoNATServiceMode) UnmarshalText 

func (m *AutoNATServiceMode) UnmarshalText(text []byte) error

type AutoNATThrottleConfig 

type AutoNATThrottleConfig struct {
	// GlobalLimit and PeerLimit sets the global and per-peer dialback
	// limits. The AutoNAT service will only perform the specified number of
	// dialbacks per interval.
	//
	// Setting either to 0 will disable the appropriate limit.
	GlobalLimit, PeerLimit int

	// Interval specifies how frequently this node should reset the
	// global/peer dialback limits.
	//
	// When unset, this defaults to 1 minute.
	Interval OptionalDuration `json:",omitempty"`
}

AutoNATThrottleConfig configures the throttle limites.

type AutoTLS added in v0.32.0 

type AutoTLS struct {
	// Enables the p2p-forge feature and all related features.
	Enabled Flag `json:",omitempty"`

	// Optional, controls if Kubo should add /tls/sni/.../ws listener to every /tcp port if no explicit /ws is defined in Addresses.Swarm
	AutoWSS Flag `json:",omitempty"`

	// Optional override of the parent domain that will be used
	DomainSuffix *OptionalString `json:",omitempty"`

	// Optional override of HTTP API that acts as ACME DNS-01 Challenge broker
	RegistrationEndpoint *OptionalString `json:",omitempty"`

	// Optional Authorization token, used with private/test instances of p2p-forge
	RegistrationToken *OptionalString `json:",omitempty"`

	// Optional override of CA ACME API used by p2p-forge system
	CAEndpoint *OptionalString `json:",omitempty"`
}

AutoTLS includes optional configuration of p2p-forge client of service for obtaining a domain and TLS certificate to improve connectivity for web browser clients. More: https://github.com/ipshipyard/p2p-forge#readme

type ComposableRouterParams added in v0.16.0 

type ComposableRouterParams struct {
	Routers []ConfigRouter
	Timeout *OptionalDuration `json:",omitempty"`
}

type Config 

type Config struct {
	Identity  Identity  // local node's peer identity
	Datastore Datastore // local node's storage
	Addresses Addresses // local node's addresses
	Mounts    Mounts    // local node's mount points
	Discovery Discovery // local node's discovery mechanisms
	Routing   Routing   // local node's routing settings
	Ipns      Ipns      // Ipns settings
	Bootstrap []string  // local nodes's bootstrap peer addresses
	Gateway   Gateway   // local node's gateway server options
	API       API       // local node's API settings
	Swarm     SwarmConfig
	AutoNAT   AutoNATConfig
	AutoTLS   AutoTLS
	Pubsub    PubsubConfig
	Peering   Peering
	DNS       DNS
	Migration Migration

	Provider     Provider
	Reprovider   Reprovider
	Experimental Experiments
	Plugins      Plugins
	Pinning      Pinning
	Import       Import
	Version      Version

	Internal Internal // experimental/unstable options
}

Config is used to load ipfs config files.

func FromMap 

func FromMap(v map[string]interface{}) (*Config, error)

func Init 

func Init(out io.Writer, nBitsForKeypair int) (*Config, error)

func InitWithIdentity 

func InitWithIdentity(identity Identity) (*Config, error)

func (*Config) BootstrapPeers 

func (c *Config) BootstrapPeers() ([]peer.AddrInfo, error)

func (*Config) Clone 

func (c *Config) Clone() (*Config, error)

Clone copies the config. Use when updating.

func (*Config) SetBootstrapPeers 

func (c *Config) SetBootstrapPeers(bps []peer.AddrInfo)

type ConfigRouter added in v0.16.0 

type ConfigRouter struct {
	RouterName   string
	Timeout      Duration
	IgnoreErrors bool
	ExecuteAfter *OptionalDuration `json:",omitempty"`
}

type ConnMgr 

type ConnMgr struct {
	Type        *OptionalString   `json:",omitempty"`
	LowWater    *OptionalInteger  `json:",omitempty"`
	HighWater   *OptionalInteger  `json:",omitempty"`
	GracePeriod *OptionalDuration `json:",omitempty"`
}

ConnMgr defines configuration options for the libp2p connection manager.

type DHTMode added in v0.16.0 

type DHTMode string
const (
	DHTModeServer DHTMode = "server"
	DHTModeClient DHTMode = "client"
	DHTModeAuto   DHTMode = "auto"
)

type DHTRouterParams added in v0.16.0 

type DHTRouterParams struct {
	Mode                 DHTMode
	AcceleratedDHTClient bool `json:",omitempty"`
	PublicIPNetwork      bool
}

type DNS 

type DNS struct {
	// Resolvers is a map of FQDNs to URLs for custom DNS resolution.
	// URLs starting with `https://` indicate DoH endpoints.
	// Support for other resolver types can be added in the future.
	// https://en.wikipedia.org/wiki/Fully_qualified_domain_name
	// https://en.wikipedia.org/wiki/DNS_over_HTTPS
	//
	// Example:
	// - Custom resolver for ENS:          `eth.` → `https://dns.eth.limo/dns-query`
	// - Override the default OS resolver: `.`    → `https://doh.applied-privacy.net/query`
	Resolvers map[string]string
	// MaxCacheTTL is the maximum duration DNS entries are valid in the cache.
	MaxCacheTTL *OptionalDuration `json:",omitempty"`
}

DNS specifies DNS resolution rules using custom resolvers.

type Datastore 

type Datastore struct {
	StorageMax         string // in B, kB, kiB, MB, ...
	StorageGCWatermark int64  // in percentage to multiply on StorageMax
	GCPeriod           string // in ns, us, ms, s, m, h

	// deprecated fields, use Spec
	Type   string           `json:",omitempty"`
	Path   string           `json:",omitempty"`
	NoSync bool             `json:",omitempty"`
	Params *json.RawMessage `json:",omitempty"`

	Spec map[string]interface{}

	HashOnRead        bool
	BloomFilterSize   int
	BlockKeyCacheSize OptionalInteger `json:",omitempty"`
	WriteThrough      Flag            `json:",omitempty"`
}

Datastore tracks the configuration of the datastore.

func DefaultDatastoreConfig 

func DefaultDatastoreConfig() Datastore

DefaultDatastoreConfig is an internal function exported to aid in testing.

type Discovery 

type Discovery struct {
	MDNS MDNS
}

type Duration added in v0.16.0 

type Duration struct {
	time.Duration
}

func (Duration) MarshalJSON added in v0.16.0 

func (d Duration) MarshalJSON() ([]byte, error)

func (*Duration) UnmarshalJSON added in v0.16.0 

func (d *Duration) UnmarshalJSON(b []byte) error

type Experiments 

type Experiments struct {
	FilestoreEnabled              bool
	UrlstoreEnabled               bool
	ShardingEnabled               bool `json:",omitempty"` // deprecated by autosharding: https://github.com/ipfs/kubo/pull/8527
	Libp2pStreamMounting          bool
	P2pHttpProxy                  bool //nolint
	StrategicProviding            bool
	OptimisticProvide             bool
	OptimisticProvideJobsPoolSize int
	GatewayOverLibp2p             bool `json:",omitempty"`

	GraphsyncEnabled     graphsyncEnabled                 `json:",omitempty"`
	AcceleratedDHTClient experimentalAcceleratedDHTClient `json:",omitempty"`
}

type Flag 

type Flag int8

Flag represents a ternary value: false (-1), default (0), or true (+1).

When encoded in json, False is "false", Default is "null" (or empty), and True is "true". 

const (
	False   Flag = -1
	Default Flag = 0
	True    Flag = 1
)

func (Flag) MarshalJSON 

func (f Flag) MarshalJSON() ([]byte, error)

func (Flag) String 

func (f Flag) String() string

func (*Flag) UnmarshalJSON 

func (f *Flag) UnmarshalJSON(input []byte) error

func (Flag) WithDefault 

func (f Flag) WithDefault(defaultValue bool) bool

WithDefault resolves the value of the flag given the provided default value.

Panics if Flag is an invalid value.

type Gateway 

type Gateway struct {
	// HTTPHeaders configures the headers that should be returned by this
	// gateway.
	HTTPHeaders map[string][]string // HTTP headers to return with the gateway

	// RootRedirect is the path to which requests to `/` on this gateway
	// should be redirected.
	RootRedirect string

	// NoFetch configures the gateway to _not_ fetch blocks in response to
	// requests.
	NoFetch bool

	// NoDNSLink configures the gateway to _not_ perform DNS TXT record
	// lookups in response to requests with values in `Host` HTTP header.
	// This flag can be overridden per FQDN in PublicGateways.
	NoDNSLink bool

	// DeserializedResponses configures this gateway to respond to deserialized
	// requests. Disabling this option enables a Trustless only gateway, as per:
	// https://specs.ipfs.tech/http-gateways/trustless-gateway/. This can
	// be overridden per FQDN in PublicGateways.
	DeserializedResponses Flag

	// DisableHTMLErrors disables pretty HTML pages when an error occurs. Instead, a `text/plain`
	// page will be sent with the raw error message.
	DisableHTMLErrors Flag

	// PublicGateways configures behavior of known public gateways.
	// Each key is a fully qualified domain name (FQDN).
	PublicGateways map[string]*GatewaySpec

	// ExposeRoutingAPI configures the gateway port to expose
	// routing system as HTTP API at /routing/v1 (https://specs.ipfs.tech/routing/http-routing-v1/).
	ExposeRoutingAPI Flag
}

Gateway contains options for the HTTP gateway server.

type GatewaySpec 

type GatewaySpec struct {
	// Paths is explicit list of path prefixes that should be handled by
	// this gateway. Example: `["/ipfs", "/ipns"]`
	Paths []string

	// UseSubdomains indicates whether or not this gateway uses subdomains
	// for IPFS resources instead of paths. That is: http://CID.ipfs.GATEWAY/...
	//
	// If this flag is set, any /ipns/$id and/or /ipfs/$id paths in Paths
	// will be permanently redirected to http://$id.[ipns|ipfs].$gateway/.
	//
	// We do not support using both paths and subdomains for a single domain
	// for security reasons (Origin isolation).
	UseSubdomains bool

	// NoDNSLink configures this gateway to _not_ resolve DNSLink for the FQDN
	// provided in `Host` HTTP header.
	NoDNSLink bool

	// InlineDNSLink configures this gateway to always inline DNSLink names
	// (FQDN) into a single DNS label in order to interop with wildcard TLS certs
	// and Origin per CID isolation provided by rules like https://publicsuffix.org
	InlineDNSLink Flag

	// DeserializedResponses configures this gateway to respond to deserialized
	// responses. Disabling this option enables a Trustless Gateway, as per:
	// https://specs.ipfs.tech/http-gateways/trustless-gateway/.
	DeserializedResponses Flag
}

type HTTPRouterParams added in v0.18.0 

type HTTPRouterParams struct {
	// Endpoint is the URL where the routing implementation will point to get the information.
	Endpoint string

	// MaxProvideBatchSize determines the maximum amount of CIDs sent per batch.
	// Servers might not accept more than 100 elements per batch. 100 elements by default.
	MaxProvideBatchSize int

	// MaxProvideConcurrency determines the number of threads used when providing content. GOMAXPROCS by default.
	MaxProvideConcurrency int
}

func (*HTTPRouterParams) FillDefaults added in v0.18.0 

func (hrp *HTTPRouterParams) FillDefaults()

type Identity 

type Identity struct {
	PeerID  string
	PrivKey string `json:",omitempty"`
}

Identity tracks the configuration of the local node's identity.

func CreateIdentity 

func CreateIdentity(out io.Writer, opts []options.KeyGenerateOption) (Identity, error)

CreateIdentity initializes a new identity.

func (*Identity) DecodePrivateKey 

func (i *Identity) DecodePrivateKey(passphrase string) (ic.PrivKey, error)

DecodePrivateKey is a helper to decode the users PrivateKey.

type Import added in v0.29.0 

type Import struct {
	CidVersion      OptionalInteger
	UnixFSRawLeaves Flag
	UnixFSChunker   OptionalString
	HashFunction    OptionalString
	BatchMaxNodes   OptionalInteger
	BatchMaxSize    OptionalInteger
}

Import configures the default options for ingesting data. This affects commands that ingest data, such as 'ipfs add', 'ipfs dag put, 'ipfs block put', 'ipfs files write'.

type Internal 

type Internal struct {
	// All marked as omitempty since we are expecting to make changes to all subcomponents of Internal
	Bitswap                     *InternalBitswap  `json:",omitempty"`
	UnixFSShardingSizeThreshold *OptionalString   `json:",omitempty"`
	Libp2pForceReachability     *OptionalString   `json:",omitempty"`
	BackupBootstrapInterval     *OptionalDuration `json:",omitempty"`
}

type InternalBitswap 

type InternalBitswap struct {
	TaskWorkerCount             OptionalInteger
	EngineBlockstoreWorkerCount OptionalInteger
	EngineTaskWorkerCount       OptionalInteger
	MaxOutstandingBytesPerPeer  OptionalInteger
	ProviderSearchDelay         OptionalDuration
	WantHaveReplaceSize         OptionalInteger
}

type Ipns 

type Ipns struct {
	RepublishPeriod string
	RecordLifetime  string

	ResolveCacheSize int

	// MaxCacheTTL is the maximum duration IPNS entries are valid in the cache.
	MaxCacheTTL *OptionalDuration `json:",omitempty"`

	// Enable namesys pubsub (--enable-namesys-pubsub)
	UsePubsub Flag `json:",omitempty"`
}

type MDNS 

type MDNS struct {
	Enabled bool
}

type Method added in v0.16.0 

type Method struct {
	RouterName string
}

type MethodName added in v0.16.0 

type MethodName string
const (
	MethodNameProvide       MethodName = "provide"
	MethodNameFindProviders MethodName = "find-providers"
	MethodNameFindPeers     MethodName = "find-peers"
	MethodNameGetIPNS       MethodName = "get-ipns"
	MethodNamePutIPNS       MethodName = "put-ipns"
)

type Methods added in v0.16.0 

type Methods map[MethodName]Method

func (Methods) Check added in v0.16.0 

func (m Methods) Check() error

type Migration 

type Migration struct {
	// Sources in order of preference, where "IPFS" means use IPFS and "HTTPS"
	// means use default gateways. Any other values are interpreted as
	// hostnames for custom gateways. Empty list means "use default sources".
	DownloadSources []string
	// Whether or not to keep the migration after downloading it.
	// Options are "discard", "cache", "pin".  Empty string for default.
	Keep string
}

Migration configures how migrations are downloaded and if the downloads are added to IPFS locally.

type Mounts 

type Mounts struct {
	IPFS           string
	IPNS           string
	FuseAllowOther bool
}

Mounts stores the (string) mount points.

type OptionalDuration 

type OptionalDuration struct {
	// contains filtered or unexported fields
}

OptionalDuration wraps time.Duration to provide json serialization and deserialization.

NOTE: the zero value encodes to JSON nill.

func NewOptionalDuration added in v0.18.0 

func NewOptionalDuration(d time.Duration) *OptionalDuration

NewOptionalDuration returns an OptionalDuration from a string.

func (*OptionalDuration) IsDefault 

func (d *OptionalDuration) IsDefault() bool

func (OptionalDuration) MarshalJSON 

func (d OptionalDuration) MarshalJSON() ([]byte, error)

func (OptionalDuration) String 

func (d OptionalDuration) String() string

func (*OptionalDuration) UnmarshalJSON 

func (d *OptionalDuration) UnmarshalJSON(input []byte) error

func (*OptionalDuration) WithDefault 

func (d *OptionalDuration) WithDefault(defaultValue time.Duration) time.Duration

type OptionalInteger 

type OptionalInteger struct {
	// contains filtered or unexported fields
}

OptionalInteger represents an integer that has a default value

When encoded in json, Default is encoded as "null".

func NewOptionalInteger added in v0.19.0 

func NewOptionalInteger(v int64) *OptionalInteger

NewOptionalInteger returns an OptionalInteger from a int64.

func (*OptionalInteger) IsDefault 

func (p *OptionalInteger) IsDefault() bool

IsDefault returns if this is a default optional integer.

func (OptionalInteger) MarshalJSON 

func (p OptionalInteger) MarshalJSON() ([]byte, error)

func (OptionalInteger) String 

func (p OptionalInteger) String() string

func (*OptionalInteger) UnmarshalJSON 

func (p *OptionalInteger) UnmarshalJSON(input []byte) error

func (*OptionalInteger) WithDefault 

func (p *OptionalInteger) WithDefault(defaultValue int64) (value int64)

WithDefault resolves the integer with the given default.

type OptionalString 

type OptionalString struct {
	// contains filtered or unexported fields
}

OptionalString represents a string that has a default value

When encoded in json, Default is encoded as "null".

func NewOptionalString 

func NewOptionalString(s string) *OptionalString

NewOptionalString returns an OptionalString from a string.

func (*OptionalString) IsDefault 

func (p *OptionalString) IsDefault() bool

IsDefault returns if this is a default optional integer.

func (OptionalString) MarshalJSON 

func (p OptionalString) MarshalJSON() ([]byte, error)

func (OptionalString) String 

func (p OptionalString) String() string

func (*OptionalString) UnmarshalJSON 

func (p *OptionalString) UnmarshalJSON(input []byte) error

func (*OptionalString) WithDefault 

func (p *OptionalString) WithDefault(defaultValue string) (value string)

WithDefault resolves the integer with the given default.

type Peering 

type Peering struct {
	// Peers lists the nodes to attempt to stay connected with.
	Peers []peer.AddrInfo
}

Peering configures the peering service.

type Pinning 

type Pinning struct {
	RemoteServices map[string]RemotePinningService
}

type Plugin 

type Plugin struct {
	Disabled bool
	Config   interface{}
}

type Plugins 

type Plugins struct {
	Plugins map[string]Plugin
}

type Priority 

type Priority int64

Priority represents a value with a priority where 0 means "default" and -1 means "disabled".

When encoded in json, Default is encoded as "null" and Disabled is encoded as "false". 

const (
	DefaultPriority Priority = 0
	Disabled        Priority = -1
)

func (Priority) MarshalJSON 

func (p Priority) MarshalJSON() ([]byte, error)

func (Priority) String 

func (p Priority) String() string

func (*Priority) UnmarshalJSON 

func (p *Priority) UnmarshalJSON(input []byte) error

func (Priority) WithDefault 

func (p Priority) WithDefault(defaultPriority Priority) (priority int64, enabled bool)

WithDefault resolves the priority with the given default.

If defaultPriority is Default/0, this function will return 0.

Panics if the priority has an invalid value (e.g., not DefaultPriority, Disabled, or > 0).

type Profile 

type Profile struct {
	// Description briefly describes the functionality of the profile.
	Description string

	// Transform takes ipfs configuration and applies the profile to it.
	Transform Transformer

	// InitOnly specifies that this profile can only be applied on init.
	InitOnly bool
}

Profile contains the profile transformer the description of the profile.

type Provider 

type Provider struct {
	Strategy string // Which keys to announce
}

type PubsubConfig 

type PubsubConfig struct {
	// Router can be either floodsub (legacy) or gossipsub (new and
	// backwards compatible).
	Router string

	// DisableSigning disables message signing. Message signing is *enabled*
	// by default.
	DisableSigning bool

	// Enable pubsub (--enable-pubsub-experiment)
	Enabled Flag `json:",omitempty"`

	// SeenMessagesTTL is a value that controls the time window within which
	// duplicate messages will be identified and won't be emitted.
	SeenMessagesTTL *OptionalDuration `json:",omitempty"`

	// SeenMessagesStrategy is a setting that determines how the time-to-live
	// (TTL) countdown for deduplicating messages is calculated.
	SeenMessagesStrategy *OptionalString `json:",omitempty"`
}

type RPCAuthScope added in v0.25.0 

type RPCAuthScope struct {
	// AuthSecret is the secret that will be compared to the HTTP "Authorization".
	// header. A secret is in the format "type:value". Check the documentation for
	// supported types.
	AuthSecret string

	// AllowedPaths is an explicit list of RPC path prefixes to allow.
	// By default, none are allowed. ["/api/v0"] exposes all RPCs.
	AllowedPaths []string
}

type RelayClient 

type RelayClient struct {
	// Enables the auto relay feature: will use relays if it is not publicly reachable.
	Enabled Flag `json:",omitempty"`

	// StaticRelays configures static relays to use when this node is not
	// publicly reachable. If set, auto relay will not try to find any
	// other relay servers.
	StaticRelays []string `json:",omitempty"`
}

type RelayService 

type RelayService struct {
	// Enables the limited relay service for other peers (circuit v2 relay).
	Enabled Flag `json:",omitempty"`

	// ConnectionDurationLimit is the time limit before resetting a relayed connection.
	ConnectionDurationLimit *OptionalDuration `json:",omitempty"`
	// ConnectionDataLimit is the limit of data relayed (on each direction) before resetting the connection.
	ConnectionDataLimit *OptionalInteger `json:",omitempty"`

	// ReservationTTL is the duration of a new (or refreshed reservation).
	ReservationTTL *OptionalDuration `json:",omitempty"`

	// MaxReservations is the maximum number of active relay slots.
	MaxReservations *OptionalInteger `json:",omitempty"`
	// MaxCircuits is the maximum number of open relay connections for each peer; defaults to 16.
	MaxCircuits *OptionalInteger `json:",omitempty"`
	// BufferSize is the size of the relayed connection buffers.
	BufferSize *OptionalInteger `json:",omitempty"`

	// MaxReservationsPerIP is the maximum number of reservations originating from the same IP address.
	MaxReservationsPerIP *OptionalInteger `json:",omitempty"`
	// MaxReservationsPerASN is the maximum number of reservations origination from the same ASN.
	MaxReservationsPerASN *OptionalInteger `json:",omitempty"`
}

RelayService configures the resources of the circuit v2 relay. For every field a reasonable default will be defined in go-ipfs.

type RemotePinningService 

type RemotePinningService struct {
	API      RemotePinningServiceAPI
	Policies RemotePinningServicePolicies
}

type RemotePinningServiceAPI 

type RemotePinningServiceAPI struct {
	Endpoint string
	Key      string
}

type RemotePinningServiceMFSPolicy 

type RemotePinningServiceMFSPolicy struct {
	// Enable enables watching for changes in MFS and re-pinning the MFS root cid whenever a change occurs.
	Enable bool
	// Name is the pin name for MFS.
	PinName string
	// RepinInterval determines the repin interval when the policy is enabled. In ns, us, ms, s, m, h.
	RepinInterval string
}

type RemotePinningServicePolicies 

type RemotePinningServicePolicies struct {
	MFS RemotePinningServiceMFSPolicy
}

type Reprovider 

type Reprovider struct {
	Interval *OptionalDuration `json:",omitempty"` // Time period to reprovide locally stored objects to the network
	Strategy *OptionalString   `json:",omitempty"` // Which keys to announce
}

type ResourceMgr 

type ResourceMgr struct {
	// Enables the Network Resource Manager feature, default to on.
	Enabled Flag        `json:",omitempty"`
	Limits  swarmLimits `json:",omitempty"`

	MaxMemory          *OptionalString  `json:",omitempty"`
	MaxFileDescriptors *OptionalInteger `json:",omitempty"`

	// A list of multiaddrs that can bypass normal system limits (but are still
	// limited by the allowlist scope). Convenience config around
	// https://pkg.go.dev/github.com/libp2p/go-libp2p/p2p/host/resource-manager#Allowlist.Add
	Allowlist []string `json:",omitempty"`
}

ResourceMgr defines configuration options for the libp2p Network Resource Manager <https://github.com/libp2p/go-libp2p/tree/master/p2p/host/resource-manager#readme>

type Router 

type Router struct {
	// Router type ID. See RouterType for more info.
	Type RouterType

	// Parameters are extra configuration that this router might need.
	// A common one for HTTP router is "Endpoint".
	Parameters interface{}
}

type RouterParser added in v0.16.0 

type RouterParser struct {
	Router
}

func (*RouterParser) UnmarshalJSON added in v0.16.0 

func (r *RouterParser) UnmarshalJSON(b []byte) error

type RouterType 

type RouterType string

Type is the routing type. Depending of the type we need to instantiate different Routing implementations. 

const (
	RouterTypeHTTP       RouterType = "http"       // HTTP JSON API for delegated routing systems (IPIP-337).
	RouterTypeDHT        RouterType = "dht"        // DHT router.
	RouterTypeSequential RouterType = "sequential" // Router helper to execute several routers sequentially.
	RouterTypeParallel   RouterType = "parallel"   // Router helper to execute several routers in parallel.
)

type Routers added in v0.16.0 

type Routers map[string]RouterParser

type Routing 

type Routing struct {
	// Type sets default daemon routing mode.
	//
	// Can be one of "auto", "autoclient", "dht", "dhtclient", "dhtserver", "none", or "custom".
	// When unset or set to "auto", DHT and implicit routers are used.
	// When "custom" is set, user-provided Routing.Routers is used.
	Type *OptionalString `json:",omitempty"`

	AcceleratedDHTClient Flag `json:",omitempty"`

	LoopbackAddressesOnLanDHT Flag `json:",omitempty"`

	Routers Routers

	Methods Methods
}

Routing defines configuration options for libp2p routing.

type Strings 

type Strings []string

Strings is a helper type that (un)marshals a single string to/from a single JSON string and a slice of strings to/from a JSON array of strings.

func (Strings) MarshalJSON 

func (o Strings) MarshalJSON() ([]byte, error)

MarshalJSON conforms to the json.Marshaler interface.

func (*Strings) UnmarshalJSON 

func (o *Strings) UnmarshalJSON(data []byte) error

UnmarshalJSON conforms to the json.Unmarshaler interface.

type SwarmConfig 

type SwarmConfig struct {
	// AddrFilters specifies a set libp2p addresses that we should never
	// dial or receive connections from.
	AddrFilters []string

	// DisableBandwidthMetrics disables recording of bandwidth metrics for a
	// slight reduction in memory usage. You probably don't need to set this
	// flag.
	DisableBandwidthMetrics bool

	// DisableNatPortMap turns off NAT port mapping (UPnP, etc.).
	DisableNatPortMap bool

	// RelayClient controls the client side of "auto relay" feature.
	// When enabled, the node will use relays if it is not publicly reachable.
	RelayClient RelayClient

	// RelayService.* controls the "relay service".
	// When enabled, node will provide a limited relay service to other peers.
	RelayService RelayService

	// EnableHolePunching enables the hole punching service.
	EnableHolePunching Flag `json:",omitempty"`

	// Transports contains flags to enable/disable libp2p transports.
	Transports Transports

	// ConnMgr configures the connection manager.
	ConnMgr ConnMgr

	// ResourceMgr configures the libp2p Network Resource Manager
	ResourceMgr ResourceMgr
}

type Transformer 

type Transformer func(c *Config) error

Transformer is a function which takes configuration and applies some filter to it.

type Transports 

type Transports struct {
	// Network specifies the base transports we'll use for dialing. To
	// listen on a transport, add the transport to your Addresses.Swarm.
	Network struct {
		// All default to on.
		QUIC         Flag `json:",omitempty"`
		TCP          Flag `json:",omitempty"`
		Websocket    Flag `json:",omitempty"`
		Relay        Flag `json:",omitempty"`
		WebTransport Flag `json:",omitempty"`
		// except WebRTCDirect which is experimental and opt-in.
		WebRTCDirect Flag `json:",omitempty"`
	}

	// Security specifies the transports used to encrypt insecure network
	// transports.
	Security struct {
		// Defaults to 100.
		TLS Priority `json:",omitempty"`
		// Defaults to 300.
		Noise Priority `json:",omitempty"`
	}

	// Multiplexers specifies the transports used to multiplex multiple
	// connections over a single duplex connection.
	Multiplexers struct {
		// Defaults to 100.
		Yamux Priority `json:",omitempty"`
	}
}

type Version added in v0.30.0 

type Version struct {
	// Optional suffix to the AgentVersion presented by `ipfs id` and exposed
	// via libp2p identify protocol.
	AgentSuffix *OptionalString `json:",omitempty"`

	// Detect when to warn about new version when observed via libp2p identify
	SwarmCheckEnabled          Flag             `json:",omitempty"`
	SwarmCheckPercentThreshold *OptionalInteger `json:",omitempty"`
}

Version allows controling things like custom user agent and update checks.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.