Iroh Networking Stack

The iroh-dns-server is a server that acts as both a pkarr relay and a DNS server. It provides the following services:

• DNS Server: Listens on UDP and TCP for standard DNS queries.
• HTTP/HTTPS Server: Provides endpoints for packet relay and DNS-over-HTTPS:
  • GET and PUT on /pkarr: Handles pkarr signed packets.
  • GET on /dns-query: Answers DNS queries via DNS-over-HTTPS (DoH).

Valid pkarr signed packets received via the /pkarr endpoint are served over DNS. The server appends a configured origin to the pkarr packet origin.

Iroh is a Rust library designed to establish direct peer-to-peer connections between endpoints. It provides an API for dialing via public keys, abstracting away the complexities of network connectivity.

Key features include:

• Direct Connections: Uses QUIC and NAT traversal (hole-punching) to find the fastest route between peers.
• Relay Fallback: If a direct connection cannot be established, iroh automatically falls back to using relay servers to maintain connectivity.
• Security: All connections are end-to-end encrypted and mutually authenticated using the endpoint's public key as its TLS identity.
• Multiplexing: Built on QUIC, allowing multiple concurrent streams over a single connection.

Instead of building custom networking logic, you can use existing protocols built on top of iroh:

• iroh-blobs: BLAKE3-based content-addressed blob transfer for data ranging from kilobytes to terabytes.
• iroh-gossip: A publish-subscribe overlay network designed to scale on resource-constrained devices like phones.
• iroh-docs: An eventually-consistent key-value store built using iroh-blobs.

As of version 0.9.0, iroh is organized into several specialized crates to allow developers to integrate only the specific components they need into their applications:

• iroh: The main library entry point and includes the CLI.
• iroh-bytes: Handles the core data transfer protocol, including support for resuming transfers.
• iroh-net: Provides networking tools, including NAT traversal, peer management, and general networking capabilities.
• iroh-metrics: Provides metrics collection compatible with Prometheus.

When an Iroh endpoint initializes, it automatically performs a latency test against known relay endpoints to determine which one is "closest to". This selected server is designated as the endpoint's home relay server.

Key behaviors:

• Multiple Connections: An endpoint can be connected to multiple relay servers simultaneously.
• Advertising: The endpoint advertises its home relay server as the preferred path for hole-punching or relaying packets.
• Direct Connections: If no firewalls or NATs exist between two endpoints, you do not need to know their relay server to connect directly.
• Hole Punching Requirement: To facilitate hole punching through NATs/firewalls, you must know at least one relay server to which the target endpoint is connected.

Iroh provides built-in mechanisms to facilitate connections between peers that are not directly reachable (e.g., behind NATs or on different IPv4/IPv6 networks). The connectivity stack includes:

• Hole Punching: Techniques to traverse NATs to establish direct peer-to-peer connections.
• Automatic Relaying: If direct hole punching fails, iroh automatically uses relays to maintain connectivity.
• NAT Traversal: Integrated support for discovering and connecting through complex network topologies.

For detailed technical implementation details, refer to the Iroh Hole Punching documentation.

Iroh uses the tracing crate for both logging and structured events. Unlike standard logs, structured events are designed for automated tooling and follow a specific convention to ensure they can be processed by custom subscribers without interfering with normal application logs.

Event Conventions:

• Target: Must be prefixed with iroh::_events:: followed by ::-separated names (e.g., iroh::_events::my_event).
• Message: There is no message; the unique target itself defines the event's meaning.
• Fields: Used exclusively for carrying structured data.
• Level: Always set to DEBUG.

To ensure an event follows these conventions and is distinct from normal logging, use the event!() macro.

event!(
    target: "iroh::_events::subject",
    Level::DEBUG,
    field = value,
);

Instead of implementing low-level networking, you can use existing protocols built on iroh:

• iroh-blobs: For BLAKE3-based content-addressed blob transfer (kilobytes to terabytes).
• iroh-gossip: For publish-subscribe overlay networks.

For non-Rust integrations, refer to iroh-ffi.

An iroh network participant is represented by an Endpoint.

• Identity: Every endpoint is controlled by a unique SecretKey. The corresponding public key is the EndpointId, which serves as the endpoint's unique identity.
• Authentication: Connections are authenticated against the EndpointId, preventing impersonation.
• Addressing: To connect to an endpoint using only its EndpointId, iroh uses address lookup services.
• N0 Preset: Using the presets::N0 configuration installs the DNS/Pkarr address lookup service, which utilizes servers hosted by [n0] for global endpoint discovery.
• Relays: When an endpoint is created, it connects to a nearby relay (its "home relay"). This relay facilitates the initial connection and helps in hole-punching to establish a direct QUIC connection. Relays only forward encrypted packets and cannot inspect traffic.