| 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/p2p/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8", |
| 49 | "/ip4/127.0.0.1/udp/4001/quic-v1/p2p/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8", |
| 50 | "/ip4/192.168.2.131/tcp/4001/p2p/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8", |
| 51 | "/ip4/192.168.2.131/udp/4001/quic-v1/p2p/QmTNwsFkLAed15kQEC1ZJWPfoNbBQnMFojfJKQ9sZj1dk8", |
| 52 | ], |
| 53 | "AgentVersion": "go-ipfs/0.4.11-dev/", |
| 54 | "ProtocolVersion": "ipfs/0.1.0" |
| 55 | } |
| 56 | ``` |
| 57 | |
| 58 | Next, check to see if the nodes have a connection to each other. You can do this |
| 59 | by running `ipfs swarm peers` on one node, and checking for the other nodes |
| 60 | peer ID in the output. If the two nodes *are* connected, and the `ipfs get` |
| 61 | command is still hanging, then something unexpected is going on, and I |
| 62 | recommend filing an issue about it. If they are not connected, then let's try |
| 63 | and debug why. (Note: you can skip to 'Manually connecting node A to node B' if |
| 64 | you just want things to work. Going through the debugging process and reporting |
| 65 | what happened to the ipfs team on IRC is helpful to us to understand common |
| 66 | pitfalls that people run into) |
| 67 | |
| 68 | ### Checking providers |
| 69 | When requesting content on ipfs, nodes search the DHT for 'provider records' to |
| 70 | see who has what content. Let's manually do that on node B to make sure that |
| 71 | node B is able to determine that node A has the data. Run `ipfs routing findprovs |
| 72 | <hash>`. We expect to see the peer ID of node A printed out. If this command |
| 73 | returns nothing (or returns IDs that are not node A), then no record of A |
| 74 | having the data exists on the network. This can happen if the data is added |
| 75 | while node A does not have a daemon running. If this happens, you can run `ipfs |
| 76 | routing provide <hash>` on node A to announce to the network that you have that |
| 77 | hash. Then if you restart the `ipfs get` command, node B should now be able |
| 78 | to tell that node A has the content it wants. If node A's peer ID showed up in |
| 79 | the initial `findprovs` call, or manually providing the hash didn't resolve the |
| 80 | problem, then it's likely that node B is unable to make a connection to node A. |
| 81 | |
| 82 | ### Checking addresses |
| 83 | |
| 84 | In the case where node B simply cannot form a connection to node A, despite |
| 85 | knowing that it needs to, the likely culprit is a bad NAT. When node B learns |
| 86 | that it needs to connect to node A, it checks the DHT for addresses for node A, |
| 87 | and then starts trying to connect to them. We can check those addresses by |
| 88 | running `ipfs routing findpeer <node A peerID>` on node B. This command should |
| 89 | return a list of addresses for node A. If it doesn't return any addresses, then |
| 90 | you should try running the manual providing command from the previous steps. |
| 91 | Example output of addresses might look something like this: |
| 92 | |
| 93 | ``` |
| 94 | /ip4/127.0.0.1/tcp/4001 |
| 95 | /ip4/127.0.0.1/udp/4001/quic-v1 |
| 96 | /ip4/192.168.2.133/tcp/4001 |
| 97 | /ip4/192.168.2.133/udp/4001/quic-v1 |
| 98 | /ip4/88.157.217.196/tcp/63674 |
| 99 | /ip4/88.157.217.196/udp/63674/quic-v1 |
| 100 | ``` |
| 101 | |
| 102 | In this case, we can see a localhost (127.0.0.1) address, a LAN address (the |
| 103 | 192.168.*.* one) and another address. If this third address matches your |
| 104 | external IP, then the network knows a valid external address for your node. At |
| 105 | this point, its safe to assume that your node has a difficult to traverse NAT |
| 106 | situation. If this is the case, you can try to enable UPnP or NAT-PMP on the |
| 107 | router of node A and retry the process. Otherwise, you can try manually |
| 108 | connecting node A to node B. |
| 109 | |
| 110 | ### Manually connecting node A to B |
| 111 | |
| 112 | On node B run `ipfs id` and take one of the multiaddrs that contains its public |
| 113 | ip address, and then on node A run `ipfs swarm connect <multiaddr>`. You can |
| 114 | also try using a relayed connection, for more information [read this |
| 115 | doc](./experimental-features.md#circuit-relay). If that *still* doesn't work, |
| 116 | then you should either join IRC and ask for help there, or file an issue on |
| 117 | github. |
| 118 | |
| 119 | If this manual step *did* work, then you likely have an issue with NAT |
| 120 | traversal, and ipfs cannot figure out how to make it through. Please report |
| 121 | situations like this to us so we can work on fixing them. |