diff --git a/about/faq.mdx b/about/faq.mdx index 3969d97..e31a65c 100644 --- a/about/faq.mdx +++ b/about/faq.mdx @@ -35,7 +35,7 @@ Relays serve two roles: they assist with [NAT Traversal](/concepts/nat-traversal Because relays are **stateless** (they route encrypted packets but store nothing), they're cheap to run and easy to scale. There's no database to sync, no state to migrate, and automatic failover across relay instances is built in. -By default iroh is configured with four public relay servers run by number 0 (two in the US, one in Europe, and one in Asia), free to use for development and testing. To prevent abuse, throughput through public relays is rate-limited. For production workloads, you can run a [dedicated relay](/concepts/relays#dedicated-relays) or [self-host your own](/concepts/relays#deploy-your-own-relay). +By default iroh is configured with several public rate-limited relay servers run by number 0 (two in the US, one in Europe, and one in Asia), free to use for development and testing. To prevent abuse, throughput through public relays is rate-limited. For production workloads, you can run a [dedicated relay](/concepts/relays#dedicated-relays) or [self-host your own](/concepts/relays#deploy-your-own-relay). ## Can relays read the traffic they route? @@ -46,6 +46,8 @@ From the perspective of our QUIC implementation, the relay is "just another UDP Because the relays are relaying traffic, they theoretically know that Endpoint ID X talks to Endpoint ID Y and how many bytes are sent this way, but only for as long as these endpoints haven't established a direct connection yet. However, we don't record this data on our relays. +If you're answering this question for a security review rather than for yourself, [Enterprise Networks](/concepts/security-privacy#questions-from-security-reviews) covers it alongside what a relay can see, what leaves your network, and what running your own relay does and doesn't change. + ## How secure is iroh's end-to-end encryption? @@ -67,6 +69,8 @@ The easiest path is a [dedicated relay via Iroh Services](/concepts/relays#dedic Running your own relay doesn't affect interoperability. Your endpoints can still connect to peers using other relay servers, and since relays are stateless and logic lives at the client, can be swapped independently. +For firewall rules, certificates, and access control on a relay you host yourself, see [Running your own relay](/configuring-networks#running-your-own-relay). + ## What are the risks of running a public relay? @@ -85,7 +89,7 @@ If you're in a local network together you can enable [local network address look ## How can I control which relay servers iroh connects to? Iroh will only talk to relay servers that it knows URLs for. -By default iroh is configured with 3 relay servers from the [default `RelayMap`](https://docs.rs/iroh/latest/iroh/defaults/prod/index.html). +By default iroh is configured with several public rate-limited relay servers from the [default `RelayMap`](https://docs.rs/iroh/latest/iroh/defaults/prod/index.html). If your endpoint has address lookup services configured (which is the default with the `N0` preset), then iroh might connect to relay servers discovered that way. @@ -108,6 +112,8 @@ This returns an `impl Watchable` that reflects whether the endpoin Iroh gives you full control over which endpoints are allowed to connect via [endpoint hooks](/connecting/endpoint-hooks). Hooks let you intercept incoming connections before they're accepted, so you can allow or reject them based on the connecting endpoint's ID, your own allowlist/denylist logic, or any application-specific policy. +That controls who your application accepts. If you run your own relay, you can separately control which endpoints the relay itself will carry traffic for, by endpoint ID, a shared token, or a callback to your own service. See [Controlling who can use your relay](/configuring-networks#controlling-who-can-use-your-relay). + ## What is "Address Lookup" in iroh and which one should I enable? @@ -128,14 +134,25 @@ First, peer-to-peer [address lookup over the Mainline DHT](/connecting/dht-addre When you do a P2P address lookup, any Mainline server node could respond: each [BEP 44](https://www.bittorrent.org/beps/bep_0044.html) record is stored on 20 random Mainline nodes. So yes, a BitTorrent client that participates in the DHT as a server and has been running long enough to be in the routing tables will respond. +## Our IT or security team needs to approve iroh. What do they need? + +Iroh operates on open standards: HTTPS on TCP 443, QUIC HTTP/3, mTLS, and industry grade end to end encryption with elliptic curve keys. Nothing listens for inbound connections, no ports are forwarded, and all traffic is end-to-end encrypted whether it goes direct or through a relay. Allowing outbound UDP is optional, but it is what lets most connections go direct. + +[Enterprise Networks](/configuring-networks) is written for that reader rather than for a developer: what iroh does on a managed network, what to allow, the security and privacy questions that come up in review, and how to run every part of it on infrastructure you control. + + ## What ports does iroh use? -Iroh listens on **Two UDP ports**: one for IPv4 and one for IPv6, used for direct P2P connections; configurable via [`endpoint::Builder`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Builder.html) +**Outbound TCP 443** to your relay servers. This is the only connection iroh strictly requires, and it's an HTTPS connection that upgrades to a WebSocket. + +**Outbound UDP** for direct connections. Iroh binds **two UDP ports**, one for IPv4 and one for IPv6, assigned by the operating system unless you set them via [`endpoint::Builder`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Builder.html). Direct connections go to arbitrary destination ports on the far side, and **UDP 7842** on the relay is used to learn your own public address. Iroh will work behind firewalls that only allow TCP outbound, but direct connections won't be possible in that case; all traffic will fall back to the relay. It's totally possible that you maintain connections to multiple relays at a time, if you're connected to iroh endpoints that have another home relay than yours. Each of these connections will use another TCP socket. +For the full list of flows, hostnames, and firewall rules to hand to a network administrator, see [Enterprise Networks](/configuring-networks). + ## How would onion-routing work with iroh? @@ -255,3 +272,80 @@ It would also mean Endpoint IDs would be exactly 37x as big. To support post-quantum-cryptography, we would need to trade off usability with the risk should a sufficiently powerful quantum computers would become real. We believe it is much more important to serve existing use cases efficiently, so they have encryption *today*. We fully believe the work on post-quantum-cryptography is good and important and follow developments closely. + +## Does this punch holes in my firewall? + +No. The technique has an alarming name, so it is worth being precise about what +actually happens. + +Two devices, each behind its own firewall, send an outbound packet to each other +at roughly the same moment. Each firewall sees an outbound connection from a +device on its own network and allows the reply, under the same rule that lets a +browser load a website. Neither firewall is tricked, and neither is +reconfigured. + +In practical terms: + +- iroh never accepts unsolicited inbound connections. No port is exposed to the + internet. +- Every connection begins as outbound traffic from a device you control. +- If your firewall does not allow the reply, nothing is bypassed. The connection + falls back to the relay. +- If you block the relay hostnames too, iroh stops working. That is the intended + behavior, not something to defend against. + +One caveat on that last point. Blocking the hostnames listed below stops iroh in +its default configuration, which is what almost every application uses. But the +hostnames are a setting in the application, and iroh also supports other ways of +finding peers that your developers could enable. If you need a hard guarantee +rather than a sensible default, block outbound UDP as well, and ask your +developers to confirm what the application is actually configured with. + +## Can we stop data going through a relay entirely? + +This request usually arrives as a policy statement: no company data may pass +through a server we do not control. It is worth separating the two things that +might mean, because they have different answers. + +**If the concern is that someone could read the data,** it is already addressed. +A relay forwards encrypted bytes and cannot decrypt them. No relay operator can +see inside your traffic. + +**If the concern is control, jurisdiction, or data residency,** the answer is to +run the relay yourself, as described above. Your server, your network, your +logs, and nothing leaves your perimeter. + +Switching relaying off entirely is a third option. It is a one-line change for +your developers: + +```rust +let endpoint = Endpoint::builder(presets::Empty) + .relay_mode(RelayMode::Disabled) + .bind() + .await?; +``` + +It is usually the wrong choice. It removes the fallback, but it also removes the +machinery that makes direct connections work in the first place. + +- **Roughly one connection in ten stops working.** Stricter firewalls and + certain router types do not allow two devices to connect directly. Those + connections use a relay today. Without one they simply fail, with no fallback + and no error you can fix from the network side. +- **You lose the introduction, not just the fallback.** The relay is how two + devices first find each other and coordinate the simultaneous connection + attempt. Without it, a device behind a firewall cannot be reached at all + unless you provide another way for peers to find each other. +- **Connections take longer to start.** Normally the first data flows over the + relay immediately and moves to a direct connection a moment later. Without a + relay, nothing flows until the direct connection succeeds or fails. +- **Network changes turn into outages.** Switching from Wi-Fi to a mobile + connection, or a DHCP lease change, breaks the direct path. The relay normally + carries traffic during the seconds it takes to rebuild one. + +The cost also falls unevenly. It lands on whoever is behind the most restrictive +network, which is often a customer or a remote worker rather than someone you +can help. + +For nearly every deployment, running your own relay is the better answer. You +get the control you were after, and your users keep the connectivity. diff --git a/concepts/security-privacy.mdx b/concepts/security-privacy.mdx index fb27610..81b6086 100644 --- a/concepts/security-privacy.mdx +++ b/concepts/security-privacy.mdx @@ -104,3 +104,84 @@ for each relay in the route, which would require significant protocol changes. If these features are interesting to you, please [contact us](https://n0.computer/) to discuss your specific requirements. + + +## Questions from security reviews + +These are the questions that come up when a network or security team reviews an +application built on iroh. For the firewall side of that review, see +[Deploying to enterprise networks](/configuring-networks). + +### Can the relay operator read our data? + +No. Traffic is encrypted end to end between the two devices. A relay forwards +encrypted bytes and holds no key that can decrypt them. + +This holds for every relay: ones you run, dedicated ones from Iroh Services, and +the shared public ones. It also means running the relay yourself does not give +you visibility into the contents. What it gives you is control of the path. + +### What can a relay see? + +The identities of the devices connected to it, which pairs are exchanging +traffic, when, and how much. It cannot see file names, message contents, or +anything else inside the connection. + +Once two devices establish a direct connection, their traffic stops flowing +through the relay, so this visibility covers the period before that plus any +connection that never manages to go direct. + +A relay is also not told when a pair goes direct. From its point of view traffic +simply stops, and it cannot distinguish a pair that is still talking over a direct +path from one that finished and disconnected. So a relay cannot reliably infer how +long two devices communicated or how much they exchanged in total, only what it +carried itself. + +That connection metadata is a real disclosure, and it is a fair thing to care +about. If it matters to you, run your own relay and it stays with you. + +### Can we inspect or log the contents? + +No, and this is not a property of the UDP path specifically. The relay +connection on port 443 is also encrypted end to end, so a TLS inspection +appliance sees encrypted data either way. + +If your policy requires visibility into content, the place to get it is the +application, not the network. Your developers can log what the application sends +and receives. Running your own relay gives you full control of the path and the +connection metadata, but not the contents. + +### What actually leaves our network? + +Four things: + +1. Encrypted connections to relay servers: the ones your application is + configured with, plus the relay that any device you connect to has chosen for + itself. +2. A small signed record published to `dns.iroh.link`, containing the device's + public key and which relay it is using. **Internal IP addresses are not + published by default.** iroh deliberately filters them out to avoid leaking + them to a public server. +3. DNS lookups for the devices you connect to. +4. If direct connections are allowed, UDP traffic to the other device, which + reveals your public IP address to that device. This is true of any direct + connection between two computers, and is covered in more depth in + [Protecting leakage of IP Addresses](#protecting-leakage-of-ip-addresses). + +### Can we control which of our devices are allowed to use it? + +Yes, on relays you run yourself. You can admit a specific list of devices or +require a shared password. See +[Controlling who can use your relay](/configuring-networks#controlling-who-can-use-your-relay). +Dedicated relays from Iroh Services with authentication enabled do this for you, +and only admit devices belonging to your project. + +On the shared public relays, no. Any application that knows the URL can connect. + +### Can we turn parts of it off? + +Yes. Direct connections, automatic router port opening, local network discovery, +and even relaying itself can each be disabled independently. Each one is a change +your developers make in the application, and +[Deploying to enterprise networks](/configuring-networks) has the specifics for +each. diff --git a/configuring-networks.mdx b/configuring-networks.mdx new file mode 100644 index 0000000..b2dd41a --- /dev/null +++ b/configuring-networks.mdx @@ -0,0 +1,424 @@ +--- +title: "Deploying to enterprise networks" +description: "What iroh does on your network, what to allow through your firewall, and how to keep it under your control" +--- + +If a team at your company wants to ship software built on iroh, this page tells +you what it will do on your network, what you need to allow, and what you can +control. + +## The one-minute version + +- **All traffic is encrypted end to end**, including traffic that passes through + a relay server. The relay operator cannot read it. +- **You do not have to open anything inward.** There is no inbound rule to write, + no port to forward, and no static IP to assign. Devices do listen on the UDP + sockets they bind, and by default iroh asks your gateway for an external port + over UPnP or NAT-PMP, which you can switch off. See + [Automatic port opening](#automatic-port-opening). +- **Allowing outbound UDP is optional, but recommended.** It makes connections faster and + cheaper, by being direct, but iroh works without it. +- **You can run all of the infrastructure yourself** if you do not want traffic + leaving your network. + +If you have set up a video conferencing or VoIP system, iroh's requirements will +look familiar. It needs the same two things Teams, Zoom, and WebEx need: a way +for a device to learn its own public address, and a server that can pass traffic +along when two devices cannot reach each other directly. + +### Checklist + +Firewall and DNS: + +- Allow outbound TCP 443 to the relay hostnames with WebSocket support +- Allow outbound TCP 443 to `dns.iroh.link`, or plan to replace address lookup +- Confirm your DNS filtering does not strip TXT records for `dns.iroh.link` +- Allow outbound UDP 7842 to the relay hostnames +- Allow outbound UDP to any destination port +- Set your firewall's UDP idle timeout to 30 seconds or more +- Turn off client isolation on wireless segments where devices should reach each other +- Test with `iroh-doctor report` from inside the network + +Ask your developers to: + +- Tell you which relay hostnames the application is configured with, before + you write any of the rules above +- Use the operating system certificate store if you inspect TLS traffic +- Configure the proxy address if outbound traffic must be proxied +- Disable automatic port opening, or confirm your gateway has UPnP and NAT-PMP + turned off already + +## What iroh does on your network + +iroh is a networking library that your developers build into an application. Its +job is to connect two devices directly, so data moves between them instead of +through a central server. + +A device running iroh produces three kinds of traffic. + +**Relay connections.** Each device opens one or a few long-lived encrypted +connections to *relay servers* on TCP port 443, as HTTPS requests that upgrade to +a WebSocket. This is the role a TURN server plays in a VoIP system. The relay +introduces two devices to each other and carries their traffic if they cannot +reach each other directly. It is always used, at minimum for the introduction. + +**Address lookup.** To find another device, iroh looks up a DNS record for it. +This is an ordinary DNS query through your own resolver. + +**Direct connections.** Once introduced, the two devices try to connect straight +to each other over UDP. This part is optional. If a direct connection is not +possible for some reason, the bi-directional connection continues to send data +using the relay. + +## What to allow + +### Required + +| Allow | To | Protocol | Why | +|---|---|---|---| +| Outbound TCP 443 | Your relay hostnames | **HTTPS, upgraded to WebSocket** | The relay connection itself, and the latency checks that pick the closest relay | +| Outbound TCP 443 | `dns.iroh.link` | HTTPS | Publishing the device's address so others can find it | +| Normal DNS (UDP/TCP 53) | Your own resolver | DNS | Looking up other devices | + + +**Opening TCP 443 is not always enough on its own.** The relay connection starts +as a standard HTTPS request and then upgrades to a WebSocket, which is the same +thing a chat application does. If you run an application-aware firewall, a web +filter, or a proxy that permits ordinary web browsing on port 443 but blocks +WebSocket upgrades, iroh will not connect at all. + +Allow the relay hostnames as a WebSocket destination, not just as an HTTPS one. + + +### Recommended + +Allowing these lets devices connect directly instead of relaying everything. + +| Allow | To | Why | +|---|---|---| +| Outbound UDP 7842 | Your relay hostnames | Lets a device learn its own public address. This is the job STUN does in a VoIP system. | +| Outbound UDP, any destination port | Any address | The direct connection between two devices | + +### Optional + +| Traffic | What it is | Default | +|---|---|---| +| UDP 1900 and UDP 5351 on your local network | Asking the gateway to open an external port (UPnP, NAT-PMP, PCP). Opens an inbound path if your gateway honors it. | On by default, and safe to turn off | +| UDP 5353 multicast on the local network | Finding devices on the same office network | Off unless your developers enable it | + +### Hostnames to allow + +Which relay hostnames to allow depends on how the application is configured. Ask +your developers, and expect one of three answers. + +**Relays you run yourself.** The hostnames are ones you already control, on your +own network or in your own cloud account. See +[Running your own relay](#running-your-own-relay). + +**Dedicated relays.** Servers provisioned for your project through Iroh Services +and used by nobody else, on hostnames given to you when they are set up. + +**The shared public relays.** Run by [n0](https://n0.computer), the company that +builds iroh, and shared with every other iroh developer worldwide. They are +meant for development and testing rather than production, so treat this as a +sign the application has not been configured yet. The defaults are: + +``` +use1-1.relay.n0.iroh.link +usw1-1.relay.n0.iroh.link +euc1-1.relay.n0.iroh.link +aps1-1.relay.n0.iroh.link +``` + +Separately from the relays, allow `dns.iroh.link`. That one is used no matter +which relays the application points at, unless your developers have replaced +address lookup with something you run. + +If your developers use the Iroh Services dashboard for monitoring or +diagnostics, that traffic travels over the connections above and needs no extra +firewall rules. + +## Common situations + +### We block outbound UDP + +**What you will see:** everything works, but more slowly, and all traffic goes +through the relay. + +**What is happening:** devices cannot reach each other directly, so every byte +takes a round trip through a relay server. + +**What to do:** nothing, if you are willing to accept the cost. It is worth +understanding the trade-off before you decide. + +The cost of blocking UDP is added delay proportional to how far away the nearest +relay is, transfer speeds limited by the relay rather than by your own internet +connection, and bandwidth charges on the relay that you either pay for directly +or share with other users of the public relays. + +Why allowing it is usually reasonable: + +- **This is QUIC, not loose datagrams.** QUIC is a connection-oriented, + congestion-controlled protocol with a TLS 1.3 handshake. It behaves like a TCP + connection that happens to run over UDP. +- **Your network almost certainly carries it already.** Chrome, Edge, and Safari + use HTTP/3 over UDP port 443 for a large share of the web, and every major + conferencing product uses UDP for media. +- **It is outbound-first.** You write no inbound rule, because the packets coming + back arrive on a flow your firewall already allowed out. The one exception is + automatic port opening, which is + [separately controllable](#automatic-port-opening). +- **Idle entries clear quickly.** iroh sends a keepalive while a connection is +active and gives up on an idle path after a specified timeout. A UDP idle +timeout of 30 seconds or more on your firewall is recommended. + +One thing that does not work: allowing UDP only to port 443. Direct connections +use randomly assigned high-numbered ports on both ends, so a rule scoped to +port 443 gains you nothing. The destination port cannot be narrowed. If you need +a tighter rule than "any destination port", your developers can pin the +application to a fixed source port with `.bind_addr("0.0.0.0:49555")`, and you +can scope the rule to that source port instead. + + +Two devices on the same office network connect directly to each other regardless +of whether your perimeter firewall allows UDP. That traffic is governed by your +internal network policy, so desk-to-desk transfers can stay local even when +outbound UDP is blocked. + + +On a network where UDP is silently dropped, the +application can skip trying, which removes probe traffic that shows up in +intrusion detection logs and speeds up startup: + +```rust +use iroh::endpoint::{presets, PortmapperConfig}; +use iroh::Endpoint; + +let endpoint = Endpoint::builder(presets::N0) + // No UDP at all: relay connections only. + .clear_ip_transports() + // Do not ask the router to open ports. + .portmapper_config(PortmapperConfig::Disabled) + .bind() + .await?; +``` + +### We inspect TLS traffic + +**What you will see:** the application cannot connect at all, and logs show a +certificate error, even though your inspection appliance's certificate authority +is installed on the machine. + +**What is happening:** iroh checks relay certificates against a list of +authorities built into the application. It does not read the operating system's +certificate store, so the certificate authority your device management tool +installed is not trusted. + +**What to do:** this is an application change, not a network one. + +**For your developers.** Switch iroh to the operating system's certificate +store, which contains the corporate certificate authority: + +```rust +use iroh::tls::CaTlsConfig; + +let endpoint = Endpoint::builder(presets::N0) + .ca_tls_config(CaTlsConfig::system()) + .bind() + .await?; +``` + +This affects the relay connection only. Direct connections between two devices +identify each other by their own cryptographic keys rather than by website +certificates, so an inspection appliance cannot sit in the middle of one. In +practice it would never be in that path anyway. + +### All traffic must go through a proxy + +**What you will see:** the application cannot reach a relay at all, because it +tries to connect directly rather than through the proxy. + +**What to do:** iroh can send its relay traffic through an HTTP proxy using +`CONNECT`, the same way a browser does. This is an application change. + +**For your developers:** + +```rust +let endpoint = Endpoint::builder(presets::N0) + // Reads HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, in that order. + .proxy_from_env() + .bind() + .await?; +``` + +Use `.proxy_url(url)` to set the address explicitly. A proxy only carries the +relay connection, so a proxied deployment usually ends up relaying everything. + +### Our DNS filtering blocks it + +**What you will see:** connections work when the application is given an address +directly, but fail when it tries to find a device by its identity. That split is +a good sign the problem is DNS rather than the firewall. + +**What is happening:** iroh finds devices by looking up a DNS TXT record under +`dns.iroh.link`. Two common configurations break this. Some DNS security +products block or strip TXT records because attackers sometimes use them to +smuggle data. Some internal DNS servers do not forward lookups for outside +domains such as `iroh.link`. + +**What to do:** allow `dns.iroh.link` in your DNS filtering policy. If you would +rather not allow it at all, your developers can turn off DNS-based lookup and +distribute addresses through whatever system you already use. + +### Guest Wi-Fi or wireless client isolation + +**What you will see:** devices on the same wireless network relay their traffic +instead of connecting directly. + +**What is happening:** two access point settings prevent local connections. +*Client isolation* (also called AP isolation, station isolation, or peer-to-peer +blocking) stops wireless devices from addressing each other, and is on by +default on most guest networks. *Multicast filtering* prevents devices from +finding each other on the local network. + +**What to do:** turn client isolation off on segments where your devices should +be able to reach each other. Neither setting breaks iroh. Both just push traffic +onto the relay that could have stayed on your own network. + +### Automatic port opening + +**What is happening:** by default iroh asks the local gateway to open an external +port for the device, using UPnP, NAT-PMP, or PCP. If your gateway implements one +of those and is configured to honor requests, iroh gets a port mapped and peers +can reach the device directly through it. + +This is the one thing iroh does that changes your perimeter without anyone asking +you, so it is worth being explicit about. It is on in a default build. Two things +soften it in practice: + +- Most business-grade gateways either do not implement these protocols or have + them turned off, in which case the request is ignored and nothing changes. +- Connectivity does not depend on it. Without a port mapping, iroh falls back to + hole punching and then to the relay. + +The UPnP discovery step also multicasts to `239.255.255.250:1900`, which is a +common intrusion detection signature and can raise firewall prompts on some +client operating systems. + +**What to do:** if your gateway has UPnP or NAT-PMP enabled and you would rather +iroh did not use it, you can turn those protocols off at the gateway, which +affects everything on the network, or have your developers disable it in the +application, which is the narrower fix. On a managed network, disabling it in the +application is the reasonable default. + +To check whether your gateway is answering these requests at all, run the +connectivity report described in +[Testing your configuration](#testing-your-configuration). It includes a port +mapping probe. + +**For your developers:** `.portmapper_config(PortmapperConfig::Disabled)` on the +endpoint builder, as in the UDP example above. + +## Keeping traffic inside your network + +If you would rather no iroh traffic left your network at all, you can replace +every piece of infrastructure outside it with your own. This is the right answer +to most concerns about relays, third-party servers, and data residency. + +There are three pieces, and you can replace them independently. + + + +Run the [relay software](https://github.com/n0-computer/iroh/tree/main/iroh-relay) +on servers your devices can reach, and have your developers point the +application at them. + + + +Either run an internal +[iroh-dns-server](https://github.com/n0-computer/iroh/tree/main/iroh-dns-server), +or drop address lookup entirely and distribute device addresses through a system +you already have. + + +This is a one-line change for your developers. It removes the shared public +relays and DNS server from the application's configuration. + + + +**For your developers:** + +```rust +use iroh::{Endpoint, RelayMap, RelayMode, RelayUrl, endpoint::presets}; + +let relay: RelayUrl = "https://relay.internal.example.com".parse()?; + +// presets::Empty starts with no external infrastructure configured. +let endpoint = Endpoint::builder(presets::Empty) + .relay_mode(RelayMode::Custom(RelayMap::from_iter([relay]))) + .bind() + .await?; +``` + +For an isolated network with no internet access at all, devices can find each +other by multicast on the local network and connect directly, with no relay +involved. This requires your switches to forward multicast and client isolation +to be off. Your developers will find the setup in +[mDNS address lookup](/connecting/local-address-lookup). + +## Help running your own relay + +If you want to run your own relay servers, you can! Everything is open source. See [Dedicated +Infrastructure](/deployment/dedicated-infrastructure) and +[contact us](https://n0.computer/) if you want help with the setup. + +## Multiple offices and sites + +Skip this section if everything runs at one site. + +Each device picks a *home relay*, the one that answers fastest, and publishes +which one it chose. To reach a device, another device connects to **that +device's** home relay, not its own. So the requirement is not that both sites +use the same relay. It is that each side can reach the relay the other side +picked. + +That distinction causes most multi-site problems. + +| What you set up | What goes wrong | What to do | +|---|---|---| +| A relay at each site, neither reachable from the other | Devices at each site pick their local relay. Neither site can reach the other's, so cross-site connections never work. | Deploy one relay both sites can reach, or make both relays reachable from both sites and list both in the application configuration. | +| Both relays reachable, but the application at one site is only configured with one of them | Devices dial the other relay without the password and get refused. Often looks intermittent or one-directional, because it depends which relay each device happened to pick. | Ship the same relay list and the same password to every site. | +| An internal address lookup server at one site only | The other site cannot find devices by identity. Connections by explicit address still work. | Make the lookup server reachable from both sites, or distribute addresses another way. | +| Site-to-site links that allow TCP 443 but not UDP | Traffic between two of your own offices goes out to a relay and back. | Allow UDP between your site subnets. This is an internal routing policy question, not a perimeter one. | + +**What survives a network outage.** Connections that are already direct keep +working when the relay becomes unreachable, because they no longer depend on it. +What stops is anything needing the relay: starting new connections, reconnecting +after a drop, and publishing addresses. + +If a site has to keep working through a total internet outage, ask your +developers to enable local network discovery alongside the normal relay +configuration. Devices on the same network segment will keep finding each other +while the link is down, and cross-site connections resume when it returns. + +| Your situation | What to deploy | +|---|---| +| One site | One internal relay. Add a second for redundancy. | +| Several sites on a company WAN | Two relays at well-connected sites, both reachable from everywhere, both in the application configuration. Devices sort out which is closer. | +| Sites with no network path between them | Each site is its own separate network. Connecting them needs a relay somewhere both can reach, such as a DMZ or a cloud server. | +| A site that must survive losing its internet link | Normal relay configuration plus local network discovery. | + +## Testing your configuration + +See [Diagnose a connectivity issue](/iroh-services/net-diagnostics/quickstart) +for a script you can run from inside your network to confirm the application can +reach the relays and that direct connections work. It is a quick way to check +that your firewall rules are correct, and it produces a report you can send to +your developers to see that everything is working. + +## Security and privacy + +The questions a security or network review raises, including what a relay can +see, what actually leaves your network, and what running your own relay does and +does not change, are answered in +[Security & Privacy](/concepts/security-privacy#questions-from-security-reviews). diff --git a/docs.json b/docs.json index 4f5e079..ddee18f 100644 --- a/docs.json +++ b/docs.json @@ -40,7 +40,8 @@ "iroh-services/net-diagnostics/quickstart", "protocols/using-quic", "examples/chat", - "add-a-relay" + "add-a-relay", + "configuring-networks" ] }, { diff --git a/troubleshooting.mdx b/troubleshooting.mdx index 3fca523..db7b352 100644 --- a/troubleshooting.mdx +++ b/troubleshooting.mdx @@ -143,3 +143,10 @@ The above output shows that the endpoint is using the `use1-1.relay.iroh.network To diagnose connectivity issues on your users' endpoints in production, use [Network Diagnostics](/iroh-services/net-diagnostics/usage). It runs the same kinds of probes as `iroh-doctor` (UDP connectivity, NAT type, relay latency, port mapping) but you trigger them from the Iroh Services dashboard against any of your project's online endpoints. The report comes back to the dashboard, so you can see what your user is experiencing without asking them to run a CLI tool. To enable diagnostics on an endpoint, grant the `NetDiagnosticsCap::GetAny` capability and run a `ClientHost`. See the [Network Diagnostics integration guide](/iroh-services/net-diagnostics/usage) for the full setup. + +## Corporate and managed networks + +If the network is one you or your customer administers, and the problem looks +like blocked UDP, an HTTPS proxy, TLS interception, or DNS filtering, see +[Enterprise Networks](/configuring-networks) for the full list of +flows to allow and how to configure iroh around each restriction.