add a document to help troubleshoot data transfers
License: MIT Signed-off-by: Jeromy <jeromyj@gmail.com>
Jeromy committed
Oct 21, 2017 at 11:16 UTC
886403df942550e5a7fadd6a86bab77fac8e5798
1 file changed
+97
docs/file-transfer.md
new
+97
@@ -0,0 +1,97 @@
1
+# Transferring a file with ipfs
2
+This document is a guide to help troubleshoot transferring a file between two
3
+machines using ipfs.
4
+
5
+## A file transfer
6
+To start, make sure that ipfs is running on both machines. To verify, run `ipfs
7
+id` on each machine and check if the `Addresses` field has anything in it. If
8
+it says `null`, then your node is not online and you will need to run `ipfs
9
+daemon`.
10
+
11
+Now, lets call the node with the file you want to transfer node 'A' and the
12
+node you want to get the file to node 'B'. On node A, add the file to ipfs
13
+using the `ipfs add` command. This will print out the multihash of the content
14
+you added. Now, on node B, you can fetch the content using `ipfs get <hash>`.
15
+
16
+If that worked, and downloaded the file, then congratulations! You just used
17
+ipfs to move files across the internet! But, if that `ipfs get` command is
18
+hanging, with no output, read onwards.
19
+
20
+## Troubleshooting
21
+
22
+So your ipfs file transfer appears to not be working. The primary reason this
23
+happens is because node B cannot figure out how to connect to node A, or node B
24
+doesn't even know it has to connect to node A.
25
+
26
+### Checking for existing connections
27
+
28
+The first thing to do is to double check that both nodes are in fact running
29
+and online. To do this, run `ipfs id` on each machine. If both nodes show some
30
+addresses (like the example below), then your nodes are online.
31
+
32
+```json
33
+{
34
+ "ID": "QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8",
35
+ "PublicKey": "CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZb6znj3LQZKP1+X81exf+vbnqNCMtHjZ5RKTCm7Fytnfe+AI1fhs9YbZdkgFkM1HLxmIOLQj2bMXPIGxUM+EnewN8tWurx4B3+lR/LWNwNYcCFL+jF2ltc6SE6BC8kMLEZd4zidOLPZ8lIRpd0x3qmsjhGefuRwrKeKlR4tQ3C76ziOms47uLdiVVkl5LyJ5+mn4rXOjNKt/oy2O4m1St7X7/yNt8qQgYsPfe/hCOywxCEIHEkqmil+vn7bu4RpAtsUzCcBDoLUIWuU3i6qfytD05hP8Clo+at+l//ctjMxylf3IQ5qyP+yfvazk+WHcsB0tWueEmiU5P2nfUUIR3AgMBAAE=",
36
+ "Addresses": [
37
+ "/ip4/127.0.0.1/tcp/4001/ipfs/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8",
38
+ "/ip4/192.168.2.131/tcp/4001/ipfs/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8",
39
+ ],
40
+ "AgentVersion": "go-ipfs/0.4.11-dev/",
41
+ "ProtocolVersion": "ipfs/0.1.0"
42
+}
43
+```
44
+
45
+Next, check to see if the nodes have a connection to eachother. You can do this
46
+by running `ipfs swarm peers` on one node, and checking for the other nodes
47
+peer ID in the output. If the two nodes *are* connected, and the `ipfs get`
48
+command is still hanging, then something unexpected is going on, and I
49
+recommend filing an issue about it. If they are not connected, then let's try
50
+and debug why. (Note: you can skip to 'Manually connecting node A to node B' if
51
+you just want things to work. Going through the debugging process and reporting
52
+what happened to the ipfs team on IRC is helpful to us to understand common
53
+pitfalls that people run into)
54
+
55
+### Checking providers
56
+When requesting content on ipfs, nodes search the DHT for 'provider records' to
57
+see who has what content. Let's manually do that on node B to make sure that
58
+node B is able to determine that node A has the data. Run `ipfs dht findprovs
59
+<hash>`. We expect to see the peer ID of node A printed out. If this command
60
+returns nothing (or returns IDs that are not node A), then no record of A
61
+having the data exists on the network. This can happen if the data is added
62
+while node A does not have a daemon running. If this happens, you can run `ipfs
63
+dht provide <hash>` on node A to announce to the network that you have that
64
+hash. Then if you restart the `ipfs get` command, node B should now be able
65
+to tell that node A has the content it wants. If node A's peer ID showed up in
66
+the initial `findprovs` call, or manually providing the hash didn't resolve the
67
+problem, then it's likely that node B is unable to make a connection to node A.
68
+
69
+### Checking addresses
70
+
71
+In the case where node B simply cannot form a connection to node A, despite
72
+knowing that it needs to, the likely culprit is a bad NAT. When node B learns
73
+that it needs to connect to node A, it checks the DHT for addresses for node A,
74
+and then starts trying to connect to them. We can check those addresses by
75
+running `ipfs dht findpeer <node A peerID>` on node B. This command should
76
+return a list of addresses for node A. If it doesnt return any addresses, then
77
+you should try running the manual providing command from the previous steps.
78
+Example output of addresses might look something like this:
79
+
80
+```
81
+/ip4/127.0.0.1/tcp/4001
82
+/ip4/192.168.2.133/tcp/4001
83
+/ip4/88.157.217.196/tcp/63674
84
+```
85
+
86
+In this case, we can see a localhost (127.0.0.1) address, a LAN address (the
87
+192.168.*.* one) and another address. If this third address matches your
88
+external IP, then the network knows a valid external address for your node. At
89
+this point, its safe to assume that your node has a difficult to traverse NAT
90
+situation. If this is the case, you can try to enable upnp or NAT-PMP on the
91
+router of node A and retry the process. Otherwise, you can try manually
92
+connecting node A to node B.
93
+
94
+### Manually connecting node A to B On node B, run `ipfs id` and take one of
95
+the multiaddrs that contains its public ip address, and then on node A run
96
+`ipfs swarm connect <multiaddr>`. If that *still* doesn't work, then you
97
+should either join IRC and ask for help there, or file an issue on github.