DNS-Based Service Discovery (DNS-SD)

This repository is used for IETF work on DNS-Based Service Discovery, particularly the DNS-SD Discovery Proxy.

This code is Open Source under the Apache 2.0 license.

This work is the product of the IETF DNSSD Working Group and was presented at the 2019 Apple Worldwide Developer Conference (WWDC) networking session.

The specification for the DNS-SD Discovery Proxy can be found in draft-ietf-dnssd-hybrid.

Other useful background reading includes the Service Discovery Road Map, Multicast DNS (RFC 6762), DNS-Based Service Discovery (RFC 6763), DNS Stateful Operations (RFC 8490), and DNS Push Notifications.

This Discovery Proxy will work, using DNS polling, with any version of Mac OS X 10.4 (released in 2004) or later. Support for wide area unicast service discovery has also been included in every version of iOS since the first iPhone in 2007. However, to get the benefit of fast asynchronous change notifications using DNS Push Notifications, which keeps the user interface up to date without polling, we highly recommend testing using the current shipping versions, macOS Catalina and iOS 13.

This document last updated 2019-10-02.

Example Scenario

A very common configuration in many company networks today is that the network printers (which all support AirPrint) are connected to wired Ethernet, and the iPhones and iPads (AirPrint clients) are connected via Wi-Fi, which is a different link, and a different IPv4 subnet and/or IPv6 prefix. Even though the iPhones and iPads are fully capable of connecting to, and using, the AirPrint printers, the problem is that the iPhones and iPads on Wi-Fi can’t discover the AirPrint printers on Ethernet, because, by design, link-local Multicast DNS does not cross between different links. In principle the Wi-Fi Access Point could be configured to bridge between Ethernet and Wi-Fi, making them one logical link, but there are a number of impediments that make this a bad idea. Multicast on Wi-Fi is unreliable, slow, and very wasteful of precious wireless spectrum. Because of this, it is becoming increasingly common to limit or disable multicast on Wi-Fi, thereby breaking discovery even in cases where you might have expected it to work.

Installing a DNS-SD Discovery Proxy, either on the Wi-Fi Access Point itself, or on any other device connected to the wired Ethernet, solves this problem. With the appropriate network configuration in place, clients on Wi-Fi automatically know to talk to that proxy to perform Multicast DNS queries on their behalf. In this way, clients on Wi-Fi are able to perform service discovery exclusively using unicast, even in configurations where multicast is entirely disabled on the Wi-Fi network. Your clients on Wi-Fi will now be able to discover and use those AirPrint printers on wired Ethernet.

Target Audience

This sample code is made available for anyone wanting to experiment with the DNS-SD Discovery Proxy.

However, the intended goal is not that end users and network administrators build and install their own DNS-SD Discovery Proxies. The intended goal is that vendors making Wi-Fi Access Points, routers, and home gateways add this capability to their products. If you work for one of these vendors, and want to add DNS-SD Discovery Proxy capability to your products, please contact us for help about how to do that.

This is pre-release code, and most likely still has some bugs. If you find bugs please help us improve the code by reporting any bugs you find, or by suggesting code changes in the form of Git pull requests.

Building and Operating a DNS-SD Discovery Proxy on your Network

There are four steps to building and operating a DNS-SD Discovery Proxy on your network:

1. Installing a prebuilt package, or building the Discovery Proxy code for yourself.

2. Picking a DNS subdomain name for your advertised services.

3. Configuring and running the Discovery Proxy.

4. Configuring clients with your chosen DNS subdomain name for wide-area discovery (either manually on the client device itself, or automatically via appropriate network configuration).

Option (i) Installing the Prebuilt Package for OpenWrt

If you want to build this code yourself to run on a Mac or Linux machine, skip ahead to Option (ii) Building the Discovery Proxy Code Yourself.

If you’re using OpenWrt and don’t want to build the code yourself, we have a prebuilt package for the router we are using for development, the GL.iNet AR750S. This package may also work on routers with similar hardware.

Connect the upstream WAN port of the AR750S to your existing home network, and connect your computer to a downstream LAN port on the AR750S, or its Wi-Fi network. Ensure that your AR750S is up to date with the latest firmware from GL.iNet. At time of writing, this is version 3.025. When you update the firmware, turn off the “Keep Settings” option. This will restore your device to factory defaults, which ensures that you’re following the setup steps described here starting with the same factory default configuration that we did.

Your AR750S should be in the default configuration, where it is obtaining an IP address for itself using DHCP on its upstream WAN port (your existing home network), and sharing that IP address with its LAN (and Wi-Fi) clients by operating its own DHCP server and NAT gateway.

At this point, take a moment to observe that your computer connected to the AR750S’s downstream LAN port or Wi-Fi cannot discover anything on the upstream WAN port side. If you press Cmd-Shift-K (“New Remote Connection”) in Terminal, you’ll not see any services on the upstream WAN port side. If you go to System Preferences and try to add a printer, you’ll not discover any printers on the upstream WAN port side. If you run “Image Capture”, you’ll not discover any scanners on the upstream WAN port side.

To install the Discovery Proxy on your AR750S, bring up a Terminal window on your Mac and type:

ssh root@192.168.8.1

Enter the admin password that you configured when you set up the router. (To save having to enter the password every time, for convenience you can also install your ssh public key on the router using the router’s web user interface).

When you are at a command prompt on the router, add a line to the end of /etc/opkg/customfeeds.conf to add our OpenWrt package, as shown below:

echo 'src/gz dnssd https://raw.githubusercontent.com/IETF-Hackathon/mDNSResponder/release/OpenWrt/packages/mips_24kc/base' >> /etc/opkg/customfeeds.conf

Remove the dnsmasq package, since we’re installing a new DNS server, and install the new components we need:

opkg update
opkg remove dnsmasq-full
opkg install isc-dhcp-server-ipv4 mbedtls-util mbedtls-write dnssd-proxy

Generate the TLS certificate for your Discovery Proxy. Generating the key may take as much as 3 minutes. Do not interrupt the key generation process. It’s just sitting there collecting random data, so it will eventually complete.

cd /etc/dnssd-proxy
gen_key type=rsa rsa_keysize=4096 filename=server.key
cert_write selfsign=1 issuer_key=server.key issuer_name=CN=discoveryproxy.home.arpa not_before=20190226000000 not_after=20211231235959 is_ca=1 max_pathlen=0 output_file=server.crt

Create firewall rules to allow Multicast DNS service discovery on the AR750S’s upstream WAN port:

uci add glfw opening
uci set glfw.@opening[-1].name='mDNS'
uci set glfw.@opening[-1].port='5353'
uci set glfw.@opening[-1].proto='UDP'
uci set glfw.@opening[-1].status='Enabled'
uci commit

Configure the DHCP domain which is communicated to clients:

uci set dhcp.isc_dhcpd.domain="service.home.arpa"
uci commit
/etc/init.d/dhcpd restart
reboot

At this point your AR750S Discovery Proxy is configured and ready for use. In this default configuration your AR750S Discovery Proxy is configured to offer unicast Discovery Proxy service on its downstream LAN ports and Wi-Fi, using Multicast DNS on its upstream WAN port (your existing home network) to discover existing services on that network. This makes services on the AR750S’s upstream WAN port visible to clients on the AR750S’s downstream LAN ports and Wi-Fi, even though those clients are not on the same link or IPv4 subnet as the services they are discovering, and no multicast packets are being forwarded between the client link (AR750S LAN port or Wi-Fi) and the services link (AR750S WAN port). This is possible because existing clients are already able to perform service discovery using unicast DNS queries, in addition to the old way using multicast DNS queries.

Once the AR750S completes its reboot, the Discovery Proxy is available and running. If you’re connecting via Wi-Fi, confirm that your computer is still associated with the AR750S (it may have reverted to your previous Wi-Fi network while the AR750S was rebooting).

IMPORTANT: We are aware of a boot-time race condition. At the instant the Discovery Proxy and the mDNSResponder process start, early in the boot process, there is not yet any configured upstream DNS recursive resolver. Mere milliseconds later the DHCP client obtains the DHCP lease and updates the network configuration information. The mDNSResponder process should notice this cha