Skip to content

Commit 4bea32e

Browse files
ElPaisanoElPaisano
authored
Update NAT config page to address ipfs#1424 (ipfs#1425)
1 parent e45ca8e commit 4bea32e

File tree

1 file changed

+108
-10
lines changed

1 file changed

+108
-10
lines changed

‎docs/how-to/nat-configuration.md

Lines changed: 108 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,130 @@
11
---
2-
title: NAT configuration
2+
title: Configure NAT and port forwarding
33
description: Fix common connection issues by managing your routers NAT and forwarding ports so other IPFS nodes can interact with your node.
44
---
55

6-
# NAT configuration
6+
# Configure NAT and port forwarding
77

8-
A common issue for new users running IPFS, especially on home networks, is that their IPFS node is _sitting_ behind a NAT (network address translation). It's common for people who run an IPFS node on their home network to have very long wait times or a high rate of request failure. This is because the rest of the nodes on the IPFS network have difficulty connecting to them through their NAT. The NAT allows many machines to share a single public address, and it is essential for the continued functioning of the IPv4 protocol, which would otherwise be unable to serve the needs of the modern networked population with its 32-bit address space.
8+
A common issue for new users running IPFS Kubo, especially on home networks, is that their IPFS node is behind a [NAT (network address translation)](../concepts/glossary.md#nat) layer (such as a residential network router). This can cause users to experience very long wait times or a high rate of request failures.
9+
Connection issues that arise as a result of a NAT can be solved with various router configurations, such as port forwarding, each of which is discussed in this guide.
10+
11+
12+
## Background
13+
14+
IPFS nodes behind a NAT often have difficulty connecting to the rest of the nodes on the IPFS network. However, there are many benefits to a NAT, because it:
15+
16+
- Allows many machines to share a single public address
17+
- Is essential for the continued functioning of the IPv4 protocol, which would otherwise be unable to serve the needs of the modern networked population with its 32-bit address space.
918

1019
When you connect to your home WiFi, your computer gets an IPv4 address of something like `10.0.1.15`. This is part of a range of IP addresses reserved for internal use by private networks. When you make an outgoing connection to a public IP address, the router replaces your internal IP with its own public IP address. When data comes back from the other side, the router will translate back to the internal address.
1120

12-
While the NAT is usually transparent for outgoing connections, listening for incoming connections requires some configuration. The router listens on a single public IP address, but any number of machines on the internal network could handle the request. To serve requests, your router must be configured to send certain traffic to a specific machine. You can configure your router to allow these connections by either of the following sections.
21+
While NATs are generally transparent for outgoing connections, listening for incoming connections requires some configuration. The router listens on a single public IP address, but any number of machines on the internal network could handle the request. To serve requests, your router must be configured to send certain traffic to a specific machine.
22+
23+
## Configuration options
24+
25+
The appropriate configuration option for your router depends on your specific setup:
26+
27+
- If your router supports them, [enable IPv6](#enable-ipv6) or [enable UPnP](#enable-upnp) to solve most connection issues
28+
- [Use DCUtR holepunching](#use-dcutr-holepunching), which is enabled by default as of Kubo v0.13
29+
- If IPv6 or UPnP are not available, or DCUtR holepunching doesn't meet your performance and reliability requirements, [enable manual port forwarding](#enable-manual-port-forwarding)
1330

14-
## IPv6
31+
### Enable IPv6
32+
33+
:::callout
34+
While enabling IPv6 can fix many connection issues, it may not address all of your connection issues. For example, your router might support IPv6, but might still be running a firewall that blocks inbound connections.
35+
:::
1536

1637
If your router and internet service provider (ISP) support IPv6, enabling it will mitigate some connection issues. Most modern routers have a single option to enable IPv6. We are unable to give detailed information about each router's settings and preferences here. Search your router manufacturer's website for _IPv6_ for information on how to enable it.
1738

18-
## UPnP
39+
### Enable UPnP
1940

2041
If your router supports UPnP, IPFS will attempt to automatically allow inbound traffic to access your local content. Some home routers may need to be configured to explicitly enable UPnP. We are unable to give detailed information about each router's settings and preferences here. Search your router manufacturer's website for _UPnP_.
2142

22-
## Port forwarding
2343

24-
Each router has different options and solutions for port forwarding. Most router manufacturers have guides for setting up port forwarding on their devices. In general, the steps are something like this:
44+
### Use DCUtR holepunching
45+
46+
As of Kubo v0.13, [DCUtR hole punching is enabled by default](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.13.md#-relay-v2-client-with-auto-discovery-swarmrelayclient).
47+
48+
DCUtR holepunching has various drawbacks and tradeoffs. Currently, the connection signaling goes through a relay, which adds an average latency of 5 seconds when opening a connection. Once a direct connection is established, latency is normal. Additionally, DCUtR holepunching does not have a 100% success rate and can fail. For a deeper dive into how holepunching works in Kubo, it's drawbacks, and more information on using DCUtR, see the [_Hole punching in libp2p - Overcoming Firewalls_ blog post](https://blog.ipfs.tech/2022-01-20-libp2p-hole-punching/).
49+
50+
Because of these drawbacks, you may want to use another solution, like manual port forwarding. To enable manual port forwarding, see the instructions below.
51+
52+
### Enable manual port forwarding
53+
54+
If your router does not support UPnP and/or IPv6, or you want better reliability and performance than what DCUtR provides, set up manual port forwarding. Complete the following steps to enable manual port forwarding:
55+
56+
1. [Open a port from the internet to your internal Kubo node](#open-a-port).
57+
1. [Update the Kubo Configuration](#update-the-kubo-configuration).
58+
1. [Restart your Kubo node](#restart-your-kubo-node).
59+
60+
First, open a port from the internet to your internal Kubo node.
61+
62+
#### Open a port
63+
64+
Each router has different options and solutions for port forwarding. Most router manufacturers have guides for setting up port forwarding on their devices. In general, the steps are:
2565

2666
1. Log into your router.
2767
1. Locate your routers port forwarding section.
2868
1. Enter the IP address of your IPFS node.
29-
1. Set traffic to go through port `4001`.
69+
1. Set traffic to go through an outside port.
70+
:::tip
71+
If you are unsure of what port to use, `4001` is recommended.
72+
:::
3073
1. Reboot your IPFS node for the changes to take effect. Make sure to reboot the entire machine, not just the IPFS daemon.
3174

32-
Assuming you're not trying to expose your daemon's API to the public internet, opening port `4001`/`tcp` should be sufficient.
75+
#### Update the Kubo configuration
76+
77+
In this step, you will update your Kubo configuration to set `Swarm.AppendAnnounce` as a list of addresses that other IPFS nodes will try to contact you at. This list lets other nodes on the network know that the port forward you created in the previous step exists, and that these are the addresses at which you can be contacted at. To update your configuration:
78+
79+
1. Open your Kubo configuration file.
80+
81+
:::tip
82+
The default location for the config file is `~/.ipfs/config`. If you have set `$IPFS_PATH`, you can find your config file at `$IPFS_PATH/config`.
83+
:::
84+
85+
1. Find the entry for `AppendAnnounce` in `Addresses` or create an entry for `AppendAnnounce` in `Addresses`:
86+
87+
```json
88+
"Addresses": {
89+
"Swarm": [
90+
"/ip4/0.0.0.0/tcp/4001",
91+
"/ip6/::/tcp/4001",
92+
"/ip4/0.0.0.0/udp/4001/quic",
93+
"/ip6/::/udp/4001/quic"
94+
],
95+
"Announce": [],
96+
"AppendAnnounce": [],
97+
"NoAnnounce": [],
98+
"API": "/ip4/127.0.0.1/tcp/5001",
99+
"Gateway": "/ip4/127.0.0.1/tcp/8080"
100+
},
101+
```
102+
103+
1. Update `AppendAnnounce`, where `<public-ip>` is your public IP address and `<port>` is the port number set in the previous step:
104+
105+
```json
106+
"AppendAnnounce": [
107+
"/ip4/<public-ip>/tcp/<port>",
108+
"/ip4/<public-ip>/udp/<port>/quic",
109+
"/ip4/<public-ip>udp/<port>/quic-v1",
110+
"/ip4/<public-ip>/udp/<port>/quic-v1/webtransport",
111+
],
112+
```
113+
114+
For example, if your public IP address is `1.2.3.4` and `12345` is the port you've chosen, `AppendAnnounce` would look like:
115+
116+
```json
117+
"AppendAnnounce": [
118+
"/ip4/1.2.3.4/tcp/12345",
119+
"/ip4/1.2.3.4/udp/12345/quic",
120+
"/ip4/1.2.3.4/udp/12345/quic-v1",
121+
"/ip4/1.2.3.4/udp/12345/quic-v1/webtransport",
122+
],
123+
```
124+
125+
#### Restart your Kubo node
126+
127+
Now that you've updated your Kubo configuration, restart Kubo so that your node is reachable, and check that the outside port is open.
128+
129+
1. Reboot your IPFS node for the changes to take effect. Make sure to reboot the entire machine, not just the IPFS daemon. Once Kubo restarts, your node should be reachable.
130+
1. Check that the outside port is open.

0 commit comments

Comments
 (0)