go-ipfs-config: github.com/ipfs/go-ipfs-config Index | Files | Directories

package config

import "github.com/ipfs/go-ipfs-config"

package config implements the ipfs config file datastructures and utilities.


Package Files

addresses.go api.go autonat.go bootstrap_peers.go config.go datastore.go discovery.go experiments.go gateway.go identity.go init.go ipns.go mounts.go peering.go plugins.go profile.go provider.go pubsub.go reprovider.go routing.go swarm.go types.go


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"
const DefaultConnMgrGracePeriod = time.Second * 20

DefaultConnMgrGracePeriod is the default value for the connection managers grace period

const DefaultConnMgrHighWater = 900

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

const DefaultConnMgrLowWater = 600

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

const DefaultDataStoreDirectory = "datastore"

DefaultDataStoreDirectory is the directory to store all the local IPFS data.

const IdentityTag = "Identity"
const PrivKeySelector = IdentityTag + "." + PrivKeyTag
const PrivKeyTag = "PrivKey"


var DefaultBootstrapAddresses = []string{

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.

var ErrInvalidPeerAddr = errors.New("invalid peer address")

ErrInvalidPeerAddr signals an address is not a valid peer address.

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/"}
            c.Addresses.Gateway = Strings{"/ip4/"}
            c.Addresses.Swarm = []string{

            c.Swarm.DisableNatPortMap = 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: "" /* 208 byte string literal not displayed */,

        InitOnly: true,
        Transform: func(c *Config) error {
            c.Datastore.Spec = flatfsSpec()
            return nil
    "flatfs": {
        Description: "" /* 820 byte string literal not displayed */,

        InitOnly: true,
        Transform: func(c *Config) error {
            c.Datastore.Spec = flatfsSpec()
            return nil
    "badgerds": {
        Description: "" /* 641 byte string literal not displayed */,

        InitOnly: true,
        Transform: func(c *Config) error {
            c.Datastore.Spec = badgerSpec()
            return nil
    "lowpower": {
        Description: "" /* 141 byte string literal not displayed */,

        Transform: func(c *Config) error {
            c.Routing.Type = "dhtclient"
            c.AutoNAT.ServiceMode = AutoNATServiceDisabled
            c.Reprovider.Interval = "0"

            c.Swarm.ConnMgr.LowWater = 20
            c.Swarm.ConnMgr.HighWater = 40
            c.Swarm.ConnMgr.GracePeriod = time.Minute.String()
            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/", port),
                fmt.Sprintf("/ip6/::/tcp/%d", port),
            return nil

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

func BootstrapPeerStrings Uses

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

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

func DataStorePath Uses

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 Uses

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 Uses

func Filename(configroot string) (string, error)

Filename returns the configuration file path given a configuration root directory. If the configuration root directory is empty, use the default one

func HumanOutput Uses

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

HumanOutput gets a config value ready for printing

func Marshal Uses

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

Marshal configuration with JSON

func ParseBootstrapPeers Uses

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

ParseBootstrapPeer parses a bootstrap list into a list of AddrInfos.

func Path Uses

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 Uses

func PathRoot() (string, error)

PathRoot returns the default configuration root directory

func ToMap Uses

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

type API Uses

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

type Addresses Uses

type Addresses struct {
    Swarm      []string // addresses for the swarm to listen on
    Announce   []string // swarm addresses to announce to the network
    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 Uses

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 Uses

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.
    // AutoNATServiceDisabled indicates that the user has disabled the
    // AutoNATService.

func (AutoNATServiceMode) MarshalText Uses

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

func (*AutoNATServiceMode) UnmarshalText Uses

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

type AutoNATThrottleConfig Uses

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 Duration `json:",omitempty"`

AutoNATThrottleConfig configures the throttle limites

type Config Uses

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
    Pubsub    PubsubConfig
    Peering   Peering

    Provider     Provider
    Reprovider   Reprovider
    Experimental Experiments
    Plugins      Plugins

Config is used to load ipfs config files.

func FromMap Uses

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

func Init Uses

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

func InitWithIdentity Uses

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

func (*Config) BootstrapPeers Uses

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

func (*Config) Clone Uses

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

Clone copies the config. Use when updating.

func (*Config) SetBootstrapPeers Uses

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

type ConnMgr Uses

type ConnMgr struct {
    Type        string
    LowWater    int
    HighWater   int
    GracePeriod string

ConnMgr defines configuration options for the libp2p connection manager

type Datastore Uses

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

Datastore tracks the configuration of the datastore.

func DefaultDatastoreConfig Uses

func DefaultDatastoreConfig() Datastore

DefaultDatastoreConfig is an internal function exported to aid in testing.

type Discovery Uses

type Discovery struct {

type Duration Uses

type Duration time.Duration

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

NOTE: the zero value encodes to an empty string.

func (Duration) MarshalText Uses

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

func (Duration) String Uses

func (d Duration) String() string

func (*Duration) UnmarshalText Uses

func (d *Duration) UnmarshalText(text []byte) error

type Experiments Uses

type Experiments struct {
    FilestoreEnabled     bool
    UrlstoreEnabled      bool
    ShardingEnabled      bool
    GraphsyncEnabled     bool
    Libp2pStreamMounting bool
    P2pHttpProxy         bool
    StrategicProviding   bool

type Flag Uses

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 Uses

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

func (Flag) String Uses

func (f Flag) String() string

func (*Flag) UnmarshalJSON Uses

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

func (Flag) WithDefault Uses

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 Uses

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

    // Writable enables PUT/POST request handling by this gateway. Usually,
    // writing is done through the API, not the gateway.
    Writable bool

    // PathPrefixes  is an array of acceptable url paths that a client can
    // specify in X-Ipfs-Path-Prefix header.
    // The X-Ipfs-Path-Prefix header is used to specify a base path to prepend
    // to links in directory listings and for trailing-slash redirects. It is
    // intended to be set by a frontend http proxy like nginx.
    // Example: To mount blog.ipfs.io (a DNSLink site) at ipfs.io/blog
    // set PathPrefixes to ["/blog"] and nginx config to translate paths
    // and pass Host header (for DNSLink):
    //  location /blog/ {
    //    rewrite "^/blog(/.*)$" $1 break;
    //    proxy_set_header Host blog.ipfs.io;
    //    proxy_set_header X-Ipfs-Gateway-Prefix /blog;
    //    proxy_pass;
    //  }
    PathPrefixes []string

    // FIXME: Not yet implemented
    APICommands []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 overriden per FQDN in PublicGateways.
    NoDNSLink bool

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

Gateway contains options for the HTTP gateway server.

type GatewaySpec Uses

type GatewaySpec struct {
    // Paths is explicit list of path prefixes that should be handled by
    // this gateway. Example: `["/ipfs", "/ipns", "/api"]`
    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 PathPrefixes
    // 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

type Identity Uses

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

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

func CreateIdentity Uses

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

CreateIdentity initializes a new identity.

func (*Identity) DecodePrivateKey Uses

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

DecodePrivateKey is a helper to decode the users PrivateKey

type Ipns Uses

type Ipns struct {
    RepublishPeriod string
    RecordLifetime  string

    ResolveCacheSize int

type MDNS Uses

type MDNS struct {
    Enabled bool

    // Time in seconds between discovery rounds
    Interval int

type Mounts Uses

type Mounts struct {
    IPFS           string
    IPNS           string
    FuseAllowOther bool

Mounts stores the (string) mount points

type Peering Uses

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

Peering configures the peering service.

type Plugin Uses

type Plugin struct {
    Disabled bool
    Config   interface{}

type Plugins Uses

type Plugins struct {
    Plugins map[string]Plugin

type Priority Uses

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 Uses

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

func (Priority) String Uses

func (p Priority) String() string

func (*Priority) UnmarshalJSON Uses

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

func (Priority) WithDefault Uses

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 Uses

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 Uses

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

type PubsubConfig Uses

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

type Reprovider Uses

type Reprovider struct {
    Interval string // Time period to reprovide locally stored objects to the network
    Strategy string // Which keys to announce

type Routing Uses

type Routing struct {
    // Type sets default daemon routing mode.
    // Can be one of "dht", "dhtclient", "dhtserver", "none", or unset.
    Type string

Routing defines configuration options for libp2p routing

type Strings Uses

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 Uses

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

MarshalJSON conforms to the json.Marshaler interface.

func (*Strings) UnmarshalJSON Uses

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

UnmarshalJSON conforms to the json.Unmarshaler interface.

type SwarmConfig Uses

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

    // DisableRelay explicitly disables the relay transport.
    // Deprecated: This flag is deprecated and is overridden by
    // `Transports.Relay` if specified.
    DisableRelay bool `json:",omitempty"`

    // EnableRelayHop makes this node act as a public relay, relaying
    // traffic between other nodes.
    EnableRelayHop bool

    // EnableAutoRelay enables the "auto relay" feature.
    // When both EnableAutoRelay and EnableRelayHop are set, this go-ipfs node
    // will advertise itself as a public relay. Otherwise it will find and use
    // advertised public relays when it determines that it's not reachable
    // from the public internet.
    EnableAutoRelay bool

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

    // ConnMgr configures the connection manager.
    ConnMgr ConnMgr

type Transformer Uses

type Transformer func(c *Config) error

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

type Transports Uses

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"`

    // Security specifies the transports used to encrypt insecure network
    // transports.
    Security struct {
        // Defaults to 100.
        TLS Priority `json:",omitempty"`
        // Defaults to 200.
        SECIO 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"`
        // Defaults to 200.
        Mplex Priority `json:",omitempty"`



Package config imports 18 packages (graph) and is imported by 118 packages. Updated 2020-07-15. Refresh now. Tools for package owners.