Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

Latest commit

 

History

History
352 lines (234 loc) · 10.7 KB

CONFIG.md

File metadata and controls

352 lines (234 loc) · 10.7 KB
Raw

The js-ipfs config file

The js-ipfs config file is a JSON document located in the root directory of the js-ipfs repository.

Table of Contents

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.

  • 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.

  • lowpower

    Reduces daemon overhead on the system. May affect node functionality, performance of content discovery and data fetching may be degraded.

  • default-power

    Inverse of "lowpower" profile.

Addresses

Contains information about various listener addresses to be used by this node.

API

The IPFS daemon exposes an HTTP API that allows to control the node and run the same commands as you can do from the command line. It is defined on the HTTP API Spec.

Multiaddr or array of Multiaddr describing the address(es) to serve the HTTP API on.

Default: /ip4/127.0.0.1/tcp/5002

RPC

js-IPFS has a gRPC-over-websockets server that allows it to do things that you cannot do over HTTP like bi-directional streaming. It implements the same API as the HTTP API Spec and can be accessed using the ipfs-client module.

Configure the address it listens on using this config key.

Default: /ip4/127.0.0.1/tcp/5003

Delegates

Delegate peers are used to find peers and retrieve content from the network on your behalf.

Array of Multiaddr describing which addresses to use as delegate nodes.

Default: []

Gateway

A gateway is exposed by the IPFS daemon, which allows an easy way to access content from IPFS, using an IPFS path.

Multiaddr or array of Multiaddr describing the address(es) to serve the gateway on.

Default: /ip4/127.0.0.1/tcp/9090

Swarm

Array of Multiaddr describing which addresses to listen on for p2p swarm connections.

Default:

[
  "/ip4/0.0.0.0/tcp/4002",
  "/ip4/127.0.0.1/tcp/4003/ws"
]

Announce

Array of Multiaddr describing which addresses to announce over the network.

Default:

[]

Bootstrap

Bootstrap is an array of Multiaddr of trusted nodes to connect to in order to initiate a connection to the network.

Datastore

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

Spec

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 (e.g. 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.

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

Discovery

Contains options for configuring IPFS node discovery mechanisms.

MDNS

Multicast DNS is a discovery protocol that is able to find other peers on the local network.

Options for Multicast DNS peer discovery:

  • Enabled

    A boolean value for whether or not MDNS should be active.

    Default: true

  • Interval

    A number of seconds to wait between discovery checks.

    Default: 10

webRTCStar

WebRTCStar is a discovery mechanism provided by a signalling-star that allows peer-to-peer communications in the browser.

Options for webRTCstar peer discovery:

  • Enabled

    A boolean value for whether or not webRTCStar should be active.

    Default: true

Identity

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.

Keychain

We can customize the key management and cryptographically protected messages by changing the Keychain options. Those options are used for generating the derived encryption key (DEK). The DEK object, along with the passPhrase, is the input to a PBKDF2 function.

Default:

{
  "dek": {
    "keyLength": 512/8,
    "iterationCount": 1000,
    "salt": "at least 16 characters long",
    "hash": "sha2-512"
  }
}

You can check the parameter choice for pbkdf2 for more information.

Pubsub

Options for configuring the pubsub subsystem. It is important pointing out that this is not supported in the browser. If you want to configure a different pubsub router in the browser you must configure libp2p.modules.pubsub options instead.

Router

A string value for specifying which pubsub routing protocol to use. You can either use gossipsub in order to use the ChainSafe/gossipsub-js implementation, or floodsub to use the libp2p/js-libp2p-floodsub implementation. You can read more about these implementations on the libp2p/specs/pubsub document.

Default: gossipsub

Enabled

A boolean value for wether or not pubsub router should be active.

Default: true

Swarm

Options for configuring the swarm.

ConnMgr

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

  • LowWater

    The minimum number of connections to maintain.

    Default: 200 (both browser and node.js)

  • HighWater

    The number of connections that, when exceeded, will trigger a connection GC operation.

    Default: 500 (both browser and node.js)

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.

DisableNatPortMap

By default when running under nodejs, libp2p will try to use UPnP to open a random high port on your router for any TCP connections you have configured.

Set DisableNatPortMap to true to disable this behaviour.

Example

{
  "Swarm": {
    "ConnMgr": {
      "LowWater": 100,
      "HighWater": 200,
    }
  },
  "DisableNatPortMap": false
}

API

Settings applied to the HTTP RPC API server

HTTPHeaders

HTTP header settings used by the HTTP RPC API server

Access-Control-Allow-Origin

The RPC API endpoints running on your local node are protected by the Cross-Origin Resource Sharing mechanism.

When a request is made that sends an Origin header, that Origin must be present in the allowed origins configured for the node, otherwise the browser will disallow that request to proceed, unless mode: 'no-cors' is set on the request, in which case the response will be opaque.

To allow requests from web browsers, configure the API.HTTPHeaders.Access-Control-Allow-Origin setting. This is an array of URL strings with safelisted Origins.

Example

If you are running a webapp locally that you access via the URL http://127.0.0.1:3000, you must add it to the list of allowed origins in order to make API requests from that webapp in the browser:

{
  "API": {
    "HTTPHeaders": {
      "Access-Control-Allow-Origin": [
        "http://127.0.0.1:3000"
      ]
    }
  }
}

Note that the origin must match exactly so 'http://127.0.0.1:3000' is treated differently to 'http://127.0.0.1:3000/'

Access-Control-Allow-Credentials

The Access-Control-Allow-Credentials header allows client-side JavaScript running in the browser to send and receive credentials with requests - cookies, auth headers or TLS certificates.

For most applications this will not be necessary but if you require this to be set, see the example below for how to configure it.

Example
{
  "API": {
    "HTTPHeaders": {
      "Access-Control-Allow-Credentials": true
    }
  }
}