docs/mdns.txt

   1 ---
   2 ---
   3 Multicast DNS Daemon
   4 ====================
   5
   6 == mdns
   7
   8 'This is early stage documentation, but at least attempts to cover
   9 some basic usage, and bring mdns usage out of the dark.'
  10
  11 mDNS, also known as Bonjour or zero-configuration networking, enables automatic
  12 discovery of computers, devices, and services on IP networks.  It is
  13 an internet standard documented in link:https://tools.ietf.org/html/rfc6762[RFC6762]
  14
  15 The 'mdns' package provides a compact implementation of this standard, well
  16 integrated with the 'LEDE' system environment. In particular, almost all
  17 interaction with the daemon is via link:ubus.html[ubus]
  18
  19 === Alternatives
  20
  21 * mdnsd - provided by Apple's mDNSResponder package
  22 * avahi-* - A fairly full, but quite large implementation
  23
  24 === Browsing announced services
  25
  26 ----
  27 $ ubus call mdns scan
  28 # wait a second or two
  29 $ ubus call mdns browse
  30 # big json dump example...
  31         ....
  32         "_printer._tcp": {
  33                 "HP\\032Color\\032LaserJet\\032CP2025dn\\032(28A6CC)": {
  34                         "port": 515,
  35                         "txt": "txtvers=1",
  36                         "txt": "qtotal=1",
  37                         "txt": "rp=RAW",
  38                         "txt": "ty=HP Color LaserJet CP2025dn",
  39                         "txt": "product=(HP Color LaserJet CP2025dn)",
  40                         "txt": "priority=50",
  41                         "txt": "adminurl=http:\/\/NPI28A6CC.local.",
  42                         "txt": "Transparent=T",
  43                         "txt": "Binary=T",
  44                         "txt": "TBCP=T"
  45                 },
  46                 "HP\\032LaserJet\\032P3010\\032Series\\032[46A14F]": {
  47                         "port": 515,
  48                         "txt": "txtvers=1",
  49                         "txt": "qtotal=4",
  50                         "txt": "rp=RAW",
  51                         "txt": "pdl=application\/postscript,application\/vnd.hp-PCL,application\/vnd.hp-PCLXL",
  52                         "txt": "ty=HP LaserJet P3010 Series",
  53                         "txt": "product=(HP LaserJet P3010 Series)",
  54                         "txt": "usb_MFG=Hewlett-Packard",
  55                         "txt": "usb_MDL=HP LaserJet P3010 Series",
  56                         "txt": "priority=52",
  57                         "txt": "adminurl=http:\/\/NPI46A14F.local."
  58                 },
  59         ....
  60 ----
  61
  62 ==== Issues/Bugs
  63
  64 * IP addresses are missing
  65 * TXT records aren't valid json in the dump, so jsonfilter can't be used.
  66 * How long is data cached? What causes it to update? No idea.
  67
  68 === Announcing local services
  69 'mdns' scans all the services listed in 'ubus' (`ubus call service list`) and
  70 looks for 'mdns' objects in their data object.  You can view this more
  71 selectively for example with:
  72 ----
  73 # ubus call service list | jsonfilter -e '@[*].instances[*].data.mdns'
  74 { "ssh_22": { "service": "_ssh._tcp.local", "port": 22, "txt": [ "daemon=dropbear" ] } }
  75 ----
  76
  77 Here we can see that ssh is being advertised locally.
  78
  79 If you want to advertise your own service, your service needs to (*AT THE
  80 TIME OF WRITING*) be a link:procd.html[procd] managed service.  You can use the `procd_add_mdns`
  81 call to provide a basic definition.
  82 ----
  83 procd_open_instance
  84 ....
  85 procd_add_mdns <service> <proto> <port> [<textkey=textvalue> ... ]
  86 ...
  87 procd_close_instance
  88 ----
  89
  90 As an example, the following call
  91 ----
  92 procd_add_mdns "hoho" "tcp" "99" "daemon=special" "colour=fuschia"
  93 ----
  94 will result in advertising `_hoho._tcp.local` with two text records.
  95
  96 If you wish to create a more complicated mdns information block, see
  97 'procd_add_mdns_service' in '/lib/functions/procd.sh' but be warned that mdns
  98 probably can't automatically support everything you can represent in json.
  99