doc(config): cleanup
Trying to make this a bit more consistent and structured. * Fix wrapping. * Use headings for all config values.
Steven Allen committed
Jan 30, 2020 at 22:13 UTC
bd8917facf0943231c9ab989c11f6d16ecb71f52
1 file changed
+209
-82
docs/config.md
+209
-82
@@ -38,7 +38,8 @@ Available profiles:
38
39
Replaces default datastore configuration with experimental badger datastore.
40
If you apply this profile after `ipfs init`, you will need to convert your
41
- datastore to the new configuration. You can do this using [ipfs-ds-convert](https://github.com/ipfs/ipfs-ds-convert)
41
+ datastore to the new configuration. You can do this using
42
+ [ipfs-ds-convert](https://github.com/ipfs/ipfs-ds-convert)
43
44
WARNING: badger datastore is experimental. Make sure to backup your data
45
frequently.
@@ -59,24 +60,69 @@ Available profiles:
60
## Table of Contents
61
62
- [`Addresses`](#addresses)
63
+ - [`Addresses.API`](#addressesapi)
64
+ - [`Addresses.Gateway`](#addressesgateway)
65
+ - [`Addresses.Swarm`](#addressesswarm)
66
+ - [`Addresses.Announce`](#addressesannounce)
67
+ - [`Addresses.NoAnnounce`](#addressesnoannounce)
68
- [`API`](#api)
69
+ - [`API.HTTPHeaders`](#apihttpheaders)
70
- [`Bootstrap`](#bootstrap)
71
- [`Datastore`](#datastore)
72
+ - [`Datastore.StorageMax`](#datastorestoragemax)
73
+ - [`Datastore.StorageGCWatermark`](#datastorestoragegcwatermark)
74
+ - [`Datastore.GCPeriod`](#datastoregcperiod)
75
+ - [`Datastore.HashOnRead`](#datastorehashonread)
76
+ - [`Datastore.BloomFilterSize`](#datastorebloomfiltersize)
77
+ - [`Datastore.Spec`](#datastorespec)
78
- [`Discovery`](#discovery)
79
+ - [`Discovery.MDNS`](#discoverymdns)
80
+ - [`Discovery.MDNS.Enabled`](#discoverymdnsenabled)
81
+ - [`Discovery.MDNS.Interval`](#discoverymdnsinterval)
82
- [`Routing`](#routing)
83
+ - [`Routing.Type`](#routingtype)
84
- [`Gateway`](#gateway)
85
+ - [`Gateway.NoFetch`](#gatewaynofetch)
86
+ - [`Gateway.HTTPHeaders`](#gatewayhttpheaders)
87
+ - [`Gateway.RootRedirect`](#gatewayrootredirect)
88
+ - [`Gateway.Writable`](#gatewaywritable)
89
+ - [`Gateway.PathPrefixes`](#gatewaypathprefixes)
90
- [`Identity`](#identity)
91
+ - [`Identity.PeerID`](#identitypeerid)
92
+ - [`Identity.PrivKey`](#identityprivkey)
93
- [`Ipns`](#ipns)
94
+ - [`Ipns.RepublishPeriod`](#ipnsrepublishperiod)
95
+ - [`Ipns.RecordLifetime`](#ipnsrecordlifetime)
96
+ - [`Ipns.ResolveCacheSize`](#ipnsresolvecachesize)
97
- [`Mounts`](#mounts)
98
+ - [`Mounts.IPFS`](#mountsipfs)
99
+ - [`Mounts.IPNS`](#mountsipns)
100
+ - [`Mounts.FuseAllowOther`](#mountsfuseallowother)
101
- [`Reprovider`](#reprovider)
102
+ - [`Reprovider.Interval`](#reproviderinterval)
103
+ - [`Reprovider.Strategy`](#reproviderstrategy)
104
- [`Swarm`](#swarm)
73
-- [`ConnMgr`](#connmgr)
105
+ - [`Swarm.AddrFilters`](#swarmaddrfilters)
106
+ - [`Swarm.DisableBandwidthMetrics`](#swarmdisablebandwidthmetrics)
107
+ - [`Swarm.DisableNatPortMap`](#swarmdisablenatportmap)
108
+ - [`Swarm.DisableRelay`](#swarmdisablerelay)
109
+ - [`Swarm.EnableRelayHop`](#swarmenablerelayhop)
110
+ - [`Swarm.EnableAutoRelay`](#swarmenableautorelay)
111
+ - [`Swarm.EnableAutoNATService`](#swarmenableautonatservice)
112
+ - [`Swarm.ConnMgr`](#swarmconnmgr)
113
+ - [`Swarm.ConnMgr.Type`](#swarmconnmgrtype)
114
+ - [`Swarm.ConnMgr.LowWater`](#swarmconnmgrlowwater)
115
+ - [`Swarm.ConnMgr.HighWater`](#swarmconnmgrhighwater)
116
+ - [`Swarm.ConnMgr.GracePeriod`](#swarmconnmgrgraceperiod)
117
118
## `Addresses`
119
+
120
Contains information about various listener addresses to be used by this node.
121
78
-- `API`
79
-Multiaddr or array of multiaddrs describing the address to serve the local HTTP API on.
122
+### `Addresses.API`
123
+
124
+Multiaddr or array of multiaddrs describing the address to serve the local HTTP
125
+API on.
126
127
Supported Transports:
128
@@ -85,8 +131,10 @@ Supported Transports:
131
132
Default: `/ip4/127.0.0.1/tcp/5001`
133
88
-- `Gateway`
89
-Multiaddr or array of multiaddrs describing the address to serve the local gateway on.
134
+### `Addresses.Gateway`
135
+
136
+Multiaddr or array of multiaddrs describing the address to serve the local
137
+gateway on.
138
139
Supported Transports:
140
@@ -95,8 +143,10 @@ Supported Transports:
143
144
Default: `/ip4/127.0.0.1/tcp/8080`
145
98
-- `Swarm`
99
-Array of multiaddrs describing which addresses to listen on for p2p swarm connections.
146
+### `Addresses.Swarm`
147
+
148
+Array of multiaddrs describing which addresses to listen on for p2p swarm
149
+connections.
150
151
Supported Transports:
152
@@ -112,12 +162,14 @@ Default:
162
]
163
```
164
115
-- `Announce`
116
-If non-empty, this array specifies the swarm addresses to announce to the network. If empty, the daemon will announce inferred swarm addresses.
165
+### `Addresses.Announce`
166
+
167
+If non-empty, this array specifies the swarm addresses to announce to the
168
+network. If empty, the daemon will announce inferred swarm addresses.
169
170
Default: `[]`
171
120
-- `NoAnnounce`
172
+### `Addresses.NoAnnounce`
173
Array of swarm addresses not to announce to the network.
174
175
Default: `[]`
@@ -125,7 +177,7 @@ Default: `[]`
177
## `API`
178
Contains information used by the API gateway.
179
128
-- `HTTPHeaders`
180
+### `API.HTTPHeaders`
181
Map of HTTP headers to set on responses from the API HTTP server.
182
183
Example:
@@ -138,57 +190,78 @@ Example:
190
Default: `null`
191
192
## `Bootstrap`
193
+
194
Bootstrap is an array of multiaddrs of trusted nodes to connect to in order to
195
initiate a connection to the network.
196
197
Default: The ipfs.io bootstrap nodes
198
199
## `Datastore`
200
+
201
Contains information related to the construction and operation of the on-disk
202
storage system.
203
150
-- `StorageMax`
204
+### `Datastore.StorageMax`
205
+
206
A soft upper limit for the size of the ipfs repository's datastore. With `StorageGCWatermark`,
207
is used to calculate whether to trigger a gc run (only if `--enable-gc` flag is set).
208
209
Default: `10GB`
210
156
-- `StorageGCWatermark`
211
+### `Datastore.StorageGCWatermark`
212
+
213
The percentage of the `StorageMax` value at which a garbage collection will be
214
triggered automatically if the daemon was run with automatic gc enabled (that
215
option defaults to false currently).
216
217
Default: `90`
218
163
-- `GCPeriod`
219
+### `Datastore.GCPeriod`
220
+
221
A time duration specifying how frequently to run a garbage collection. Only used
222
if automatic gc is enabled.
223
224
Default: `1h`
225
169
-- `HashOnRead`
226
+### `Datastore.HashOnRead`
227
+
228
A boolean value. If set to true, all block reads from disk will be hashed and
229
verified. This will cause increased CPU utilization.
230
231
Default: `false`
232
175
-- `BloomFilterSize`
176
-A number representing the size in bytes of the blockstore's [bloom filter](https://en.wikipedia.org/wiki/Bloom_filter). A value of zero represents the feature being disabled.
233
+### `Datastore.BloomFilterSize`
234
178
-This site generates useful graphs for various bloom filter values: <https://hur.st/bloomfilter/?n=1e6&p=0.01&m=&k=7>
179
-You may use it to find a preferred optimal value, where `m` is `BloomFilterSize` in bits. Remember to convert the value `m` from bits, into bytes for use as `BloomFilterSize` in the config file.
180
-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.
181
-As of writing, [7 hash functions](https://github.com/ipfs/go-ipfs-blockstore/blob/547442836ade055cc114b562a3cc193d4e57c884/caching.go#L22) are used, so the constant `k` is 7 in the formula.
235
+A number representing the size in bytes of the blockstore's [bloom
236
+filter](https://en.wikipedia.org/wiki/Bloom_filter). A value of zero represents
237
+the feature being disabled.
238
+
239
+This site generates useful graphs for various bloom filter values:
240
+<https://hur.st/bloomfilter/?n=1e6&p=0.01&m=&k=7> You may use it to find a
241
+preferred optimal value, where `m` is `BloomFilterSize` in bits. Remember to
242
+convert the value `m` from bits, into bytes for use as `BloomFilterSize` in the
243
+config file. For example, for 1,000,000 blocks, expecting a 1% false positive
244
+rate, you'd end up with a filter size of 9592955 bits, so for `BloomFilterSize`
245
+we'd want to use 1199120 bytes. As of writing, [7 hash
246
+functions](https://github.com/ipfs/go-ipfs-blockstore/blob/547442836ade055cc114b562a3cc193d4e57c884/caching.go#L22)
247
+are used, so the constant `k` is 7 in the formula.
248
249
250
Default: `0`
251
186
-- `Spec`
187
-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).
252
+### `Datastore.Spec`
253
+
254
+Spec defines the structure of the ipfs datastore. It is a composable structure,
255
+where each datastore is represented by a json object. Datastores can wrap other
256
+datastores to provide extra functionality (eg metrics, logging, or caching).
257
189
-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.
258
+This can be changed manually, however, if you make any changes that require a
259
+different on-disk structure, you will need to run the [ipfs-ds-convert
260
+tool](https://github.com/ipfs/ipfs-ds-convert) to migrate data into the new
261
+structures.
262
191
-For more information on possible values for this configuration option, see docs/datastores.md
263
+For more information on possible values for this configuration option, see
264
+docs/datastores.md
265
266
Default:
267
```
@@ -221,25 +294,33 @@ Default:
294
```
295
296
## `Discovery`
297
+
298
Contains options for configuring ipfs node discovery mechanisms.
299
226
-- `MDNS`
300
+### `Discovery.MDNS`
301
+
302
Options for multicast dns peer discovery.
303
229
- - `Enabled`
304
+#### `Discovery.MDNS.Enabled`
305
+
306
A boolean value for whether or not mdns should be active.
307
308
Default: `true`
309
234
- - `Interval`
235
-A number of seconds to wait between discovery checks.
310
+#### `Discovery.MDNS.Interval`
311
312
+A number of seconds to wait between discovery checks.
313
314
## `Routing`
315
+
316
Contains options for content routing mechanisms.
317
241
-- `Type`
242
-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.
318
+### `Routing.Type`
319
+
320
+Content routing mode. Can be overridden with daemon `--routing` flag. When set
321
+to `dhtclient`, the node won't join the DHT but can still use it to find
322
+content.
323
+
324
Valid modes are:
325
- `dht` (default)
326
- `dhtclient`
@@ -257,15 +338,18 @@ Valid modes are:
338
339
340
## `Gateway`
341
+
342
Options for the HTTP gateway.
343
262
-- `NoFetch`
344
+### `Gateway.NoFetch`
345
+
346
When set to true, the gateway will only serve content already in the local repo
347
and will not fetch files from the network.
348
349
Default: `false`
350
268
-- `HTTPHeaders`
351
+### `Gateway.HTTPHeaders`
352
+
353
Headers to set on gateway responses.
354
355
Default:
@@ -283,20 +367,27 @@ Default:
367
}
368
```
369
286
-- `RootRedirect`
370
+### `Gateway.RootRedirect`
371
+
372
A url to redirect requests for `/` to.
373
374
Default: `""`
375
291
-- `Writable`
376
+### `Gateway.Writable`
377
+
378
A boolean to configure whether the gateway is writeable or not.
379
380
Default: `false`
381
296
-- `PathPrefixes`
297
-Array of acceptable url paths that a client can specify in X-Ipfs-Path-Prefix header.
382
299
-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.
383
+### `Gateway.PathPrefixes`
384
+
385
+Array of acceptable url paths that a client can specify in X-Ipfs-Path-Prefix
386
+header.
387
+
388
+The X-Ipfs-Path-Prefix header is used to specify a base path to prepend to links
389
+in directory listings and for trailing-slash redirects. It is intended to be set
390
+by a frontend http proxy like nginx.
391
392
Example: We mount `blog.ipfs.io` (a dnslink page) at `ipfs.io/blog`.
393
@@ -320,46 +411,57 @@ Default: `[]`
411
412
## `Identity`
413
323
-- `PeerID`
414
+### `Identity.PeerID`
415
+
416
The unique PKI identity label for this configs peer. Set on init and never read,
417
its merely here for convenience. Ipfs will always generate the peerID from its
418
keypair at runtime.
419
328
-- `PrivKey`
420
+### `Identity.PrivKey`
421
+
422
The base64 encoded protobuf describing (and containing) the nodes private key.
423
424
## `Ipns`
425
333
-- `RepublishPeriod`
426
+### `Ipns.RepublishPeriod`
427
+
428
A time duration specifying how frequently to republish ipns records to ensure
429
they stay fresh on the network. If unset, we default to 4 hours.
430
337
-- `RecordLifetime`
431
+### `Ipns.RecordLifetime`
432
+
433
A time duration specifying the value to set on ipns records for their validity
434
lifetime.
435
+
436
If unset, we default to 24 hours.
437
342
-- `ResolveCacheSize`
438
+### `Ipns.ResolveCacheSize`
439
+
440
The number of entries to store in an LRU cache of resolved ipns entries. Entries
441
will be kept cached until their lifetime is expired.
442
443
Default: `128`
444
445
## `Mounts`
446
+
447
FUSE mount point configuration options.
448
351
-- `IPFS`
449
+### `Mounts.IPFS`
450
+
451
Mountpoint for `/ipfs/`.
452
354
-- `IPNS`
453
+### `Mounts.IPNS`
454
+
455
Mountpoint for `/ipns/`.
456
357
-- `FuseAllowOther`
457
+### `Mounts.FuseAllowOther`
458
+
459
Sets the FUSE allow other option on the mountpoint.
460
461
## `Reprovider`
462
362
-- `Interval`
463
+### `Reprovider.Interval`
464
+
465
Sets the time between rounds of reproviding local content to the routing
466
system. If unset, it defaults to 12 hours. If set to the value `"0"` it will
467
disable content reproviding.
@@ -369,7 +471,8 @@ not being able to discover that you have the objects that you have. If you want
471
to have this disabled and keep the network aware of what you have, you must
472
manually announce your content periodically.
473
372
-- `Strategy`
474
+### `Reprovider.Strategy`
475
+
476
Tells reprovider what should be announced. Valid strategies are:
477
- "all" (default) - announce all stored data
478
- "pinned" - only announce pinned data
@@ -379,13 +482,14 @@ Tells reprovider what should be announced. Valid strategies are:
482
483
Options for configuring the swarm.
484
382
-- `AddrFilters`
383
-An array of addresses (multiaddr netmasks) to not dial. By default, IPFS nodes advertise
384
-_all_ addresses, even internal ones. This makes it easier for nodes on the same
385
-network to reach each other. Unfortunately, this means that an IPFS node will
386
-try to connect to one or more private IP addresses whenever dialing another
387
-node, even if this other node is on a different network. This may may trigger
388
-netscan alerts on some hosting providers or cause strain in some setups.
485
+### `Swarm.AddrFilters`
486
+
487
+An array of addresses (multiaddr netmasks) to not dial. By default, IPFS nodes
488
+advertise _all_ addresses, even internal ones. This makes it easier for nodes on
489
+the same network to reach each other. Unfortunately, this means that an IPFS
490
+node will try to connect to one or more private IP addresses whenever dialing
491
+another node, even if this other node is on a different network. This may may
492
+trigger netscan alerts on some hosting providers or cause strain in some setups.
493
494
The `server` configuration profile fills up this list with sensible defaults,
495
preventing dials to all non-routable IP addresses (e.g., `192.168.0.0/16`) but
@@ -393,12 +497,14 @@ you should always check settings against your own network and/or hosting
497
provider.
498
499
396
-- `DisableBandwidthMetrics`
500
+### `Swarm.DisableBandwidthMetrics`
501
+
502
A boolean value that when set to true, will cause ipfs to not keep track of
503
bandwidth metrics. Disabling bandwidth metrics can lead to a slight performance
504
improvement, as well as a reduction in memory usage.
505
401
-- `DisableNatPortMap`
506
+### `Swarm.DisableNatPortMap`
507
+
508
Disable automatic NAT port forwarding.
509
510
When not disabled (default), go-ipfs asks NAT devices (e.g., routers), to open
@@ -406,51 +512,72 @@ up an external port and forward it to the port go-ipfs is running on. When this
512
works (i.e., when your router supports NAT port forwarding), it makes the local
513
go-ipfs node accessible from the public internet.
514
409
-- `DisableRelay`
515
+### `Swarm.DisableRelay`
516
+
517
Disables the p2p-circuit relay transport.
518
412
-- `EnableRelayHop`
413
-Enables HOP relay for the node. If this is enabled, the node will act as
414
-an intermediate (Hop Relay) node in relay circuits for connected peers.
519
+### `Swarm.EnableRelayHop`
520
+
521
+Enables HOP relay for the node.
522
+
523
+If this is enabled, the node will act as an intermediate (Hop Relay) node in
524
+relay circuits for connected peers.
525
+
526
+### `Swarm.EnableAutoRelay`
527
416
-- `EnableAutoRelay`
528
Enables automatic relay for this node.
418
-If the node is a HOP relay (`EnableRelayHop` is true) then it will advertise itself as a relay through the DHT.
419
-Otherwise, the node will test its own NAT situation (dialability) using passively discovered AutoNAT services.
420
-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.
529
422
-- `EnableAutoNATService`
530
+If the node is a HOP relay (`EnableRelayHop` is true) then it will advertise
531
+itself as a relay through the DHT. Otherwise, the node will test its own NAT
532
+situation (dialability) using passively discovered AutoNAT services. If the node
533
+is not publicly reachable, then it will seek HOP relays advertised through the
534
+DHT and override its public address(es) with relay addresses.
535
+
536
+### `Swarm.EnableAutoNATService`
537
+
538
Enables the AutoNAT service for this node.
424
-The service allows peers to discover their NAT situation by requesting dial backs to their public addresses.
425
-This should only be enabled on publicly reachable nodes.
539
427
-### `ConnMgr`
540
+The service allows peers to discover their NAT situation by requesting dial
541
+backs to their public addresses. This should only be enabled on publicly
542
+reachable nodes.
543
429
-The connection manager determines which and how many connections to keep and can be configured to keep.
544
+### `Swarm.ConnMgr`
545
431
-- `Type`
432
-Sets the type of connection manager to use, options are: `"none"` (no connection management) and `"basic"`.
546
+The connection manager determines which and how many connections to keep and can
547
+be configured to keep.
548
+
549
+#### `Swarm.ConnMgr.Type`
550
+
551
+Sets the type of connection manager to use, options are: `"none"` (no connection
552
+management) and `"basic"`.
553
554
#### Basic Connection Manager
555
436
-- `LowWater`
556
+##### `Swarm.ConnMgr.LowWater`
557
+
558
LowWater is the minimum number of connections to maintain.
559
439
-- `HighWater`
440
-HighWater is the number of connections that, when exceeded, will trigger a connection GC operation.
560
+##### `Swarm.ConnMgr.HighWater`
561
442
-- `GracePeriod`
443
-GracePeriod is a time duration that new connections are immune from being closed by the connection manager.
562
+HighWater is the number of connections that, when exceeded, will trigger a
563
+connection GC operation.
564
445
-The "basic" connection manager tries to keep between `LowWater` and `HighWater` connections. It works by:
565
+##### `Swarm.ConnMgr.GracePeriod`
566
+
567
+GracePeriod is a time duration that new connections are immune from being closed
568
+by the connection manager.
569
+
570
+The "basic" connection manager tries to keep between `LowWater` and `HighWater`
571
+connections. It works by:
572
573
1. Keeping all connections until `HighWater` connections is reached.
448
-2. Once `HighWater` is reached, it closes connections until `LowWater` is reached.
449
-3. To prevent thrashing, it never closes connections established within the `GracePeriod`.
574
+2. Once `HighWater` is reached, it closes connections until `LowWater` is
575
+ reached.
576
+3. To prevent thrashing, it never closes connections established within the
577
+ `GracePeriod`.
578
579
**Example:**
580
453
-
581
```json
582
{
583
"Swarm": {