mDNS - iroh

The mDNS address lookup mechanism will automatically broadcast your endpoint’s presence on the local network, and listen for other endpoints doing the same. When another endpoint is discovered, the dialing information is exchanged, and a connection can be established directly over the local network without needing a relay. Devices need to be connected to the same local network for mDNS address lookup to work. This can be a Wi-Fi network, an Ethernet network, or even a mobile hotspot, but does not work in browsers.

Three devices on the same network — an iPhone, an Android phone and an embedded device — behind one router; each multicasts an mDNS announcement of its key and local address, and every device's known-peers list grows as the announcements arrive

Choose an mDNS lookup

Local discovery is optional in iroh 1.x. Neither of these crates is enabled by default; add one when your application needs to find peers on the same network. They make different performance trade-offs:

Crate	How it discovers peers	When to consider it
`iroh-mdns-address-lookup`	Uses `swarm-discovery`, which adjusts the frequency of address announcements based on observed traffic.	Long-running endpoints or large local meshes where limiting multicast traffic matters.
`iroh-mdns-peer-lookup`	Uses the standard mDNS/DNS-SD query and response protocol.	Short-lived or on-demand clients, including mobile apps that need a quick initial connection.

For mobile devices, weigh connection setup time against how long discovery stays active and its effect on battery use. A mobile app participating in a large local mesh may prefer bounded multicast traffic; an app that wakes briefly to connect may prefer faster initial lookup. These crates use different discovery formats, so check that the endpoints you want to find use a compatible lookup. Both examples below use presets::N0, which enables the default DNS lookup and relay servers alongside local discovery. Neither mDNS crate is enabled by the preset. mDNS shares local dialing addresses with peers on the local network. Publishing IP addresses to a global address lookup is not required for iroh’s hole punching: endpoints exchange IP information after a connection is established, including when that connection starts through a relay. A connected peer may learn your IP addresses; take this into account if your application authenticates peers after accepting connections.

Using `iroh-mdns-address-lookup`

Add the crate alongside iroh:

[dependencies]
iroh = "1"
iroh-mdns-address-lookup = "0.5"

Bind the endpoint, build the mDNS service with its endpoint ID, then register the service:

use iroh::{Endpoint, endpoint::presets};
use iroh_mdns_address_lookup::MdnsAddressLookup;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let endpoint = Endpoint::bind(presets::N0).await?;
    let mdns = MdnsAddressLookup::builder().build(endpoint.id())?;
    endpoint.address_lookup()?.add(mdns.clone());

    // Keep `mdns` if you want to call `mdns.subscribe().await` to receive
    // discovered and expired peer events.
    Ok(())
}

You can also pass MdnsAddressLookup::builder() to Endpoint::builder(presets::N0).address_lookup(...) before binding if you do not need to retain the mDNS handle for subscribe(). For discovery events and address filtering, see the iroh-mdns-address-lookup documentation.

Using `iroh-mdns-peer-lookup`

The peer lookup crate uses standard DNS-SD records. Its announce option lets a listening endpoint advertise itself while a client can perform lookup without advertising:

[dependencies]
iroh = "1"
iroh-mdns-peer-lookup = "0.1"

use iroh::{Endpoint, endpoint::presets};
use iroh_mdns_peer_lookup::{Options, lookup};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let options = Options::new().announce(true).build();
    let mdns = lookup(options).await?;
    let endpoint = Endpoint::builder(presets::N0)
        .address_lookup(mdns)
        .bind()
        .await?;
    // Accept connections with `endpoint`.
    Ok(())
}

Use .announce(false) for a client that only looks up peers. See the crate documentation for its other options.

​Choose an mDNS lookup

​Using iroh-mdns-address-lookup

​Using iroh-mdns-peer-lookup

Choose an mDNS lookup

Using `iroh-mdns-address-lookup`

Using `iroh-mdns-peer-lookup`