mDNSPosix/ReadMe.txt

   1 ReadMe About mDNSPosix
   2 ----------------------
   3
   4 mDNSPosix is a port of Apple's core mDNS code to Posix platforms.
   5
   6 mDNS is short for "multicast DNS", which is a technology that allows you
   7 to register IP services and browse the network for those services.  For
   8 more information about mDNS, see the mDNS web site.
   9
  10   <http://www.multicastdns.org/>
  11
  12 mDNS is part of a family of technologies resulting from the efforts of
  13 the IETF zeroconf working group.  For information about other zeroconf
  14 technologies, see the zeroconf web site.
  15
  16   <http://www.zeroconf.org/>
  17
  18 Apple uses the trade mark "Bonjour" to describe our implementation of
  19 zeroconf technologies.  This sample is designed to show how easy it is
  20 to make a device "Bonjour compatible".
  21
  22 The code in this sample was compiled and tested on Mac OS X (10.1.x,
  23 10.2, 10.3), Solaris (SunOS 5.8), Linux (Redhat 2.4.9-21, Fedora Core 1),
  24 and OpenBSD (2.9). YMMV.
  25
  26
  27 Packing List
  28 ------------
  29
  30 The sample uses the following directories:
  31
  32 o mDNSCore -- A directory containing the core mDNS code.  This code
  33   is written in pure ANSI C and has proved to be very portable.
  34   Every platform needs this core protocol engine code.
  35
  36 o mDNSShared -- A directory containing useful code that's not core to
  37   the main protocol engine itself, but nonetheless useful, and used by
  38   more than one (but not necessarily all) platforms.
  39
  40 o mDNSPosix -- The files that are specific to Posix platforms: Linux,
  41   Solaris, FreeBSD, NetBSD, OpenBSD, etc. This code will also work on
  42   OS X, though that's not its primary purpose.
  43
  44 o Clients -- Example client code showing how to use the API to the
  45   services provided by the daemon.
  46
  47
  48 Building the Code
  49 -----------------
  50
  51 The sample does not use autoconf technology, primarily because I didn't
  52 want to delay shipping while I learnt how to use it.  Thus the code
  53 builds using a very simple make file.  To build the sample you should
  54 cd to the mDNSPosix directory and type "make os=myos", e.g.
  55
  56     make os=panther
  57
  58 For Linux you would change that to:
  59
  60     make os=linux
  61
  62 There are definitions for each of the platforms I ported to.  If you're
  63 porting to any other platform please add appropriate definitions for it
  64 and send us the diffs so they can be incorporated into the main
  65 distribution.
  66
  67
  68 Using the Sample
  69 ----------------
  70 When you compile, you will get:
  71
  72 o Main products for general-purpose use (e.g. on a desktop computer):
  73   - mdnsd
  74   - libmdns
  75   - nss_mdns (See nss_ReadMe.txt for important information about nss_mdns)
  76
  77 o Standalone products for dedicated devices (printer, network camera, etc.)
  78   - mDNSClientPosix
  79   - mDNSResponderPosix
  80   - mDNSProxyResponderPosix
  81
  82 o Debugging tools
  83   - mDNSNetMonitor
  84   - mDNSIdentify
  85
  86 As root type "make install" to install six things:
  87 o mdnsd                   (usually in /usr/sbin)
  88 o libmdns                 (usually in /usr/lib)
  89 o dns_sd.h                (usually in /usr/include)
  90 o startup scripts         (e.g. in /etc/rc.d)
  91 o manual pages            (usually in /usr/share/man)
  92 o nss_mdns                (usually in /lib)
  93 o nss configuration files (usually in /etc)
  94
  95 Once you've installed the files in their respective places,
  96 you need to start the daemon running, either by rebooting,
  97 or by running the startup script "/etc/init.d/mdns start"
  98 (the exact path may be different on your system).
  99 Then you can cd to the "Clients" folder and type "make".
 100 This builds a test client showing how to exercise all the major
 101 functionality of the daemon.
 102
 103
 104 How It Works
 105 ------------
 106                                                    +--------------------+
 107                                                    | Client Application |
 108    +----------------+                              +--------------------+
 109    |  uds_daemon.c  | <--- Unix Domain Socket ---> |      libmdns       |
 110    +----------------+                              +--------------------+
 111    |    mDNSCore    |
 112    +----------------+
 113    |  mDNSPosix.c   |
 114    +----------------+
 115
 116 mdnsd is divided into three sections.
 117
 118 o mDNSCore is the main protocol engine
 119 o mDNSPosix.c provides the glue it needs to run on a Posix OS
 120 o uds_daemon.c exports a Unix Domain Socket interface to
 121   the services provided by mDNSCore
 122
 123 Client applications link with the libmdns, which implements the functions
 124 defined in the dns_sd.h header file, and implements the IPC protocol
 125 used to communicate over the Unix Domain Socket interface to the daemon.
 126
 127 Note that, strictly speaking, nss_mdns could be just another client of
 128 mdnsd, linking with libmdns just like any other client. However, because
 129 of its central role in the normal operation of multicast DNS, it is built
 130 and installed along with the other essential system support components.
 131
 132
 133 Clients for Embedded Systems
 134 ----------------------------
 135
 136 For small devices with very constrained resources, with a single address
 137 space and (typically) no virtual memory, the uds_daemon.c/UDS/libmdns
 138 layer may be eliminated, and the Client Application may live directly
 139 on top of mDNSCore:
 140
 141     +--------------------+
 142     | Client Application |
 143     +--------------------+
 144     |      mDNSCore      |
 145     +--------------------+
 146     |    mDNSPosix.c     |
 147     +--------------------+
 148
 149 Programming to this model is more work, so using the daemon and its
 150 library is recommended if your platform is capable of that.
 151
 152 The runtime behaviour when using the embedded model is as follows:
 153
 154 1. The application calls mDNS_Init, which in turns calls the platform
 155    (mDNSPlatformInit).
 156
 157 2. mDNSPlatformInit gets a list of interfaces (get_ifi_info) and registers
 158    each one with the core (mDNS_RegisterInterface).  For each interface
 159    it also creates a multicast socket (SetupSocket).
 160
 161 3. The application then calls select() repeatedly to handle file descriptor
 162    events. Before calling select() each time, the application calls
 163    mDNSPosixGetFDSet() to give mDNSPosix.c a chance to add its own file
 164    descriptors to the set, and then after select() returns, it calls
 165    mDNSPosixProcessFDSet() to give mDNSPosix.c a chance to receive and
 166    process any packets that may have arrived.
 167
 168 4. When the core needs to send a UDP packet it calls
 169    mDNSPlatformSendUDP.  That routines finds the interface that
 170    corresponds to the source address requested by the core, and
 171    sends the datagram using the UDP socket created for the
 172    interface.  If the socket is flow send-side controlled it just
 173    drops the packet.
 174
 175 5. When SocketDataReady runs it uses a complex routine,
 176    "recvfrom_flags", to actually receive the packet.  This is required
 177    because the core needs information about the packet that is
 178    only available via the "recvmsg" call, and that call is complex
 179    to implement in a portable way.  I got my implementation of
 180    "recvfrom_flags" from Stevens' "UNIX Network Programming", but
 181    I had to modify it further to work with Linux.
 182
 183 One thing to note is that the Posix platform code is very deliberately
 184 not multi-threaded.  I do everything from a main loop that calls
 185 "select()".  This is good because it avoids all the problems that often
 186 accompany multi-threaded code. If you decide to use threads in your
 187 platform, you will have to implement the mDNSPlatformLock() and
 188 mDNSPlatformUnlock() calls which are currently no-ops in mDNSPosix.c.
 189
 190
 191 Once you've built the embedded samples you can test them by first
 192 running the client, as shown below.
 193
 194   quinn% build/mDNSClientPosix
 195   Hit ^C when you're bored waiting for responses.
 196
 197 By default the client starts a search for AppleShare servers and then
 198 sits and waits, printing a message when services appear and disappear.
 199
 200 To continue with the test you should start the responder in another
 201 shell window.
 202
 203   quinn% build/mDNSResponderPosix -n Foo
 204
 205 This will start the responder and tell it to advertise a AppleShare
 206 service "Foo".  In the client window you will see the client print out
 207 the following as the service shows up on the network.
 208
 209   quinn% build/mDNSClientPosix
 210   Hit ^C when you're bored waiting for responses.
 211   *** Found name = 'Foo', type = '_afpovertcp._tcp.', domain = 'local.'
 212
 213 Back in the responder window you can quit the responder cleanly using
 214 SIGINT (typically ^C).
 215
 216   quinn% build/mDNSResponderPosix -n Foo
 217   ^C
 218   quinn%
 219
 220 As the responder quits it will multicast that the "Foo" service is
 221 disappearing and the client will see that notification and print a
 222 message to that effect (shown below).  Finally, when you're done with
 223 the client you can use SIGINT to quit it.
 224
 225   quinn% build/mDNSClientPosix
 226   Hit ^C when you're bored waiting for responses.
 227   *** Found name = 'Foo', type = '_afpovertcp._tcp.', domain = 'local.'
 228   *** Lost  name = 'Foo', type = '_afpovertcp._tcp.', domain = 'local.'
 229   ^C
 230   quinn%
 231
 232 If things don't work, try starting each program in verbose mode (using
 233 the "-v 1" option, or very verbose mode with "-v 2") to see if there's
 234 an obvious cause.
 235
 236 That's it for the core functionality.  Each program supports a variety
 237 of other options.  For example, you can advertise and browse for a
 238 different service type using the "-t type" option.  Use the "-?" option
 239 on each program for more user-level information.
 240
 241
 242 Caveats
 243 -------
 244 Currently the program uses a simple make file.
 245
 246 There are various problems with loopback-only self discovery.  The code
 247 will attempt service discovery on the loopback interface only if no
 248 other interfaces are available.  However, this exposes a number of
 249 problems with the underlying network stack (at least on Mac OS X).
 250
 251 o On Mac OS X 10.1.x the code fails to start on the loopback interface
 252   because the IP_ADD_MEMBERSHIP option returns ENOBUFS.
 253
 254 o On Mac OS X 10.2 the loopback-only case fails because
 255   mDNSPlatformSendUDP's call to "sendto" fails with error EHOSTUNREACH
 256   [Radar ID 3016042].
 257
 258 I haven't been able to test the loopback-only case on other platforms
 259 because I don't have access to the physical machine.
 260
 261
 262 Licencing
 263 ---------
 264 This code is distributed under the Apple Public Source License.
 265 Information about the licence is included at the top of each source file.
 266
 267
 268 Credits and Version History
 269 ---------------------------
 270 If you find any problems with this sample, mail <dts@apple.com> and I
 271 will try to fix them up.
 272
 273 1.0a1 (Jul 2002) was a prerelease version that was distributed
 274 internally at Apple.
 275
 276 1.0a2 (Jul 2002) was a prerelease version that was distributed
 277 internally at Apple.
 278
 279 1.0a3 (Aug 2002) was the first shipping version.  The core mDNS code is
 280 the code from Mac OS 10.2 (Jaguar) GM.
 281
 282 Share and Enjoy
 283
 284 Apple Developer Technical Support
 285 Networking, Communications, Hardware
 286
 287 6 Aug 2002
 288
 289
 290 To Do List
 291 ----------
 292 • port to a System V that's not Solaris
 293 • use sig_atomic_t for signal to main thread flags