doc: expand on peering service documentation
* Explain _why_ it exists. * Explain how it can be used.
Steven Allen committed
May 25, 2020 at 19:11 UTC
7990d2ccb51c0c9ea205e07b37e21330e3189ad3
1 file changed
+33
-3
docs/config.md
+33
-3
@@ -709,9 +709,39 @@ Default: `false`
709
### `Peering`
710
711
Configures the peering subsystem. The peering subsystem configures go-ipfs to
712
-connect to, remain connected to, and reconnect to a set of peers. Peers should
713
-use this subsystem to create "sticky" links between frequently used peers for
714
-improved reliability.
712
+connect to, remain connected to, and reconnect to a set of nodes. Nodes should
713
+use this subsystem to create "sticky" links between frequently useful peers to
714
+improve reliability.
715
+
716
+Use-cases:
717
+
718
+* An IPFS gateway connected to an IPFS cluster should peer to ensure that the
719
+ gateway can always fetch content from the cluster.
720
+* A dapp may peer embedded go-ipfs nodes with a set of pinning services or
721
+ textile cafes/hubs.
722
+* A set of friends may peer to ensure that they can always fetch each other's
723
+ content.
724
+
725
+When a node is added to the set of peered nodes, go-ipfs will:
726
+
727
+1. Protect connections to this node from the connection manager. That is,
728
+ go-ipfs will never automatically close the connection to this node and
729
+ connections to this node will not count towards the connection limit.
730
+2. Connect to this node on startup.
731
+3. Repeatedly try to reconnect to this node if the last connection dies or the
732
+ node goes offline. This repeated re-connect logic is governed by a randomized
733
+ exponential backoff delay ranging from ~5 seconds to ~10 minutes to avoid
734
+ repeatedly reconnect to a node that's offline.
735
+
736
+Peering can be asymmetric or symmetric:
737
+
738
+* When symmetric, the connection will be protected by both nodes and will likely
739
+ be vary stable.
740
+* When asymmetric, only one node (the node that configured peering) will protect
741
+ the connection and attempt to re-connect to the peered node on disconnect. If
742
+ the peered node is under heavy load and/or has a low connection limit, the
743
+ connection may flap repeatedly. Be careful when asymmetrically peering to not
744
+ overload peers.
745
746
#### `Peering.Peers`
747