# How PkarrPublisher Publishes iroh Endpoint Addresses to DNS > Learn how PkarrPublisher publishes iroh endpoint addresses to DNS. Discover the process of collecting, encoding, and uploading data for easy resolution via DNS queries. - Repository: [number zero/iroh](https://github.com/n0-computer/iroh) - Tags: how-to-guide - Published: 2026-07-05 --- **`PkarrPublisher` publishes iroh endpoint addresses to DNS by filtering and collecting endpoint data, encoding it into a cryptographically signed packet, and uploading it to a pkarr relay via HTTP PUT, where the data becomes resolvable through standard DNS queries.** The `PkarrPublisher` component in the [n0-computer/iroh](https://github.com/n0-computer/iroh) repository provides a decentralized mechanism for making iroh node addresses discoverable via DNS. It bridges peer-to-peer networking with traditional DNS infrastructure by publishing signed endpoint information to pkarr relays. This article explains the internal mechanics of how PkarrPublisher works for publishing iroh endpoint addresses to DNS, based on the actual implementation in the source code. ## The Three-Stage Publishing Pipeline The publishing flow in [`iroh/src/address_lookup/pkarr.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/address_lookup/pkarr.rs) operates through three distinct stages: data collection, cryptographic signing, and HTTP transmission. ### Collecting Endpoint Data The publisher begins by receiving an **`EndpointData`** structure containing the node's relay URLs, direct IP addresses, and other connectivity information. Before publication, this data passes through an **`AddrFilter`** to ensure privacy and security. By default, the filter uses **`AddrFilter::relay_only()`**, which strips direct IP addresses to prevent leakage of public network locations. This filtering occurs in the publisher's data collection phase, ensuring only relay-mediated addresses are exposed to the public DNS record. ### Encoding and Signing the Packet Once filtered, the endpoint data transforms into an **`EndpointInfo`** structure. The critical step occurs in `EndpointInfo::to_pkarr_signed_packet`, which creates a **`SignedPacket`** following the pkarr specification format: `<32-byte pubkey><64-byte signature><8-byte timestamp>`. This process, implemented in [`iroh-dns/src/pkarr.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/src/pkarr.rs), signs the payload using the endpoint's **`SecretKey`** and appends a monotonic timestamp to prevent replay attacks. The resulting packet contains DNS TXT records encoding the reachable addresses, cryptographically bound to the node's public key. ### Publishing via HTTP PUT The **`PkarrRelayClient`** handles the network transmission, configured with optional TLS and custom DNS resolvers as shown in lines 311-316 of [`iroh/src/address_lookup/pkarr.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/address_lookup/pkarr.rs). A background **`PublisherService`** manages the publication lifecycle, watching for endpoint data changes or triggering on a periodic republish interval. When publishing, the service performs an HTTP PUT request to `/` with the signed packet as the request body. The pkarr relay stores this packet and, if functioning as a DNS resolver, serves it under a derived domain name (e.g., `o3dks..6uyy.dns.iroh.link`). ## Architecture and Key Components The implementation relies on several coordinated components working across multiple source files: - **`PkarrPublisherBuilder`** – Configures publication parameters including address filtering, TTL values, and republish intervals. Located in [`iroh/src/address_lookup/pkarr.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/address_lookup/pkarr.rs) (lines 150-167). - **`PublisherService`** – Background task managing periodic republication (defaulting to 5-minute intervals) and handling backoff strategies on network failures. Implements the HTTP PUT logic in lines 56-74. - **`PkarrResolver`** – The complementary component for DNS lookups, retrieving signed packets from relays or DNS resolvers and reconstructing `EndpointInfo` for peer connections (lines 86-94). - **`SignedPacket`** – The wire format defined in [`iroh-dns/src/pkarr.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/src/pkarr.rs) handling binary encoding, signature verification, and timestamp validation (lines 41-48, 81-87). ## Configuration Options The builder pattern allows customization of publication behavior beyond the privacy-preserving defaults: ```rust use iroh::address_lookup::pkarr::{PkarrPublisher, AddrFilter}; use std::time::Duration; use url::Url; // Configure a publisher with custom intervals and full address disclosure let relay_url = Url::parse("https://dns.iroh.link/pkarr").unwrap(); let publisher = PkarrPublisher::builder(relay_url) .ttl(60) // DNS TTL in seconds .republish_interval(Duration::from_secs(120)) // Republish every 2 minutes .addr_filter(AddrFilter::unfiltered()) // Include direct IPs .build(secret_key.clone(), tls_config.clone()); ``` ## Integrating with iroh Endpoints In practice, you integrate the publisher directly into an iroh endpoint builder: ```rust use iroh::endpoint::Builder; use iroh::address_lookup::pkarr::PkarrPublisher; use url::Url; let relay_url = Url::parse("https://dns.iroh.link/pkarr").unwrap(); let endpoint = Builder::new() .address_lookup(PkarrPublisher::builder(relay_url)) .build() .await?; ``` Manual updates trigger immediate republication through the background service: ```rust // Trigger a fresh publication with current endpoint data let data = endpoint.endpoint_data(); endpoint.publish(&data); ``` ## Summary - **`PkarrPublisher`** writes iroh endpoint data to pkarr relays, making nodes discoverable via DNS without centralized registries. - **Privacy defaults** use `AddrFilter::relay_only()` to avoid leaking direct IP addresses to public DNS records. - **Cryptographic signing** binds endpoint information to the node's public key using `EndpointInfo::to_pkarr_signed_packet` with the format `<32-byte pubkey><64-byte signature><8-byte timestamp>`. - **HTTP transport** uploads signed packets via PUT requests to `/`, handled by `PkarrRelayClient` and managed by the background `PublisherService`. - **Automatic refresh** occurs every 5 minutes by default (`DEFAULT_REPUBLISH_INTERVAL`), ensuring DNS records remain current. ## Frequently Asked Questions ### What is the default address filtering behavior in PkarrPublisher? By default, `PkarrPublisher` uses **`AddrFilter::relay_only()`**, which filters out direct IP addresses and publishes only relay URLs. This prevents exposure of the node's physical network location to public DNS queries, enhancing privacy while maintaining connectivity through relay infrastructure. ### How often does PkarrPublisher republish endpoint data? The background **`PublisherService`** republishes data every **5 minutes** by default, controlled by `DEFAULT_REPUBLISH_INTERVAL`. The builder allows customization via `.republish_interval()`, and the service also triggers immediate updates when endpoint data changes or manual `publish()` calls occur. ### What format does the DNS packet use in pkarr publishing? The signed packet follows the **pkarr specification**: a binary concatenation of `<32-byte pubkey><64-byte signature><8-byte timestamp>`. This format, implemented in [`iroh-dns/src/pkarr.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/src/pkarr.rs), encodes endpoint information as DNS TXT records and cryptographically signs them with the node's `SecretKey`. ### How does DNS resolution work after publishing with PkarrPublisher? Once published, the pkarr relay stores the signed packet and serves it via DNS under a name derived from the z-base-32 encoded public key (e.g., `o3dks..6uyy.dns.iroh.link`). The complementary **`PkarrResolver`** queries these records, verifies the signatures, and reconstructs `EndpointInfo` for establishing peer connections.