doc: expand on relay documentation
Steven Allen committed
Apr 27, 2020 at 16:00 UTC
6d7d3ef30ecfb892d599d5325947089fe67bfeea
1 file changed
+27
-10
docs/config.md
+27
-10
@@ -756,24 +756,41 @@ go-ipfs node accessible from the public internet.
756
757
### `Swarm.DisableRelay`
758
759
-Disables the p2p-circuit relay transport.
759
+Disables the p2p-circuit relay transport. This will prevent this node from
760
+connecting to nodes behind relays, or accepting connections from nodes behind
761
+relays.
762
763
### `Swarm.EnableRelayHop`
764
763
-Enables HOP relay for the node.
765
+Configures this node to act as a relay "hop". A relay "hop" relays traffic for other peers.
766
765
-If this is enabled, the node will act as an intermediate (Hop Relay) node in
766
-relay circuits for connected peers.
767
+WARNING: Do not enable this option unless you know what you're doing. Other
768
+peers will randomly decide to use your node as a relay and consume _all_
769
+available bandwidth. There is _no_ rate-limiting.
770
771
### `Swarm.EnableAutoRelay`
772
770
-Enables automatic relay for this node.
773
+Enables "automatic relay" mode for this node. This option does two _very_
774
+different things based on the `Swarm.EnableRelayHop`. See
775
+[#7228](https://github.com/ipfs/go-ipfs/issues/7228) for context.
776
772
-If the node is a HOP relay (`EnableRelayHop` is true) then it will advertise
773
-itself as a relay through the DHT. Otherwise, the node will test its own NAT
774
-situation (dialability) using passively discovered AutoNAT services. If the node
775
-is not publicly reachable, then it will seek HOP relays advertised through the
776
-DHT and override its public address(es) with relay addresses.
777
+#### Mode 1: `EnableRelayHop` is `false`
778
+
779
+If `Swarm.EnableAutoRelay` is enabled and `Swarm.EnableRelayHop` is disabled,
780
+your node will automatically _use_ public relays from the network if it detects
781
+that it cannot be reached from the public internet (e.g., it's behind a
782
+firewall). This is likely the feature you're looking for.
783
+
784
+If you enable `EnableAutoRelay`, you should almost certainly disable
785
+`EnableRelayHop`.
786
+
787
+#### Mode 2: `EnableRelayHop` is `true`
788
+
789
+If `EnableAutoRelay` is enabled and `EnableRelayHop` is enabled, your node will
790
+_act_ as a public relay for the network. Furthermore, in addition to simply
791
+relaying traffic, your node will advertise itself as a public relay. Unless you
792
+have the bandwidth of a small ISP, do not enable both of these options at the
793
+same time.
794
795
### `Swarm.EnableAutoNATService`
796