Configure to support NAT

A common issue for new users running BTFS, especially on home networks, is that their BTFS node is behind a NAT (network address translation) layer (such as a residential network router). This can cause users to experience very long wait times or a high rate of request failures. 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.

Background

BTFS nodes behind a NAT often have difficulty connecting to the rest of the nodes on the BTFS network. However, there are many benefits to a NAT, because it:

• Allows many machines to share a single public address
• 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.

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.

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.

Configuration options

The appropriate configuration option for your router depends on your specific setup:

If your router supports them, enable IPv6 or enable UPnP to solve most connection issues
Use DCUtR holepunching, which is enabled by default as of Kubo v0.13
If IPv6 or UPnP are not available, or DCUtR holepunching doesn't meet your performance and reliability requirements, enable manual port forwarding

Enable IPv6

📘

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.

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.

Enable UPnP

If your router supports UPnP, BTFS 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.

Use DCUtR holepunching

As of BTFS v2.3.1, DCUtR hole punching is enabled by default.

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.