Created
February 8, 2025 16:09
-
-
Save stokito/abc5af50733126dd9a65f796a42f717e to your computer and use it in GitHub Desktop.
Revisions
-
stokito created this gist
Feb 8, 2025 .There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,168 @@ ====== Multicast DNS Daemon ====== ===== umdns ===== //This is early stage documentation, but at least attempts to cover some basic usage, and bring umdns usage out of the dark.// mDNS, also known as Bonjour or zero-configuration networking (ZeroConf) or DNS Service Discovery (DNS-SD), enables automatic discovery of computers, devices, and services on IP networks. It is an internet standard documented in [[https://tools.ietf.org/html/rfc6762|RFC6762]]. The [[packages:pkgdata:umdns]] package provides a compact implementation of this standard, well integrated with the OpenWrt system environment. In particular, almost all interaction with the daemon is via [[docs:guide-developer:ubus]]. ==== Alternatives ==== See [[docs:guide-user:network:zeroconfig:zeroconf|Zero configuration networking in OpenWrt]] ==== Config File ==== <code bash /etc/config/umdns> config umdns option jail 1 # enables jail - see procd list network lan list network dmz # Provides visibility into both networks, but does not act as a repeater </code> Note that it may be unsafe to enable umdns on ''wan'' interface. Note that ''%%network list%%'' argument refers to interface name under ''%%/etc/config/network%%'' not the device name shown by ''%%ifconfig%%''. Test if you using the right name with ''%%ifstatus%%''. So if you have something like ''%%config interface 'vlan1'%%'' in your ''%%/etc/config/network%%'', use ''%%vlan1%%''. ==== Install ==== umdns is available starting from OpenWRT 17 and to install it execute ''opkg install umdns'' ==== Firewall ==== If you need to advertise on WAN or other networks then UDP port 5353 should be opened in firewall: <code bash /etc/config/firewall> config rule option src_port '5353' option src '*' option name 'Allow-mDNS' option target 'ACCEPT' option dest_ip '224.0.0.251' option dest_port '5353' option proto 'udp' </code> To configure from GUI see "Firewall rules" section of [[https://blog.christophersmart.com/2020/03/30/resolving-mdns-across-vlans-with-avahi-on-openwrt/|Resolving mDNS across VLANs with Avahi on OpenWRT]] ==== Browsing announced services ==== <code> $ ubus call umdns update # wait a second or two $ ubus call umdns browse # big json dump example... .... "_printer._tcp": { "HP\\032Color\\032LaserJet\\032CP2025dn\\032(28A6CC)": { "port": 515, "txt": "txtvers=1", "txt": "qtotal=1", "txt": "rp=RAW", "txt": "ty=HP Color LaserJet CP2025dn", "txt": "product=(HP Color LaserJet CP2025dn)", "txt": "priority=50", "txt": "adminurl=http:\/\/NPI28A6CC.local.", "txt": "Transparent=T", "txt": "Binary=T", "txt": "TBCP=T" }, "HP\\032LaserJet\\032P3010\\032Series\\032[46A14F]": { "port": 515, "txt": "txtvers=1", "txt": "qtotal=4", "txt": "rp=RAW", "txt": "pdl=application\/postscript,application\/vnd.hp-PCL,application\/vnd.hp-PCLXL", "txt": "ty=HP LaserJet P3010 Series", "txt": "product=(HP LaserJet P3010 Series)", "txt": "usb_MFG=Hewlett-Packard", "txt": "usb_MDL=HP LaserJet P3010 Series", "txt": "priority=52", "txt": "adminurl=http:\/\/NPI46A14F.local." }, .... $ ubus call umdns hosts #Show hosts discovered via mDns "SteakPrinter.local": { "ipv4": "192.168.1.159" }, "Upstairs.local": { "ipv4": "192.168.1.151" }, </code> ==== Issues/Bugs ==== * IP addresses are missing. * TXT records aren't valid json in the dump, so jsonfilter can't be used. * How long is data cached? What causes it to update? No idea. * You may not see locally advertised services with ''ubus call umdns browse''. See the [[https://forum.openwrt.org/t/how-to-announce-service-with-umdns/5029/7|discussion]] ==== Announcing local services ==== The umdns scans all the services listed in ubus (''ubus call service list'') and looks for ''mdns'' objects in their data object. You can view this more selectively for example with: <code> # ubus call service list | jsonfilter -e "$[*]['instances'][*]['data']['mdns']" { "ssh_22": { "service": "_ssh._tcp.local", "port": 22, "txt": [ "daemon=dropbear" ] } } </code> Here we can see that ssh is being advertised locally. If you want to advertise your own service, your service needs to be a [[docs:guide-developer:procd]] managed service. You can use the ''procd_add_mdns'' call to provide a basic definition. <code> procd_open_instance .... procd_add_mdns <service> <proto> <port> [<textkey=textvalue> ... ] ... procd_close_instance </code> As an example, the following call <code bash> procd_add_mdns "webdav" "tcp" "80" "path=/nextcloud/remote.php/dav/files/YOUR_USER/" "u=YOUR_USER" </code> will result in advertising ''_webdav._tcp.local'' with two text records. In the example we published a WebDAV folder from Nextcloud and now it can be seen in Network folder of a file manager in GNOME and KDE and can be [[https://kodi.wiki/view/Avahi_Zeroconf|discovered from a Kodi media player]]. The service names may be taken from the [[https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml|IANA register]] and the txt-records may be taken from the official DNS-SD keys (see [[http://www.dns-sd.org/ServiceTypes.html|ServiceTypes]] under "Defined TXT keys". If you wish to create a more complicated mdns information block, see ''procd_add_mdns_service'' in ''/lib/functions/procd.sh'' but be warned that umdns probably can't automatically support everything you can represent in json. ===== Service description files in /etc/umdns ===== umdns advertises the services whose ''*.json'' files are found in ''/etc/umdns''. This is similar to how Avahi advertises ''*.service'' files in ''/etc/avahi/services/''. For example the same WebDAV service description: <code yaml /etc/umdns/nextcloud_webdav.json> { "nextcloud_webdav": { "service": "_webdav._tcp.local", "port": 80, "txt": [ "path=/nextcloud/remote.php/dav/files/YOUR_USER/", "u=YOUR_USER" ] } } </code> Or you can advertise SFTP and SSH: <code yaml /etc/umdns/ssh.json> { "ssh_login": { "service": "_ssh._tcp.local", "port": 22, "txt": [ "u=root" ] }, "sftp_share": { "service": "_sftp-ssh._tcp.local", "port": 22, "txt": [ "path=/", "u=root" ] } } </code> See more examples in [[commit>?p=project/mdnsd.git;a=tree;f=json;hb=HEAD|umdns sources]] The reload the umdns service with: ''ubus call umdns reload'' or ''service umdns reload'' ==== Testing === To see that service was advertised you may use ''avahi-discover'' GUI application. To see from a command line use ''avahi-browse --all''. To find a specific service use: ''avahi-browse -d local _webdav._tcp''.