docs: add experimental-features.md
License: MIT Signed-off-by: Lars Gierth <larsg@systemli.org>
Lars Gierth committed
Jul 5, 2017 at 01:58 UTC
0660f1c46f8443ee1ded0672054b9b5e61250007
1 file changed
+214
docs/experimental-features.md
new
+214
@@ -0,0 +1,214 @@
1
+# Experimental features of go-ipfs
2
+
3
+This document contains a list of experimental features in go-ipfs.
4
+These features, commands, and APIs aren't mature, and you shouldn't rely on them.
5
+Once they reach maturity, there's going to be mention in the changelog and release posts.
6
+If they don't reach maturity, the same applies, and their code is removed.
7
+
8
+Subscribe to https://github.com/ipfs/go-ipfs/issues/3397 to get updates.
9
+
10
+When you add a new experimental feature to go-ipfs, or change an experimental feature,
11
+you MUST please make a PR updating this document, and link the PR in the above issue.
12
+
13
+- [ipfs pubsub](#ipfs-pubsub)
14
+- [Client mode DHT routing](#client-mode-dht-routing)
15
+- [go-multiplex stream muxer](#go-multiplex-stream-muxer)
16
+- [Raw leaves for unixfs files](#raw-leaves-for-unixfs-files)
17
+- [ipfs filestore](#ipfs-filestore)
18
+- [Private Networks](#private-networks)
19
+- [ipfs p2p](#ipfs-p2p)
20
+
21
+---
22
+
23
+## ipfs pubsub
24
+
25
+### State
26
+
27
+experimental, default-disabled.
28
+
29
+### In Version
30
+
31
+0.4.5
32
+
33
+### How to enable
34
+
35
+run your daemon with the `--enable-pubsub-experiment` flag. Then use the `ipfs pubsub` commands.
36
+
37
+### Road to being a real feature
38
+- [ ] Needs more people to use and report on how well it works
39
+- [ ] Needs authenticated modes to be implemented
40
+- [ ] needs performance analyses to be done
41
+
42
+---
43
+
44
+## Client mode DHT routing
45
+Allows the dht to be run in a mode that doesnt serve requests to the network, saving bandwidth.
46
+
47
+### State
48
+experimental.
49
+
50
+### In Version
51
+0.4.5
52
+
53
+### How to enable
54
+run your daemon with the `--routing=dhtclient` flag.
55
+
56
+### Road to being a real feature
57
+- [ ] Needs more people to use and report on how well it works.
58
+- [ ] Needs analysis of effect it has on the network as a whole.
59
+
60
+---
61
+
62
+## go-multiplex stream muxer
63
+Adds support for using the go-multiplex stream muxer alongside (or instead of) yamux and spdy. This multiplexer is far simpler, and uses less memory and bandwidth than the others, but is lacking on congestion control and backpressure logic. It is available to try out and experiment with.
64
+
65
+### State
66
+Experimental
67
+
68
+### In Version
69
+0.4.5
70
+
71
+### How to enable
72
+run your daemon with `--enable-mplex-experiment`
73
+
74
+To make it the default stream muxer, set the environment variable `LIBP2P_MUX_PREFS` as follows:
75
+```
76
+export LIBP2P_MUX_PREFS="/mplex/6.7.0 /yamux/1.0.0 /spdy/3.1.0"
77
+```
78
+
79
+To check which stream muxer is being used between any two given peers, check the json output of the `ipfs swarm peers` command, you'll see something like this:
80
+```
81
+$ ipfs swarm peers -v --enc=json | jq .
82
+{
83
+ "Peers": [
84
+ {
85
+ "Addr": "/ip4/104.131.131.82/tcp/4001",
86
+ "Peer": "QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ",
87
+ "Latency": "46.032624ms",
88
+ "Muxer": "*peerstream_multiplex.conn",
89
+ "Streams": [
90
+ {
91
+ "Protocol": "/ipfs/bitswap/1.1.0"
92
+ },
93
+ {
94
+ "Protocol": "/ipfs/kad/1.0.0"
95
+ },
96
+ {
97
+ "Protocol": "/ipfs/kad/1.0.0"
98
+ }
99
+ ]
100
+ },
101
+ {
102
+...
103
+```
104
+
105
+### Road to being a real feature
106
+- [ ] Significant real world testing and performance metrics across a wide variety of workloads showing that it works well.
107
+
108
+---
109
+
110
+## Raw Leaves for unixfs files
111
+Allows files to be added with no formatting in the leaf nodes of the graph.
112
+
113
+### State
114
+experimental.
115
+
116
+### In Version
117
+master, 0.4.5
118
+
119
+### How to enable
120
+Use `--raw-leaves` flag when calling `ipfs add`.
121
+
122
+### Road to being a real feature
123
+- [ ] Needs more people to use and report on how well it works.
124
+
125
+---
126
+
127
+## ipfs filestore
128
+Allows files to be added without duplicating the space they take up on disk.
129
+
130
+### State
131
+experimental.
132
+
133
+### In Version
134
+master, 0.4.7
135
+
136
+### How to enable
137
+Modify your ipfs config:
138
+```
139
+ipfs config --json Experimental.FilestoreEnabled true
140
+```
141
+
142
+And then pass the `--nocopy` flag when running `ipfs add`
143
+
144
+### Road to being a real feature
145
+- [ ] Needs more people to use and report on how well it works.
146
+- [ ] Need to address error states and failure conditions
147
+- [ ] Need to write docs on usage, advantages, disadvantages
148
+- [ ] Need to merge utility commands to aid in maintenance and repair of filestore
149
+
150
+---
151
+
152
+## Private Networks
153
+
154
+Allows ipfs to only connect to other peers who have a shared secret key.
155
+
156
+### State
157
+Experimental
158
+
159
+### In Version
160
+master, 0.4.7
161
+
162
+### How to enable
163
+Generate a pre-shared-key using [ipfs-swarm-key-gen](https://github.com/Kubuxu/go-ipfs-swarm-key-gen)):
164
+```
165
+go get github.com/Kubuxu/go-ipfs-swarm-key-gen/ipfs-swarm-key-gen
166
+ipfs-swarm-key-gen > ~/.ipfs/swarm.key
167
+```
168
+
169
+To join a given private network, get the key file from someone in the network and save it to `~/.ipfs/swarm.key` (If you are using a custom `$IPFS_PATH`, put it in there instead).
170
+
171
+When using this feature, you will not be able to connect to the default bootstrap nodes (Since we arent part of your private network) so you will need to set up your own bootstrap nodes.
172
+
173
+To prevent your node from even trying to connect to the default bootstrap nodes, run:
174
+```bash
175
+ipfs bootstrap rm --all
176
+```
177
+
178
+To be extra cautious, You can also set the `LIBP2P_FORCE_PNET` environment variable to `1` to force the usage of private networks. If no private network is configured, the daemon will fail to start.
179
+
180
+### Road to being a real feature
181
+- [ ] Needs more people to use and report on how well it works
182
+- [ ] More documentation
183
+
184
+---
185
+
186
+## ipfs p2p
187
+Allows to tunnel TCP connections through Libp2p sterams
188
+
189
+### State
190
+Experimental
191
+
192
+### In Version
193
+master, 0.4.10
194
+
195
+### How to enable
196
+P2P command needs to be enabled in config
197
+
198
+`ipfs config --json Experimental.Libp2pStreamMounting true`
199
+
200
+### How to use
201
+
202
+Basic usage:
203
+
204
+- Open a listener on one node (node A)
205
+`p2p listener open p2p-test /ip4/127.0.0.1/tcp/10101`
206
+- Connect your app to the endpoint opened locally (tcp on localhost port 10101)
207
+- On the other node, connect to the listener on node A
208
+`ipfsi 1 p2p stream dial $NODE_A_PEERID p2p-test /ip4/127.0.0.1/tcp/10102`
209
+- Now connect the application on node B to its tcp endpoint, and they should now be communicating
210
+
211
+### Road to being a real feature
212
+- [ ] Needs more people to use and report on how well it works / fits use cases
213
+- [ ] More documentation
214
+- [ ] Support other protocols