document circuit relay in docs/experimental-features
License: MIT Signed-off-by: vyzo <vyzo@hackzen.org>
vyzo committed
Aug 17, 2017 at 11:45 UTC
ad772e5df9d6da395929331c71212b0fa06adf44
1 file changed
+53
docs/experimental-features.md
+53
@@ -17,6 +17,7 @@ you MUST please make a PR updating this document, and link the PR in the above i
17
- [ipfs filestore](#ipfs-filestore)
18
- [Private Networks](#private-networks)
19
- [ipfs p2p](#ipfs-p2p)
20
+- [Circuit Relay](#circuit-relay)
21
22
---
23
@@ -212,3 +213,55 @@ Basic usage:
213
- [ ] Needs more people to use and report on how well it works / fits use cases
214
- [ ] More documentation
215
- [ ] Support other protocols
216
+
217
+---
218
+
219
+## Circuit Relay
220
+
221
+Allows peers to connect through an intermediate relay node when there
222
+is no direct connectivity.
223
+
224
+### State
225
+Experimental
226
+
227
+### In Version
228
+master
229
+
230
+### How to enable
231
+
232
+The relay transport is enabled by default, which allows peers to dial
233
+through relay and listens for incoming relay connections.
234
+The transport can be disabled by setting `Swarm.DisableRelay = true` in
235
+the configuration.
236
+
237
+By default, peers don't act as intermediate nodes (relays). This can
238
+be enabled by setting `Swarm.EnableRelayHop = true` in the configuration.
239
+Note that the option needs to be set before online services are started
240
+to have an effect; an already online node would have to be restarted.
241
+
242
+### Basic Usage:
243
+
244
+In order to connect peers QmA and QmB through a relay node QmRelay:
245
+
246
+- Both peers should connect to the relay:
247
+`ipfs swarm connect /transport/address/ipfs/QmRelay`
248
+- Peer QmA can then connect to peer QmB using the relay:
249
+`ipfs swarm connect /ipfs/QmRelay/p2p-cricuit/ipfs/QmB`
250
+
251
+Peers can also connect with an unspecific relay address, which will
252
+try to dial through known relays:
253
+`ipfs swarm connect /p2p-circuit/ipfs/QmB`
254
+
255
+Peers can see their (unspecific) relay address in the output of
256
+`ipfs swarm addrs listen`
257
+
258
+### Road to being a real feature
259
+
260
+- [ ] Needs more people to use it and report on how well it works.
261
+- [ ] Advertise relay addresses to the DHT for NATed or otherwise
262
+ unreachable peers.
263
+- [ ] Active relay discovery for specific relay address advertisement.
264
+ We would like advertised relay addresses to designate specific relays
265
+ for efficient dialing.
266
+- [ ] Dialing priorities for relay addresses; arguably, relay addresses
267
+ should have lower priority than direct dials.