From 527d3a0ef5082c99ab2c3d68b94088751cc19c2f Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Thu, 5 Mar 2026 11:10:38 -0800 Subject: [PATCH] naming has changed --- concepts/discovery.mdx | 4 +- concepts/holepunching.mdx | 91 ------------------------- concepts/nat-traversal.mdx | 64 +++++++++++++++++ concepts/relays.mdx | 2 +- deployment/dedicated-infrastructure.mdx | 6 +- docs.json | 10 ++- iroh-services/access.mdx | 2 +- 7 files changed, 79 insertions(+), 100 deletions(-) delete mode 100644 concepts/holepunching.mdx create mode 100644 concepts/nat-traversal.mdx diff --git a/concepts/discovery.mdx b/concepts/discovery.mdx index f485943..bd271dd 100644 --- a/concepts/discovery.mdx +++ b/concepts/discovery.mdx @@ -27,12 +27,12 @@ There are four different implementations of the discovery service in iroh. **By ### The motivation We want iroh to establish connections with as little friction as possible. Our -first big push toward chipping away at this goal was adding [holepunching](/concepts/holepunching) into +first big push toward chipping away at this goal was adding [NAT traversal](/concepts/nat-traversal) into iroh. Now, devs no longer need to worry about opening up ports on their servers / firewalls or be resigned to only creating connections to computers inside their local NAT. -But even with holepunching, you need to know *where* to dial. Dialing an endpoint in +But even with NAT traversal, you need to know *where* to dial. Dialing an endpoint in iroh needs either an IP address to talk to, or the URL of a relay to which the remote endpoint is connected. To make things easier, you can use [tickets](/concepts/tickets) early-on. Tickets are easily encodable diff --git a/concepts/holepunching.mdx b/concepts/holepunching.mdx deleted file mode 100644 index 3ec3170..0000000 --- a/concepts/holepunching.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "Holepunching" ---- - -With holepunching, iroh applications can: -- **Connect directly** between devices without manual network configuration -- **Reduce latency** by avoiding servers when possible -- **Save bandwidth** by keeping data transfer peer-to-peer -- **Improve resilience and reliability** by not depending on all traffic being sent through third parties - -The best part? All of this happens automatically—you don't need to understand the technical details to benefit from it. - -## The Problem: NAT Blocks Direct Connections - -Imagine you're trying to video call a friend. Both of you are behind routers at -home. When you try to connect directly to each other, your routers' firewalls -block the incoming connection because they don't recognize it as a response to -something you requested. The combination of NAT (which translates addresses) and -firewall rules (which filter traffic) makes direct connections -challenging. - -Most home and office networks use NAT, which acts like a one-way door—devices -inside the network can reach out to the internet, but the internet can't easily -reach back in. This causes reliance on central servers, which can introduce -latency and reliability issues. - -Traditionally, this problem was solved by: -- **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge) -- **Relay servers**: Routing all traffic through a third-party server (slow and expensive) - - -## The Innovation: Holepunching - -**Holepunching** is a clever technique that works around NAT and firewall restrictions to allow direct connections between peers without manual configuration or relying entirely on relay servers. - -iroh uses a sophisticated holepunching implementation built on top of QUIC and integrates with the relay system. The process relies on two key elements: - -Holepunching works in most network configurations, but some corporate firewalls or cellular networks may still require relay fallback. iroh handles this automatically. - - -## How Holepunching Works in iroh - -### 1. Initial Contact Through a Relay - -Both peers first connect to a shared [relay server](/concepts/relays). The relay -acts as a meeting point where peers can coordinate without being able to connect -directly yet. - -The relay server observes each node's public IP address and port (the address -from which it sees incoming traffic). This *reflective address* can be used by -the remote peer to reach through the firewall, provided the firewall considers -it expected traffic. - -### 2. Sharing Connection Information - -Through the relay, peers exchange their: -- **Public IP addresses** (how they appear to the outside internet) -- **Port numbers** (the specific door number the router assigned them) -- **Local addresses** (in case they're on the same network) - -Nodes coordinate their holepunching attempts through the relay as a side -channel. Both nodes simultaneously send UDP datagrams to each other's reflective -addresses. Since both are sending on the same 4-tuple (source IP, source port, -destination IP, destination port), the firewalls recognize the incoming packets -as matching outbound traffic and allow them through. - -Importantly, the relay server doesn't actively participate in holepunching -- it -simply forwards encrypted packets between nodes without knowledge of whether -they contain application data or coordination messages. - - - -### 3. Simultaneous Outbound Connection - -Here's the magic: both peers try to connect to each other **at the same time**. When peer A sends a packet to peer B's public address, A's NAT creates a mapping and the firewall creates a temporary rule allowing responses from B. When peer B sends a packet to peer A at the same moment, B's NAT and firewall do the same. - -Because both NAT mappings are established and both firewalls now have rules expecting traffic from each other, the packets get through, and a direct connection is established! - -### 4. Fallback to Relay - -If holepunching fails (some networks use particularly strict NAT configurations), iroh automatically falls back to routing traffic through the relay server. This ensures connections always work, even if they can't be direct. - -## Read more - -For technical details on the implementation, see: - -- [iroh's holepunching implementation](https://docs.rs/iroh/latest/iroh/endpoint/index.html#nat-traversal) -- [Relay system documentation](/concepts/relays) -- [Dedicated infrastructure setup](/deployment/dedicated-infrastructure) -- [Endpoint configuration](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html) - diff --git a/concepts/nat-traversal.mdx b/concepts/nat-traversal.mdx new file mode 100644 index 0000000..a65ddd6 --- /dev/null +++ b/concepts/nat-traversal.mdx @@ -0,0 +1,64 @@ +--- +title: "NAT Traversal" +--- + +NAT traversal is the set of techniques iroh uses to establish direct peer-to-peer connections between devices that sit behind NATs and firewalls. With NAT traversal, iroh applications can: + +- **Connect directly** between devices without manual network configuration +- **Reduce latency** by avoiding servers when possible +- **Save bandwidth** by keeping data transfer peer-to-peer +- **Improve resilience and reliability** by not depending on all traffic being routed through third parties + +All of this happens automatically — you don't need to understand the technical details to benefit from it. + +## The Problem: NATs and Firewalls Block Direct Connections + +Imagine you're trying to connect two devices directly — both sitting behind home or office routers. The routers' firewalls block incoming connections because they don't recognise them as responses to outbound traffic. The combination of NAT (which translates addresses) and firewall rules (which filter traffic) makes direct connections challenging. + +Most home and office networks use NAT, which acts like a one-way door — devices inside the network can reach out to the internet, but the internet can't easily reach back in. This causes reliance on central servers, which can introduce latency and reliability issues. + +Traditionally, this problem was solved by: +- **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge) +- **Relay servers**: Routing all traffic through a third-party server (slow and expensive) + +## How NAT Traversal Works in iroh + +iroh's NAT traversal is built on top of QUIC and integrates tightly with the [relay system](/concepts/relays). The core technique is simultaneous outbound connection — sometimes called "holepunching" — where both peers send packets to each other at the same time, causing their respective firewalls and NATs to create mappings that allow the traffic through. + +Note that despite the "NAT" in the name, this technique applies equally to firewalls that don't involve NAT. iroh uses it whenever a direct connection needs to be established through any restrictive network boundary. + +NAT traversal succeeds in the vast majority of real-world conditions — roughly 9 out of 10 network configurations allow a direct connection to be established. iroh's implementation is deterministic: if it works between two devices once, it will continue to work as long as their networking setup stays stable. Where it fails — some corporate firewalls or cellular networks — iroh automatically falls back to the relay. + +### 1. Initial Contact Through a Relay + +Both peers first connect to a shared [relay server](/concepts/relays). The relay acts as a meeting point where peers can coordinate before a direct path is established. + +The relay server observes each node's public IP address and port (the address from which it sees incoming traffic). This *reflective address* can be used by the remote peer to reach through the firewall, provided the firewall considers it expected traffic. + +### 2. Sharing Connection Information + +Through the relay, peers exchange their: +- **Public IP addresses** (how they appear to the outside internet) +- **Port numbers** (the specific door number the router assigned them) +- **Local addresses** (in case they're on the same network) + +Both nodes simultaneously send UDP datagrams to each other's reflective addresses. Since both are sending on the same 4-tuple (source IP, source port, destination IP, destination port), the firewalls recognise the incoming packets as matching outbound traffic and allow them through. + +The relay server doesn't actively participate in this process — it simply forwards encrypted packets between nodes without knowledge of whether they contain application data or coordination messages. + +### 3. Simultaneous Outbound Connection + +Both peers try to connect to each other **at the same time**. When peer A sends a packet to peer B's public address, A's NAT creates a mapping and the firewall creates a temporary rule allowing responses from B. When peer B sends a packet to peer A at the same moment, B's NAT and firewall do the same. + +Because both mappings are now established and both firewalls expect traffic from each other, the packets get through and a direct connection is formed. + +### 4. Fallback to Relay + +If NAT traversal fails (some networks use particularly strict configurations), iroh automatically falls back to routing traffic through the relay server. This ensures connections always work, even if they can't be direct. + +## Read more + +- [iroh's NAT traversal implementation](https://docs.rs/iroh/latest/iroh/endpoint/index.html#nat-traversal) +- [Relay system documentation](/concepts/relays) +- [Dedicated infrastructure setup](/deployment/dedicated-infrastructure) +- [Endpoint configuration](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html) diff --git a/concepts/relays.mdx b/concepts/relays.mdx index b117e52..f997a3a 100644 --- a/concepts/relays.mdx +++ b/concepts/relays.mdx @@ -12,7 +12,7 @@ those cases traffic falls back to running through the relay. Relay servers **do not** have access to the data being transmitted, as it's encrypted end-to-end. We're working on formally collecting the direct connection rate from production -iroh networks. Anecdotal evidence points to roughly 9 out of 10 networking conditions we see in practice allowing a direct connection to be established. Our holepunching implementation is deterministic - if it works between two devices once, it should continue to work as long as their networking setup remains stable. +iroh networks. Anecdotal evidence points to roughly 9 out of 10 networking conditions we see in practice allowing a direct connection to be established. Our NAT traversal implementation is deterministic - if it works between two devices once, it should continue to work as long as their networking setup remains stable. ## Public relays diff --git a/deployment/dedicated-infrastructure.mdx b/deployment/dedicated-infrastructure.mdx index 0e1a4d3..546627a 100644 --- a/deployment/dedicated-infrastructure.mdx +++ b/deployment/dedicated-infrastructure.mdx @@ -3,13 +3,13 @@ title: "Dedicated Infrastructure" --- By default, iroh will use public shared infrastructure to facilitate connections over -DNS and end-to-end encryption over relays. This infrastructure comprises: +address lookup and end-to-end encryption over relays. This infrastructure comprises: 1. [Relays](/concepts/relays) -2. [Discovery Servers (DNS)](/concepts/discovery) +2. [Address Lookup](/concepts/discovery) Relays forward traffic when direct connections are not possible as well -as facilitates holepunching for direct connections. These servers are managed and +as facilitates NAT traversal for direct connections. These servers are managed and maintained by [n0.computer](https://n0.computer), and are shared by a global public network of developers. diff --git a/docs.json b/docs.json index 188fd76..027d42f 100644 --- a/docs.json +++ b/docs.json @@ -27,7 +27,7 @@ "concepts/tickets", "concepts/discovery", "concepts/relays", - "concepts/holepunching", + "concepts/nat-traversal", "concepts/protocols" ] } @@ -153,5 +153,11 @@ }, "integrations": { "plausible": { "domain": "docs.iroh.computer" } - } + }, + "redirects": [ + { + "source": "/concepts/holepunching", + "destination": "/concepts/nat-traversal" + } + ] } diff --git a/iroh-services/access.mdx b/iroh-services/access.mdx index 7117381..32acad6 100644 --- a/iroh-services/access.mdx +++ b/iroh-services/access.mdx @@ -7,7 +7,7 @@ Some features on your Iroh Services project require authorization. Examples of what **doesn't** require authorization: - Synchronizing data across relays -- [Holepunching](/concepts/holepunching) connections to other iroh endpoints +- [NAT traversal](/concepts/nat-traversal) connections to other iroh endpoints Examples of what **does** require authorization: - Uploading metrics from endpoints to your project