Skip to content

Commit 0f68fcf

Browse files
whyrusleepingwhyrusleeping
authored
Merge pull request #4332 from ipfs/docs/transfer-debug
add a document to help troubleshoot data transfers
2 parents b768fb1 + 4738655 commit 0f68fcf

File tree

1 file changed

+116
-0
lines changed

1 file changed

+116
-0
lines changed

‎docs/file-transfer.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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+
```
17+
# On A
18+
> ipfs add myfile.txt
19+
added QmZJ1xT1T9KYkHhgRhbv8D7mYrbemaXwYUkg7CeHdrk1Ye myfile.txt
20+
21+
# On B
22+
> ipfs get QmZJ1xT1T9KYkHhgRhbv8D7mYrbemaXwYUkg7CeHdrk1Ye
23+
Saving file(s) to QmZJ1xT1T9KYkHhgRhbv8D7mYrbemaXwYUkg7CeHdrk1Ye
24+
13 B / 13 B [=====================================================] 100.00% 1s
25+
```
26+
27+
If that worked, and downloaded the file, then congratulations! You just used
28+
ipfs to move files across the internet! But, if that `ipfs get` command is
29+
hanging, with no output, read onwards.
30+
31+
## Troubleshooting
32+
33+
So your ipfs file transfer appears to not be working. The primary reason this
34+
happens is because node B cannot figure out how to connect to node A, or node B
35+
doesn't even know it has to connect to node A.
36+
37+
### Checking for existing connections
38+
39+
The first thing to do is to double check that both nodes are in fact running
40+
and online. To do this, run `ipfs id` on each machine. If both nodes show some
41+
addresses (like the example below), then your nodes are online.
42+
43+
```json
44+
{
45+
"ID": "QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8",
46+
"PublicKey": "CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZb6znj3LQZKP1+X81exf+vbnqNCMtHjZ5RKTCm7Fytnfe+AI1fhs9YbZdkgFkM1HLxmIOLQj2bMXPIGxUM+EnewN8tWurx4B3+lR/LWNwNYcCFL+jF2ltc6SE6BC8kMLEZd4zidOLPZ8lIRpd0x3qmsjhGefuRwrKeKlR4tQ3C76ziOms47uLdiVVkl5LyJ5+mn4rXOjNKt/oy2O4m1St7X7/yNt8qQgYsPfe/hCOywxCEIHEkqmil+vn7bu4RpAtsUzCcBDoLUIWuU3i6qfytD05hP8Clo+at+l//ctjMxylf3IQ5qyP+yfvazk+WHcsB0tWueEmiU5P2nfUUIR3AgMBAAE=",
47+
"Addresses": [
48+
"/ip4/127.0.0.1/tcp/4001/ipfs/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8",
49+
"/ip4/192.168.2.131/tcp/4001/ipfs/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8",
50+
],
51+
"AgentVersion": "go-ipfs/0.4.11-dev/",
52+
"ProtocolVersion": "ipfs/0.1.0"
53+
}
54+
```
55+
56+
Next, check to see if the nodes have a connection to eachother. You can do this
57+
by running `ipfs swarm peers` on one node, and checking for the other nodes
58+
peer ID in the output. If the two nodes *are* connected, and the `ipfs get`
59+
command is still hanging, then something unexpected is going on, and I
60+
recommend filing an issue about it. If they are not connected, then let's try
61+
and debug why. (Note: you can skip to 'Manually connecting node A to node B' if
62+
you just want things to work. Going through the debugging process and reporting
63+
what happened to the ipfs team on IRC is helpful to us to understand common
64+
pitfalls that people run into)
65+
66+
### Checking providers
67+
When requesting content on ipfs, nodes search the DHT for 'provider records' to
68+
see who has what content. Let's manually do that on node B to make sure that
69+
node B is able to determine that node A has the data. Run `ipfs dht findprovs
70+
<hash>`. We expect to see the peer ID of node A printed out. If this command
71+
returns nothing (or returns IDs that are not node A), then no record of A
72+
having the data exists on the network. This can happen if the data is added
73+
while node A does not have a daemon running. If this happens, you can run `ipfs
74+
dht provide <hash>` on node A to announce to the network that you have that
75+
hash. Then if you restart the `ipfs get` command, node B should now be able
76+
to tell that node A has the content it wants. If node A's peer ID showed up in
77+
the initial `findprovs` call, or manually providing the hash didn't resolve the
78+
problem, then it's likely that node B is unable to make a connection to node A.
79+
80+
### Checking addresses
81+
82+
In the case where node B simply cannot form a connection to node A, despite
83+
knowing that it needs to, the likely culprit is a bad NAT. When node B learns
84+
that it needs to connect to node A, it checks the DHT for addresses for node A,
85+
and then starts trying to connect to them. We can check those addresses by
86+
running `ipfs dht findpeer <node A peerID>` on node B. This command should
87+
return a list of addresses for node A. If it doesnt return any addresses, then
88+
you should try running the manual providing command from the previous steps.
89+
Example output of addresses might look something like this:
90+
91+
```
92+
/ip4/127.0.0.1/tcp/4001
93+
/ip4/192.168.2.133/tcp/4001
94+
/ip4/88.157.217.196/tcp/63674
95+
```
96+
97+
In this case, we can see a localhost (127.0.0.1) address, a LAN address (the
98+
192.168.*.* one) and another address. If this third address matches your
99+
external IP, then the network knows a valid external address for your node. At
100+
this point, its safe to assume that your node has a difficult to traverse NAT
101+
situation. If this is the case, you can try to enable upnp or NAT-PMP on the
102+
router of node A and retry the process. Otherwise, you can try manually
103+
connecting node A to node B.
104+
105+
### Manually connecting node A to B
106+
107+
On node B run `ipfs id` and take one of the multiaddrs that contains its public
108+
ip address, and then on node A run `ipfs swarm connect <multiaddr>`. You can
109+
also try using a relayed connection, for more information [read this
110+
doc](./experimental-features.md#circuit-relay). If that *still* doesn't work,
111+
then you should either join IRC and ask for help there, or file an issue on
112+
github.
113+
114+
If this manual step *did* work, then you likely have an issue with NAT
115+
traversal, and ipfs cannot figure out how to make it through. Please report
116+
situations like this to us so we can work on fixing them.

0 commit comments

Comments
 (0)