From 8ca659ac5c41998e838b183afbb1e1446ac07dbb Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Mon, 15 Jul 2019 12:23:38 +0200 Subject: [PATCH 1/7] docs: add config file --- README.md | 2 +- config.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 config.md diff --git a/README.md b/README.md index 5d5eb9bba7..ba4808b2d7 100644 --- a/README.md +++ b/README.md @@ -328,7 +328,7 @@ Enable and configure experimental features. |------|---------| | object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-browser.js) in browsers | -Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. +Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented on [the js-ipfs config file doc](config.md). ###### Configuring Delegate Routers diff --git a/config.md b/config.md new file mode 100644 index 0000000000..fb50bb25b4 --- /dev/null +++ b/config.md @@ -0,0 +1,157 @@ +# The js-ipfs config file + +The js-ipfs config file is a JSON document, which is located in a repository +(by default located at ~/.jsipfs/config), where the repository location may be +changed according to the value of the $IPFS_PATH environment variable. +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. + +## Table of Contents + +- [`Addresses`](#addresses) +- [`Bootstrap`](#bootstrap) +- [`Datastore`](#datastore) +- [`Discovery`](#discovery) +- [`Identity`](#identity) +- [`Swarm`](#swarm) + + +## `Addresses` +Contains information about various listener addresses to be used by this node. + +- `API` +Multiaddr describing the address to serve the local HTTP API on. + +Default: `/ip4/127.0.0.1/tcp/5002` + +- `Gateway` +Multiaddr describing the address to serve the local gateway on. + +Default: `/ip4/127.0.0.1/tcp/9090` + +- `Swarm` +Array of multiaddrs describing which addresses to listen on for p2p swarm connections. + +Default: +```json +[ + "/ip4/0.0.0.0/tcp/4002", + "/ip4/127.0.0.1/tcp/4003/ws" +] +``` + +## `Bootstrap` +Bootstrap is an array of multiaddrs 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 (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](https://github.com/ipfs/ipfs-ds-convert) to migrate data into the new structures. + +For more information on possible values for this configuration option, see docs/datastores.md + +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` +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` +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. + +## `Swarm` + +Options for configuring the swarm. + +### `ConnMgr` + +The connection manager determines which and how many connections to keep and can be configured to keep. + +#### Basic Connection Manager + +- `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. + + +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. + +**Example:** + + +```json +{ + "Swarm": { + "ConnMgr": { + "LowWater": 100, + "HighWater": 200, + } + } +} +``` From 32863db6d86c006c5a9872574db73a1745088a60 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Tue, 16 Jul 2019 10:43:16 +0200 Subject: [PATCH 2/7] chore: address review --- README.md | 2 +- config.md | 26 ++++++++++++++++++++------ 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ba4808b2d7..c04ffb2475 100644 --- a/README.md +++ b/README.md @@ -328,7 +328,7 @@ Enable and configure experimental features. |------|---------| | object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-browser.js) in browsers | -Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented on [the js-ipfs config file doc](config.md). +Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented in [the js-ipfs config file doc](config.md). ###### Configuring Delegate Routers diff --git a/config.md b/config.md index fb50bb25b4..2170416a8e 100644 --- a/config.md +++ b/config.md @@ -1,11 +1,13 @@ # The js-ipfs config file -The js-ipfs config file is a JSON document, which is located in a repository -(by default located at ~/.jsipfs/config), where the repository location may be -changed according to the value of the $IPFS_PATH environment variable. -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. +The js-ipfs config file is a JSON document located in the root +directory of the js-ipfs repository (by default the js-ipfs +repository is located at `~/.jsipfs` and the config file is at +`~/.jsipfs/config`). The repository location may be changed with +the `$IPFS_PATH` environment variable. The config file is read once +when the js-ipfs daemon is started, or each time a command is +executed in offline mode. Commands that execute on a running daemon +do not read the config file at runtime. ## Table of Contents @@ -21,11 +23,18 @@ config file at runtime. 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](https://docs.ipfs.io/reference/api/http). + Multiaddr describing the address to serve the local HTTP API on. Default: `/ip4/127.0.0.1/tcp/5002` - `Gateway` +A gateway is exposed by the IPFS daemon, which allows an easy way to +access content from IPFS, using an IPFS path. + Multiaddr describing the address to serve the local gateway on. Default: `/ip4/127.0.0.1/tcp/9090` @@ -90,6 +99,9 @@ Default: 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` @@ -103,6 +115,8 @@ A number of seconds to wait between discovery checks. Default: `10` - `webRTCStar` +WebRTCStar is a discovery mechanism prvided by a signalling-star that allows peer-to-peer communications in the browser. + Options for webRTCstar peer discovery. - `Enabled` From 27919d695ff0b5e150ba6d4aafd52016bf23d660 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Tue, 16 Jul 2019 14:39:30 +0200 Subject: [PATCH 3/7] chore: address review --- config.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/config.md b/config.md index 2170416a8e..bd3c15124e 100644 --- a/config.md +++ b/config.md @@ -1,13 +1,6 @@ # The js-ipfs config file -The js-ipfs config file is a JSON document located in the root -directory of the js-ipfs repository (by default the js-ipfs -repository is located at `~/.jsipfs` and the config file is at -`~/.jsipfs/config`). The repository location may be changed with -the `$IPFS_PATH` environment variable. The config file is read once -when the js-ipfs daemon is started, or each time a command is -executed in offline mode. Commands that execute on a running daemon -do not read the config file at runtime. +The js-ipfs config file is a JSON document located in the root directory of the js-ipfs repository. ## Table of Contents From 4435871e64d94917439ef262a869b0918d496083 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Wed, 17 Jul 2019 12:18:48 +0200 Subject: [PATCH 4/7] chore: apply suggestions from code review Co-Authored-By: Alan Shaw --- README.md | 2 +- config.md | 164 -------------------------------------------------- doc/config.md | 163 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 164 insertions(+), 165 deletions(-) delete mode 100644 config.md create mode 100644 doc/config.md diff --git a/README.md b/README.md index c04ffb2475..5574991bf8 100644 --- a/README.md +++ b/README.md @@ -328,7 +328,7 @@ Enable and configure experimental features. |------|---------| | object | [`config-nodejs.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-nodejs.js) in Node.js, [`config-browser.js`](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/config-browser.js) in browsers | -Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented in [the js-ipfs config file doc](config.md). +Modify the default IPFS node config. This object will be *merged* with the default config; it will not replace it. The default config is documented in [the js-ipfs config file doc](doc/config.md). ###### Configuring Delegate Routers diff --git a/config.md b/config.md deleted file mode 100644 index bd3c15124e..0000000000 --- a/config.md +++ /dev/null @@ -1,164 +0,0 @@ -# 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 - -- [`Addresses`](#addresses) -- [`Bootstrap`](#bootstrap) -- [`Datastore`](#datastore) -- [`Discovery`](#discovery) -- [`Identity`](#identity) -- [`Swarm`](#swarm) - - -## `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](https://docs.ipfs.io/reference/api/http). - -Multiaddr describing the address to serve the local HTTP API on. - -Default: `/ip4/127.0.0.1/tcp/5002` - -- `Gateway` -A gateway is exposed by the IPFS daemon, which allows an easy way to -access content from IPFS, using an IPFS path. - -Multiaddr describing the address to serve the local gateway on. - -Default: `/ip4/127.0.0.1/tcp/9090` - -- `Swarm` -Array of multiaddrs describing which addresses to listen on for p2p swarm connections. - -Default: -```json -[ - "/ip4/0.0.0.0/tcp/4002", - "/ip4/127.0.0.1/tcp/4003/ws" -] -``` - -## `Bootstrap` -Bootstrap is an array of multiaddrs 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 (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](https://github.com/ipfs/ipfs-ds-convert) to migrate data into the new structures. - -For more information on possible values for this configuration option, see docs/datastores.md - -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 prvided 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. - -## `Swarm` - -Options for configuring the swarm. - -### `ConnMgr` - -The connection manager determines which and how many connections to keep and can be configured to keep. - -#### Basic Connection Manager - -- `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. - - -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. - -**Example:** - - -```json -{ - "Swarm": { - "ConnMgr": { - "LowWater": 100, - "HighWater": 200, - } - } -} -``` diff --git a/doc/config.md b/doc/config.md new file mode 100644 index 0000000000..62dcefc626 --- /dev/null +++ b/doc/config.md @@ -0,0 +1,163 @@ +# 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 + +- [`Addresses`](#addresses) +- [`Bootstrap`](#bootstrap) +- [`Datastore`](#datastore) +- [`Discovery`](#discovery) +- [`Identity`](#identity) +- [`Keychain`](#keychain) +- [`Swarm`](#swarm) + + +## `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](https://docs.ipfs.io/reference/api/http). + + [Multiaddr](https://github.com/multiformats/multiaddr/) or array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing the address(es) to serve the HTTP API on. + + Default: `/ip4/127.0.0.1/tcp/5002` + +- `Gateway` + A gateway is exposed by the IPFS daemon, which allows an easy way to access content from IPFS, using an IPFS path. + + [Multiaddr](https://github.com/multiformats/multiaddr/) or array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing the address(es) to serve the gateway on. + + Default: `/ip4/127.0.0.1/tcp/9090` + +- `Swarm` + Array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing which addresses to listen on for p2p swarm connections. + + Default: + ```json + [ + "/ip4/0.0.0.0/tcp/4002", + "/ip4/127.0.0.1/tcp/4003/ws" + ] + ``` + +## `Bootstrap` +Bootstrap is an array of [Multiaddr](https://github.com/multiformats/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](https://github.com/ipfs/ipfs-ds-convert) 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 prvided 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` + + + +## `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` + LowWater is the minimum number of connections to maintain. + + Default: 200 (both browser and node.js) + +- `HighWater` + HighWater is 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. + +**Example:** + + +```json +{ + "Swarm": { + "ConnMgr": { + "LowWater": 100, + "HighWater": 200, + } + } +} +``` From a85580c49e7443bb8115a3e279230ad45ec3185c Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 18 Jul 2019 11:52:09 +0200 Subject: [PATCH 5/7] chore: add delegates --- doc/config.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/config.md b/doc/config.md index 62dcefc626..eb43c86744 100644 --- a/doc/config.md +++ b/doc/config.md @@ -23,6 +23,16 @@ Contains information about various listener addresses to be used by this node. Default: `/ip4/127.0.0.1/tcp/5002` +- `Delegates` + Delegate peers are used to find peers and retrieve content from the network on your behalf. + + Array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing which addresses to use as delegate nodes, in order to create a delegate routers. + + Default: + ```json + [] + ``` + - `Gateway` A gateway is exposed by the IPFS daemon, which allows an easy way to access content from IPFS, using an IPFS path. From 31ffb3c6ec4b109cb4cb458a141db051153b674e Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Thu, 18 Jul 2019 12:22:35 +0200 Subject: [PATCH 6/7] chore: add keychain and update table of contents --- doc/config.md | 93 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 36 deletions(-) diff --git a/doc/config.md b/doc/config.md index eb43c86744..9b8faeee3f 100644 --- a/doc/config.md +++ b/doc/config.md @@ -5,13 +5,22 @@ The js-ipfs config file is a JSON document located in the root directory of the ## Table of Contents - [`Addresses`](#addresses) + - API + - Delegates + - Gateway + - Swarm - [`Bootstrap`](#bootstrap) - [`Datastore`](#datastore) + - [`Spec`](#spec) - [`Discovery`](#discovery) + - MDNS + - webRTCStar - [`Identity`](#identity) + - [`PeerID`](#peerid) + - [`PrivKey`](#privkey) - [`Keychain`](#keychain) - [`Swarm`](#swarm) - + - [`ConnMgr`](#connmgr) ## `Addresses` Contains information about various listener addresses to be used by this node. @@ -59,40 +68,40 @@ initiate a connection to the network. 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). +#### 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](https://github.com/ipfs/ipfs-ds-convert) to migrate data into the new structures. +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](https://github.com/ipfs/ipfs-ds-convert) to migrate data into the new structures. - Default: - ``` +Default: +```json +{ + "mounts": [ + { + "child": { + "path": "blocks", + "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2", + "sync": true, + "type": "flatfs" + }, + "mountpoint": "/blocks", + "prefix": "flatfs.datastore", + "type": "measure" + }, { - "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" }, - { - "child": { - "compression": "none", - "path": "datastore", - "type": "levelds" - }, - "mountpoint": "/", - "prefix": "leveldb.datastore", - "type": "measure" - } - ], - "type": "mount" + "mountpoint": "/", + "prefix": "leveldb.datastore", + "type": "measure" } - ``` + ], + "type": "mount" +} +``` ## `Discovery` Contains options for configuring IPFS node discovery mechanisms. @@ -124,21 +133,34 @@ Contains options for configuring IPFS node discovery mechanisms. ## `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. +#### 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. +#### PrivKey +The base64 encoded protobuf describing (and containing) the nodes private key. ## `Keychain` +We can customize the key management and criptographically 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: +```json +{ + "dek": { + "keyLength": 512/8, + "iterationCount": 1000, + "salt": "at least 16 characters long", + "hash": "sha2-512" + } +} +``` +You can check the [parameter choice for pbkdf2](https://cryptosense.com/parameter-choice-for-pbkdf2/) for more information. ## `Swarm` Options for configuring the swarm. -### `ConnMgr` +#### ConnMgr The connection manager determines which and how many connections to keep and can be configured to keep. @@ -160,7 +182,6 @@ The "basic" connection manager tries to keep between `LowWater` and `HighWater` **Example:** - ```json { "Swarm": { From 77da21b6355fe071a878ad61ac2b1390e4fb925d Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Thu, 18 Jul 2019 11:50:02 +0100 Subject: [PATCH 7/7] docs: formatting tweaks --- doc/config.md | 177 +++++++++++++++++++++++++++----------------------- 1 file changed, 95 insertions(+), 82 deletions(-) diff --git a/doc/config.md b/doc/config.md index 9b8faeee3f..b1df05db22 100644 --- a/doc/config.md +++ b/doc/config.md @@ -5,16 +5,16 @@ The js-ipfs config file is a JSON document located in the root directory of the ## Table of Contents - [`Addresses`](#addresses) - - API - - Delegates - - Gateway - - Swarm + - [`API`](#api) + - [`Delegates`](#delegates) + - [`Gateway`](#gateway) + - [`Swarm`](#swarm) - [`Bootstrap`](#bootstrap) - [`Datastore`](#datastore) - [`Spec`](#spec) - [`Discovery`](#discovery) - - MDNS - - webRTCStar + - [`MDNS`](#mdns) + - [`webRTCStar`](#webrtcstar) - [`Identity`](#identity) - [`PeerID`](#peerid) - [`PrivKey`](#privkey) @@ -25,50 +25,53 @@ The js-ipfs config file is a JSON document located in the root directory of the ## `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](https://docs.ipfs.io/reference/api/http). +### `API` - [Multiaddr](https://github.com/multiformats/multiaddr/) or array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing the address(es) to serve the HTTP API on. +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](https://docs.ipfs.io/reference/api/http). - Default: `/ip4/127.0.0.1/tcp/5002` +[Multiaddr](https://github.com/multiformats/multiaddr/) or array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing the address(es) to serve the HTTP API on. -- `Delegates` - Delegate peers are used to find peers and retrieve content from the network on your behalf. +Default: `/ip4/127.0.0.1/tcp/5002` - Array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing which addresses to use as delegate nodes, in order to create a delegate routers. +### `Delegates` - Default: - ```json - [] - ``` +Delegate peers are used to find peers and retrieve content from the network on your behalf. -- `Gateway` - A gateway is exposed by the IPFS daemon, which allows an easy way to access content from IPFS, using an IPFS path. +Array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing which addresses to use as delegate nodes. - [Multiaddr](https://github.com/multiformats/multiaddr/) or array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing the address(es) to serve the gateway on. +Default: `[]` - Default: `/ip4/127.0.0.1/tcp/9090` +### `Gateway` -- `Swarm` - Array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing which addresses to listen on for p2p swarm connections. +A gateway is exposed by the IPFS daemon, which allows an easy way to access content from IPFS, using an IPFS path. - Default: - ```json - [ - "/ip4/0.0.0.0/tcp/4002", - "/ip4/127.0.0.1/tcp/4003/ws" - ] - ``` +[Multiaddr](https://github.com/multiformats/multiaddr/) or array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing the address(es) to serve the gateway on. + +Default: `/ip4/127.0.0.1/tcp/9090` + +### `Swarm` + +Array of [Multiaddr](https://github.com/multiformats/multiaddr/) describing which addresses to listen on for p2p swarm connections. + +Default: +```json +[ + "/ip4/0.0.0.0/tcp/4002", + "/ip4/127.0.0.1/tcp/4003/ws" +] +``` ## `Bootstrap` + Bootstrap is an array of [Multiaddr](https://github.com/multiformats/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 +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](https://github.com/ipfs/ipfs-ds-convert) to migrate data into the new structures. @@ -76,70 +79,79 @@ This can be changed manually, however, if you make any changes that require a di Default: ```json { - "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" + "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. +### `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` - Options for Multicast DNS peer discovery. + A boolean value for whether or not MDNS should be active. + + Default: `true` - - `Enabled` - A boolean value for whether or not MDNS should be active. +- `Interval` - Default: `true` + A number of seconds to wait between discovery checks. + + Default: `10` - - `Interval` - A number of seconds to wait between discovery checks. +### `webRTCStar` - Default: `10` +WebRTCStar is a discovery mechanism prvided by a signalling-star that allows peer-to-peer communications in the browser. -- `webRTCStar` - WebRTCStar is a discovery mechanism prvided by a signalling-star that allows peer-to-peer communications in the browser. +Options for webRTCstar peer discovery: - Options for webRTCstar peer discovery. +- `Enabled` - - `Enabled` - A boolean value for whether or not webRTCStar should be active. + A boolean value for whether or not webRTCStar should be active. - Default: `true` + Default: `true` ## `Identity` -#### PeerID +### `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 +### `PrivKey` + The base64 encoded protobuf describing (and containing) the nodes private key. ## `Keychain` + We can customize the key management and criptographically 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: @@ -147,9 +159,9 @@ Default: { "dek": { "keyLength": 512/8, - "iterationCount": 1000, - "salt": "at least 16 characters long", - "hash": "sha2-512" + "iterationCount": 1000, + "salt": "at least 16 characters long", + "hash": "sha2-512" } } ``` @@ -160,20 +172,21 @@ You can check the [parameter choice for pbkdf2](https://cryptosense.com/paramete Options for configuring the swarm. -#### ConnMgr +### `ConnMgr` The connection manager determines which and how many connections to keep and can be configured to keep. - `LowWater` - LowWater is the minimum number of connections to maintain. - Default: 200 (both browser and node.js) + The minimum number of connections to maintain. + + Default: `200` (both browser and node.js) - `HighWater` - HighWater is the number of connections that, when exceeded, will trigger a connection GC operation. - Default: 500 (both browser and node.js) + 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: