improve the documentation for the p2p feature
License: MIT Signed-off-by: Steven Allen <steven@stebalien.com>
Steven Allen committed
Mar 28, 2018 at 23:51 UTC
0198693e696a2057696f6586c01a8375fc115b64
1 file changed
+45
-13
docs/experimental-features.md
+45
-13
@@ -250,36 +250,68 @@ configured, the daemon will fail to start.
250
---
251
252
## ipfs p2p
253
-Allows to tunnel TCP connections through Libp2p streams
253
+
254
+Allows tunneling of TCP connections through Libp2p streams. If you've ever used
255
+port forwarding with SSH (the `-L` option in openssh), this feature is quite
256
+similar.
257
258
### State
259
+
260
Experimental
261
262
### In Version
263
+
264
master, 0.4.10
265
266
### How to enable
262
-P2P command needs to be enabled in config
267
264
-`ipfs config --json Experimental.Libp2pStreamMounting true`
268
+The `p2p` command needs to be enabled in config:
269
+
270
+```sh
271
+> ipfs config --json Experimental.Libp2pStreamMounting true
272
+```
273
274
### How to use
275
268
-Basic usage:
276
+First, pick a protocol name for your application. Think of the protocol name as
277
+a port number, just significantly more user-friendly. In this example, we're
278
+going to use `/p2p/kickass/1.0`.
279
+
280
+**Setup:**
281
+
282
+1. A "server" node with peer ID `$SERVER_ID`
283
+2. A "client" node.
284
+
285
+**On the "server" node:**
286
+
287
+First, start your application and have it listen on `$APP_PORT`.
288
+
289
+Then, configure the p2p listener by running:
290
+
291
+```sh
292
+> ipfs p2p listener open /p2p/kickass/1.0 /ip4/127.0.0.1/tcp/$APP_PORT
293
+```
294
+
295
+This will configure IPFS to forward all incoming `/p2p/kickass/1.0` streams to
296
+`127.0.0.1:$APP_PORT` (opening a new connection to `127.0.0.1:$APP_PORT` per
297
+incoming stream.
298
+
299
+**On the "client" node:**
300
+
301
+First, configure the p2p dialer to forward all inbound connections on
302
+`127.0.0.1:SOME_PORT` to the listener behind `/p2p/kickass/1.0` on the server
303
+node.
304
+
305
+```sh
306
+> ipfs p2p stream dial $SERVER_ID /p2p/kickass/1.0 /ip4/127.0.0.1/tcp/$SOME_PORT
307
+```
308
270
-- Open a listener on one node (node A)
271
-`ipfs p2p listener open p2p-test /ip4/127.0.0.1/tcp/10101`
272
-- Where `/ip4/127.0.0.1/tcp/10101` put address of application you want to pass
273
- p2p connections to
274
-- On the other node, connect to the listener on node A
275
-`ipfs p2p stream dial $NODE_A_PEERID p2p-test /ip4/127.0.0.1/tcp/10102`
276
-- Node B is now listening for a connection on TCP at 127.0.0.1:10102, connect
277
- your application there to complete the connection
309
+Next, have your application open a connection to `127.0.0.1:$SOME_PORT`. This connection will be forwarded to the service running on `127.0.0.1:$APP_PORT` on the remote machine.
310
311
### Road to being a real feature
312
- [ ] Needs more people to use and report on how well it works / fits use cases
313
- [ ] More documentation
282
-- [ ] Support other protocols
314
+- [ ] Support other protocols (e.g, unix domain sockets)
315
316
---
317