Configuring Your Node

vasa -

The go-ipfs config file is a JSON document located at $IPFS_PATH/config which is by default ~/.ipfs/config . It 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.

Profiles

Configuration profiles allow to tweak configuration quickly. Profiles can be applied with --profile flag to ipfs init or with the ipfs config profile apply command. When a profile is applied a backup of the configuration file will be created in $IPFS_PATH.

Available profiles:

  • server
    Recommended for nodes with public IPv4 address (servers, VPSes, etc.), disables host and content discovery in local networks. For eg. if you are running on a server in a data center, then use this profile.
  • local-discovery
    Sets default values to fields affected by server profile, enables discovery in local networks.
  • test
    Reduces external interference, useful for running ipfs in test environments. Note that with these settings node won't be able to talk to the rest of the network without manual bootstrap.
  • default-networking
    Restores default network settings. Inverse profile of the test profile.
  • badgerds
    Replaces default datastore configuration with experimental badger datastore. If you apply this profile after ipfs init, you will need to convert your datastore to the new configuration. You can do this using ipfs-ds-convert
WARNING: badger datastore is experimental. Make sure to backup your data frequently.
  • default-datastore
    Restores default datastore configuration.
  • lowpower
    Reduces daemon overhead on the system. May affect node functionality, performance of content discovery and data fetching may be degraded.
  • randomports
    Generate random port for swarm.

Now, let's explore each section of the config file.

Config Sections
Addresses

The config file stores a few different address types, all of which use the multiaddr addressing format. Lets go over what each address type means.

"Addresses": {
    "API": "/ip4/127.0.0.1/tcp/5001",
    "Announce": [],
    "Gateway": "/ip4/127.0.0.1/tcp/8080"
    "NoAnnounce": [],
    "Swarm": [
    "/ip4/0.0.0.0/tcp/4001"
    ]
}
API

Default: /ip4/127.0.0.1/tcp/5001

The API address is the address that the daemon will serve the http API from. This API is used to control the daemon through the command line, or simply via curl if you’re feeling adventurous. You should ensure that this address is not dialable from outside of your machine, or other potentially malicious parties may be able to send commands to your ipfs daemon.

Gateway

Default: /ip4/127.0.0.1/tcp/8080

The Gateway address is the address that the daemon will serve the gateway interface from. The gateway may be used to view files through ipfs, and serve static web content. This port may or may not be dialable from outside of your machine, thats entirely up to you. The gateway address is optional, if you leave it blank, the gateway server will not start.

Swarm

Default:
[
  "/ip4/0.0.0.0/tcp/4001",
  "/ip6/::/tcp/4001"
]

Swarm addresses are addresses that the local daemon will listen on for connections from other ipfs peers. You should try to ensure that these addresses can be dialed from a separate computer and that there are no firewalls blocking the ports you specify.

Announce

Default: []

If non-empty, this array specifies the swarm addresses to announce to the network. If empty, the daemon will announce inferred swarm addresses.

NoAnnounce

Default: []

Array of swarm addresses not to announce to the network.

API

Contains information used by the API gateway.

"API": {
    "HTTPHeaders": {
      "Access-Control-Allow-Credentials": [
        "true"
      ],
      "Access-Control-Allow-Headers": [
        "Authorization"
      ],
      "Access-Control-Allow-Methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE",
        "OPTIONS"
      ],
      "Access-Control-Allow-Origin": [
        "*"
      ],
      "Access-Control-Expose-Headers": [
        "Location"
      ]
    }
  }
HTTPHeaders

Default: null

Map of HTTP headers to set on responses from the API HTTP server.

Bootstrap

Default: The ipfs.io bootstrap nodes

The Bootstrap config array specifies the list of ipfs peers that your daemon will connect to on startup. The default values for this are the ‘ipfs solarnet’ nodes, which are a set of VPS servers distributed around the country.

"Bootstrap": [
    "/dnsaddr/bootstrap.libp2p.io/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
    "/dnsaddr/bootstrap.libp2p.io/ipfs/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa",
    ...
  ]
Datastore

Contains information related to the construction and operation of the on-disk storage system.

"Datastore": {
    "BloomFilterSize": 0,
    "GCPeriod": "1h",
    "HashOnRead": false,
    "Spec": {
      "mounts": [
        {
          "child": {
            "path": "blocks",
            "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2",
            "sync": true,
            "type": "flatfs"
          },
          "mountpoint": "/blocks",
          "prefix": "flatfs.datastore",
          "type": "measure"
        },
        {
          "child": {
            "compression": "none",
            "path": "datastore",
            "type": "levelds"
          },
          "mountpoint": "/",
          "prefix": "leveldb.datastore",
          "type": "measure"
        }
      ],
      "type": "mount"
    },
    "StorageGCWatermark": 90,
    "StorageMax": "10GB"
  }
StorageMax

Default: 10GB

A soft upper limit for the size of the how much the ipfs repo will store. If --enable-gc flag is set, then StorageGCWatermark is used to calculate whether to trigger a gc(Garbage Collector) run. So, if StorageGCWatermark is 90 then it means that the when storage exceeds 9GB(90%), the Garbage Collector will start deleting least used blocks of data until the storage reduces below the StorageGCWatermark.

StorageGCWatermark

Default: 90

The percentage of the StorageMax value at which a garbage collection will be triggered automatically if the daemon was run with automatic gc enabled (that option defaults to false currently).

GCPeriod

Default: 1h

A time duration specifying how frequently to run a garbage collection. Only used if automatic gc is enabled.

HashOnRead

Default: false

A boolean value. If set to true, all block reads from disk will be hashed and verified. This will cause increased CPU utilization.

BloomFilterSize

Default: 0

A number representing the size in bytes of the blockstore's bloom filter. A value of zero represents the feature being disabled.

This site generates useful graphs for various bloom filter values: https://hur.st/bloomfilter/?n=1e6&p=0.01&m=&k=7 You may use it to find a preferred optimal value, where is BloomFilterSize in bits. Remember to convert the value m from bits, into bytes for use as BloomFilterSize in the config file. For example, for 1,000,000 blocks, expecting a 1% false positive rate, you'd end up with a filter size of 9592955 bits, so for BloomFilterSize we'd want to use 1199120 bytes. As of writing, 7 hash functions are used, so the constant k is 7 in the formula.

Spec

Default:


{
  "mounts": [
	{
	  "child": {
		"path": "blocks",
		"shardFunc": "/repo/flatfs/shard/v1/next-to-last/2",
		"sync": true,
		"type": "flatfs"
	  },
	  "mountpoint": "/blocks",
	  "prefix": "flatfs.datastore",
	  "type": "measure"
	},
	{
	  "child": {
		"compression": "none",
		"path": "datastore",
		"type": "levelds"
	  },
	  "mountpoint": "/",
	  "prefix": "leveldb.datastore",
	  "type": "measure"
	}
  ],
  "type": "mount"
}

Spec defines the structure of the ipfs datastore. It is a composable structure, where each datastore is represented by a json object. Datastores can wrap other datastores to provide extra functionality (eg metrics, logging, or caching).

This can be changed manually, however, if you make any changes that require a different on-disk structure, you will need to run the ipfs-ds-convert tool to migrate data into the new structures.

Discovery

Contains options for configuring ipfs node discovery mechanisms.

"Discovery": {
    "MDNS": {
      "Enabled": true,
      "Interval": 10
    }
  }
MDNS

Options for multicast dns peer discovery.

  • Default: true

    A boolean value for whether or not mdns should be active.
Interval

A number of seconds to wait between discovery checks.

Routing

Contains options for content routing mechanisms.

"Routing": {
    "Type": "dht"
  }
Type

Content routing mode. Can be overridden with daemon --routing flag. When set to dhtclient, the node won't join the DHT but can still use it to find content. Valid modes are:

  • dht (default)
  • dhtclient
  • none
Gateway

Options for the HTTP gateway.

"Gateway": {
    "APICommands": [],
    "HTTPHeaders": {
      "Access-Control-Allow-Headers": [
        "X-Requested-With",
        "Range",
        "User-Agent"
      ],
      "Access-Control-Allow-Methods": [
        "GET"
      ],
      "Access-Control-Allow-Origin": [
        "*"
      ]
    },
    "NoFetch": false,
    "PathPrefixes": [],
    "RootRedirect": "",
    "Writable": false
  }
NoFetch

Default: false

When set to true, the gateway will only serve content already in the local repo and will not fetch files from the network.

HTTPHeaders

Default:

{
	"Access-Control-Allow-Headers": [
		"X-Requested-With"
	],
	"Access-Control-Allow-Methods": [
		"GET"
	],
	"Access-Control-Allow-Origin": [
		"*"
	]
}

Headers to set on gateway responses.

RootRedirect

Default: ""

A url to redirect requests for / to.

Writable

Default: false

A boolean to configure whether the gateway is writeable or not.

Identity

Options for the HTTP gateway.

"Identity": {
    "PeerID": "QmVD2YQF96S6Em8zhgNNDKVc7jKUqTyFRaL6ejwKXUUCju"
  }
PeerID

The unique PKI identity label for this configs peer. Set on init and never read, its merely here for convenience. Ipfs will always generate the peerID from its keypair at runtime.

PrivKey

The base64 encoded protobuf describing (and containing) the nodes private key.

Ipns

Options for the HTTP gateway.

"Ipns": {
    "RecordLifetime": "",
    "RepublishPeriod": "",
    "ResolveCacheSize": 128
  }
RepublishPeriod

A time duration specifying how frequently to republish ipns records to ensure they stay fresh on the network. If unset, we default to 4 hours.

RecordLifetime

A time duration specifying the value to set on ipns records for their validity lifetime. If unset, we default to 24 hours.

ResolveCacheSize

The number of entries to store in an LRU cache of resolved ipns entries. Entries will be kept cached until their lifetime is expired.

Mounts

The mounts config values specifies the default mount points for the ipfs and ipns virtual file systems, if no other directories are specified by the ipfs mount command. These folders should exist, and have permissions for your user to be able to mount to them via fuse.

"Mounts": {
    "FuseAllowOther": false,
    "IPFS": "/ipfs",
    "IPNS": "/ipns"
  }
IPFS

Mountpoint for /ipfs/.

IPNS

Mountpoint for /ipns/.

FuseAllowOther

Sets the FUSE allow other option on the mountpoint.

Reprovider

The mounts config values specifies the default mount points for the ipfs and ipns virtual file systems, if no other directories are specified by the ipfs mount command. These folders should exist, and have permissions for your user to be able to mount to them via fuse.

"Reprovider": {
    "Interval": "12h",
    "Strategy": "all"
  }
Interval

Sets the time between rounds of reproviding local content to the routing system. If unset, it defaults to 12 hours. If set to the value "0" it will disable content reproviding.

Note: disabling content reproviding will result in other nodes on the network not being able to discover that you have the objects that you have. If you want to have this disabled and keep the network aware of what you have, you must manually announce your content periodically.

Strategy

Tells reprovider what should be announced. Valid strategies are:

  • "all" (default) - announce all stored data
  • "pinned" - only announce pinned data
  • "roots" - only announce directly pinned keys and root keys of recursive pinsNote: disabling content reproviding will result in other nodes on the network not being able to discover that you have the objects that you have. If you want to have this disabled and keep the network aware of what you have, you must manually announce your content periodically.
Swarm

Options for configuring the swarm.

"Swarm": {
    "AddrFilters": null,
    "ConnMgr": {
      "GracePeriod": "20s",
      "HighWater": 900,
      "LowWater": 600,
      "Type": "basic"
    },
    "DisableBandwidthMetrics": false,
    "DisableNatPortMap": false,
    "DisableRelay": false,
    "EnableAutoNATService": false,
    "EnableAutoRelay": false,
    "EnableRelayHop": false
  }
AddrFilters

An array of addresses (multiaddr netmasks) to not dial. By default, IPFS nodes advertise all addresses, even internal ones. This makes it easier for nodes on the same network to reach each other. Unfortunately, this means that an IPFS node will try to connect to one or more private IP addresses whenever dialing another node, even if this other node is on a different network. This may may trigger netscan alerts on some hosting providers or cause strain in some setups.

The server configuration profile fills up this list with sensible defaults, preventing dials to all non-routable IP addresses (e.g., 192.168.0.0/16) but you should always check settings against your own network and/or hosting provider.

DisableBandwidthMetrics

A boolean value that when set to true, will cause ipfs to not keep track of bandwidth metrics. Disabling bandwidth metrics can lead to a slight performance improvement, as well as a reduction in memory usage.

DisableNatPortMap

Disable NAT discovery.

DisableRelay

Disables the p2p-circuit relay transport.

DisableRelay

Enables HOP relay for the node. If this is enabled, the node will act as an intermediate (Hop Relay) node in relay circuits for connected peers.

EnableAutoRelay

Enables automatic relay for this node. If the node is a HOP relay (EnableRelayHop is true) then it will advertise itself as a relay through the DHT. Otherwise, the node will test its own NAT situation (dialability) using passively discovered AutoNAT services. If the node is not publicly reachable, then it will seek HOP relays advertised through the DHT and override its public address(es) with relay addresses.

EnableAutoNATService

Enables the AutoNAT service for this node. The service allows peers to discover their NAT situation by requesting dial backs to their public addresses. This should only be enabled on publicly reachable nodes.

ConnMgr

The connection manager determines which and how many connections to keep and can be configured to keep.

  • TypeSets the type of connection manager to use, options are: "none" (no connection management) and "basic".
  • LowWater LowWater is the minimum number of connections to maintain.
  • HighWater HighWater is the number of connections that, when exceeded, will trigger a connection GC operation.
  • GracePeriod GracePeriod is a time duration that new connections are immune from being closed by the connection manager.

The "basic" connection manager tries to keep between LowWater and HighWater connections. It works by:

  1. Keeping all connections until HighWater connections is reached.
  2. Once HighWater is reached, it closes connections until LowWater is reached.
  3. To prevent thrashing, it never closes connections established within the GracePeriod.