Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: update go-ipfs docs for 0.5.0 release #7229

Merged
merged 4 commits into from
Apr 28, 2020
Merged

doc: update go-ipfs docs for 0.5.0 release #7229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4ebe7e6
doc: fixup config docs
Stebalien Apr 27, 2020
fa3f450
docs(datastore): fixup some notes on sync safety
Stebalien Apr 27, 2020
6d7d3ef
doc: expand on relay documentation
Stebalien Apr 27, 2020
4c663bc
feat: update experimental documentations for 0.5.0 release
Stebalien Apr 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
123 changes: 88 additions & 35 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,50 +12,82 @@ 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:
The available configuration profiles are listed below. You can also find them
documented in `ipfs config profile --help`.

- `server`

Recommended for nodes with public IPv4 address (servers, VPSes, etc.),
disables host and content discovery in local networks.
Disables local host discovery, recommended when
running IPFS on machines with public IPv4 addresses.

- `randomports`

Use a random port number for swarm.

- `default-datatore`

Configures the node to use the default datastore (flatfs).

Read the "flatfs" profile description for more information on this datastore.

This profile may only be applied when first initializing the node.

- `local-discovery`

Sets default values to fields affected by `server` profile, enables
discovery in local networks.
Sets default values to fields affected by the 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.
Reduces external interference of IPFS daemon, this
is useful when using the daemon in test environments.

- `default-networking`

Restores default network settings. Inverse profile of the `test` profile.
Restores default network settings.
Inverse profile of the test profile.

- `badgerds`
- `flatfs`

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](https://github.com/ipfs/ipfs-ds-convert)
Configures the node to use the flatfs datastore.

WARNING: badger datastore is experimental. Make sure to backup your data
frequently.
This is the most battle-tested and reliable datastore, but it's significantly
slower than the badger datastore. You should use this datastore if:

- `default-datastore`
- You need a very simple and very reliable datastore you and trust your
filesystem. This datastore stores each block as a separate file in the
underlying filesystem so it's unlikely to loose data unless there's an issue
with the underlying file system.
- You need to run garbage collection on a small (<= 10GiB) datastore. The
default datastore, badger, can leave several gigabytes of data behind when
garbage collecting.
- You're concerned about memory usage. In its default configuration, badger can
use up to several gigabytes of memory.

Restores default datastore configuration.
This profile may only be applied when first initializing the node.

- `lowpower`

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

Configures the node to use the badger datastore.

- `randomports`
This is the fastest datastore. Use this datastore if performance, especially
when adding many gigabytes of files, is critical. However:

- This datastore will not properly reclaim space when your datastore is
smaller than several gigabytes. If you run IPFS with '--enable-gc' (you have
enabled block-level garbage collection), you plan on storing very little data in
your IPFS node, and disk usage is more critical than performance, consider using
flatfs.
- This datastore uses up to several gigabytes of memory.

This profile may only be applied when first initializing the node.

- `lowpower`

Generate random port for swarm.
Reduces daemon overhead on the system. May affect node
functionality - performance of content discovery and data
fetching may be degraded.

## Table of Contents

Expand All @@ -67,6 +99,12 @@ Available profiles:
- [`Addresses.NoAnnounce`](#addressesnoannounce)
- [`API`](#api)
- [`API.HTTPHeaders`](#apihttpheaders)
- [`AutoNAT`](#autonat)
- [`AutoNAT.ServiceMode`](#autonatservicemode)
- [`AutoNAT.Throttle`](#autonatthrottle)
- [`AutoNAT.Throttle.GlobalLimit`](#autonatthrottlegloballimit)
- [`AutoNAT.Throttle.PeerLimit`](#autonatthrottlepeerlimit)
- [`AutoNAT.Throttle.Interval`](#autonatthrottleinterval)
- [`Bootstrap`](#bootstrap)
- [`Datastore`](#datastore)
- [`Datastore.StorageMax`](#datastorestoragemax)
Expand All @@ -89,7 +127,6 @@ Available profiles:
- [`Gateway.Writable`](#gatewaywritable)
- [`Gateway.PathPrefixes`](#gatewaypathprefixes)
- [`Gateway.PublicGateways`](#gatewaypublicgateways)
- [`Gateway` recipes](#gateway-recipes)
- [`Identity`](#identity)
- [`Identity.PeerID`](#identitypeerid)
- [`Identity.PrivKey`](#identityprivkey)
Expand All @@ -111,7 +148,6 @@ Available profiles:
- [`Swarm.DisableRelay`](#swarmdisablerelay)
- [`Swarm.EnableRelayHop`](#swarmenablerelayhop)
- [`Swarm.EnableAutoRelay`](#swarmenableautorelay)
- [`Swarm.EnableAutoNATService`](#swarmenableautonatservice)
- [`Swarm.ConnMgr`](#swarmconnmgr)
- [`Swarm.ConnMgr.Type`](#swarmconnmgrtype)
- [`Swarm.ConnMgr.LowWater`](#swarmconnmgrlowwater)
Expand Down Expand Up @@ -720,24 +756,41 @@ go-ipfs node accessible from the public internet.

### `Swarm.DisableRelay`

Disables the p2p-circuit relay transport.
Disables the p2p-circuit relay transport. This will prevent this node from
connecting to nodes behind relays, or accepting connections from nodes behind
relays.

### `Swarm.EnableRelayHop`

Enables HOP relay for the node.
Configures this node to act as a relay "hop". A relay "hop" relays traffic for other peers.

If this is enabled, the node will act as an intermediate (Hop Relay) node in
relay circuits for connected peers.
WARNING: Do not enable this option unless you know what you're doing. Other
peers will randomly decide to use your node as a relay and consume _all_
available bandwidth. There is _no_ rate-limiting.

### `Swarm.EnableAutoRelay`

Enables automatic relay for this node.
Enables "automatic relay" mode for this node. This option does two _very_
different things based on the `Swarm.EnableRelayHop`. See
[#7228](https://github.com/ipfs/go-ipfs/issues/7228) for context.

#### Mode 1: `EnableRelayHop` is `false`

If `Swarm.EnableAutoRelay` is enabled and `Swarm.EnableRelayHop` is disabled,
your node will automatically _use_ public relays from the network if it detects
that it cannot be reached from the public internet (e.g., it's behind a
firewall). This is likely the feature you're looking for.

If you enable `EnableAutoRelay`, you should almost certainly disable
`EnableRelayHop`.

#### Mode 2: `EnableRelayHop` is `true`

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.
If `EnableAutoRelay` is enabled and `EnableRelayHop` is enabled, your node will
_act_ as a public relay for the network. Furthermore, in addition to simply
relaying traffic, your node will advertise itself as a public relay. Unless you
have the bandwidth of a small ISP, do not enable both of these options at the
same time.

### `Swarm.EnableAutoNATService`

Expand Down
11 changes: 7 additions & 4 deletions docs/datastores.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ This document describes the different possible values for the `Datastore.Spec`
field in the ipfs configuration file.

## flatfs

Stores each key value pair as a file on the filesystem.

The shardFunc is prefixed with `/repo/flatfs/shard/v1` then followed by a descriptor of the sharding strategy. Some example values are:
Expand All @@ -21,8 +22,7 @@ The shardFunc is prefixed with `/repo/flatfs/shard/v1` then followed by a descri
}
```

NOTE: flatfs should only be used as a block store (mounted at `/blocks`) as the
current implementation is not complete.
NOTE: flatfs must only be used as a block store (mounted at `/blocks`) as it only partially implements the datastore interface. You can mount flatfs for /blocks only using the mount datastore (described below).

## levelds
Uses a leveldb database to store key value pairs.
Expand All @@ -36,10 +36,11 @@ Uses a leveldb database to store key value pairs.
```

## badgerds

Uses [badger](https://github.com/dgraph-io/badger) as a key value store.

* `syncWrites`: Flush every write to disk before continuing. Disabling this option may leave your datastore in an inconsistent state after a crash.
* `truncate`: Truncate the DB if a partially written sector is found (defaults to true). This only happens if a IPFS crashes half-way through a write so this option is usually safe to leave on.
* `syncWrites`: Flush every write to disk before continuing. Setting this to false is safe as go-ipfs will automatically flush writes to disk before and after performing critical operations like pinning. However, you can set this to true to be extra-safe (at the cost of a 2-3x slowdown when adding files).
* `truncate`: Truncate the DB if a partially written sector is found (defaults to true). There is no good reason to set this to false unless you want to manually recover partially written (and unpinned) blocks if go-ipfs crashes half-way through a adding a file.

```json
{
Expand All @@ -51,6 +52,7 @@ Uses [badger](https://github.com/dgraph-io/badger) as a key value store.
```

## mount

Allows specified datastores to handle keys prefixed with a given path.
The mountpoints are added as keys within the child datastore definitions.

Expand All @@ -71,6 +73,7 @@ The mountpoints are added as keys within the child datastore definitions.
```

## measure

This datastore is a wrapper that adds metrics tracking to any datastore.

```json
Expand Down