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 brand name "Rendezvous" to describe our implementation of
  19 zeroconf technologies.  This sample is designed to show how easy it is
  20 to make a device "Rendezvous compatible".
  21
  22 The code in this sample was compiled and tested on Mac OS X (10.1.x,
  23 10.2), Solaris (SunOS 5.6), Linux (Redhat 2.4.9-21), and OpenBSD (2.9).
  24 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
  76 o Standalone products for dedicated devices (printer, network camera, etc.)
  77   - mDNSClientPosix
  78   - mDNSResponderPosix
  79   - mDNSProxyResponderPosix
  80
  81 o Debugging tools
  82   - mDNSNetMonitor
  83   - mDNSIdentify
  84
  85 Type "sudo make install" to install four things:
  86 o mdnsd           (usually in /usr/sbin)
  87 o libmdns         (usually in /usr/lib)
  88 o dns_sd.h        (usually in /usr/include)
  89 o startup scripts (e.g. in /etc/rc.d)
  90
  91 Once you've installed the header and the library, and started the
  92 daemon running, you can cd to the "Clients" folder and type "make".
  93 This builds a test client showing how to exercise all the major
  94 functionality of the daemon.
  95
  96
  97 How It Works
  98 ------------
  99                                                    +--------------------+
 100                                                    | Client Application |
 101    +----------------+                              +--------------------+
 102    |  uds_daemon.c  | <--- Unix Domain Socket ---> |      libmdns       |
 103    +----------------+                              +--------------------+
 104    |    mDNSCore    |
 105    +----------------+
 106    |  mDNSPosix.c   |
 107    +----------------+
 108
 109 mdnsd is divided into three sections.
 110
 111 o mDNSCore is the main protocol engine
 112 o mDNSPosix.c provides the glue it needs to run on a Posix OS
 113 o uds_daemon.c exports a Unix Domain Socket interface to
 114   the services provided by mDNSCore
 115
 116 Client applications link with the libmdns, which implements the functions
 117 defined in the dns_sd.h header file, and implements the IPC protocol
 118 used to communicate over the Unix Domain Socket interface to the daemon.
 119
 120
 121 Clients for Embedded Systems
 122 ----------------------------
 123
 124 For small devices with very constrained resources, with a single address
 125 space and (typically) no virtual memory, the uds_daemon.c/UDS/libmdns
 126 layer may be eliminated, and the Client Application may live directly
 127 on top of mDNSCore:
 128
 129     +--------------------+
 130     | Client Application |
 131     +--------------------+
 132     |      mDNSCore      |
 133     +--------------------+
 134     |    mDNSPosix.c     |
 135     +--------------------+
 136
 137 Programming to this model is more work, so using the daemon and its
 138 library is recommended if your platform is capable of that.
 139
 140 The runtime behaviour when using the embedded model is as follows:
 141
 142 1. The application calls mDNS_Init, which in turns calls the platform
 143    (mDNSPlatformInit).
 144
 145 2. mDNSPlatformInit gets a list of interfaces (get_ifi_info) and registers
 146    each one with the core (mDNS_RegisterInterface).  For each interface
 147    it also creates a multicast socket (SetupSocket).
 148
 149 3. The application then calls select() repeatedly to handle file descriptor
 150    events. Before calling select() each time, the application calls
 151    mDNSPosixGetFDSet() to give mDNSPosix.c a chance to add its own file
 152    descriptors to the set, and then after select() returns, it calls
 153    mDNSPosixProcessFDSet() to give mDNSPosix.c a chance to receive and
 154    process any packets that may have arrived.
 155
 156 4. When the core needs to send a UDP packet it calls
 157    mDNSPlatformSendUDP.  That routines finds the interface that
 158    corresponds to the source address requested by the core, and
 159    sends the datagram using the UDP socket created for the
 160    interface.  If the socket is flow send-side controlled it just
 161    drops the packet.
 162
 163 5. When SocketDataReady runs it uses a complex routine,
 164    "recvfrom_flags", to actually receive the packet.  This is required
 165    because the core needs information about the packet that is
 166    only available via the "recvmsg" call, and that call is complex
 167    to implement in a portable way.  I got my implementation of
 168    "recvfrom_flags" from Stevens' "UNIX Network Programming", but
 169    I had to modify it further to work with Linux.
 170
 171 One thing to note is that the Posix platform code is very deliberately
 172 not multi-threaded.  I do everything from a main loop that calls
 173 "select()".  This is good because it avoids all the problems that often
 174 accompany multi-threaded code. If you decide to use threads in your
 175 platform, you will have to implement the mDNSPlatformLock() and
 176 mDNSPlatformUnlock() calls which are currently no-ops in mDNSPosix.c.
 177
 178
 179 Once you've built the embedded samples you can test them by first
 180 running the client, as shown below.
 181
 182   quinn% build/mDNSClientPosix
 183   Hit ^C when you're bored waiting for responses.
 184
 185 By default the client starts a search for AppleShare servers and then
 186 sits and waits, printing a message when services appear and disappear.
 187
 188 To continue with the test you should start the responder in another
 189 shell window.
 190
 191   quinn% build/mDNSResponderPosix -n Foo
 192
 193 This will start the responder and tell it to advertise a AppleShare
 194 service "Foo".  In the client window you will see the client print out
 195 the following as the service shows up on the network.
 196
 197   quinn% build/mDNSClientPosix
 198   Hit ^C when you're bored waiting for responses.
 199   *** Found name = 'Foo', type = '_afpovertcp._tcp.', domain = 'local.'
 200
 201 Back in the responder window you can quit the responder cleanly using
 202 SIGINT (typically ^C).
 203
 204   quinn% build/mDNSResponderPosix -n Foo
 205   ^C
 206   quinn%
 207
 208 As the responder quits it will multicast that the "Foo" service is
 209 disappearing and the client will see that notification and print a
 210 message to that effect (shown below).  Finally, when you're done with
 211 the client you can use SIGINT to quit it.
 212
 213   quinn% build/mDNSClientPosix
 214   Hit ^C when you're bored waiting for responses.
 215   *** Found name = 'Foo', type = '_afpovertcp._tcp.', domain = 'local.'
 216   *** Lost  name = 'Foo', type = '_afpovertcp._tcp.', domain = 'local.'
 217   ^C
 218   quinn%
 219
 220 If things don't work, try starting each program in verbose mode (using
 221 the "-v 1" option, or very verbose mode with "-v 2") to see if there's
 222 an obvious cause.
 223
 224 That's it for the core functionality.  Each program supports a variety
 225 of other options.  For example, you can advertise and browse for a
 226 different service type using the "-t type" option.  Use the "-?" option
 227 on each program for more user-level information.
 228
 229
 230 Caveats
 231 -------
 232 Currently the program uses a simple make file.
 233
 234 There are various problems with loopback-only self discovery.  The code
 235 will attempt service discovery on the loopback interface only if no
 236 other interfaces are available.  However, this exposes a number of
 237 problems with the underlying network stack (at least on Mac OS X).
 238
 239 o On Mac OS X 10.1.x the code fails to start on the loopback interface
 240   because the IP_ADD_MEMBERSHIP option returns ENOBUFS.
 241
 242 o On Mac OS X 10.2 the loopback-only case fails because
 243   mDNSPlatformSendUDP's call to "sendto" fails with error EHOSTUNREACH
 244   [Radar ID 3016042].
 245
 246 I haven't been able to test the loopback-only case on other platforms
 247 because I don't have access to the physical machine.
 248
 249
 250 Licencing
 251 ---------
 252 This code is distributed under the Apple Public Source License.
 253 Information about the licence is included at the top of each source file.
 254
 255
 256 Credits and Version History
 257 ---------------------------
 258 If you find any problems with this sample, mail <dts@apple.com> and I
 259 will try to fix them up.
 260
 261 1.0a1 (Jul 2002) was a prerelease version that was distributed
 262 internally at Apple.
 263
 264 1.0a2 (Jul 2002) was a prerelease version that was distributed
 265 internally at Apple.
 266
 267 1.0a3 (Aug 2002) was the first shipping version.  The core mDNS code is
 268 the code from Mac OS 10.2 (Jaguar) GM.
 269
 270 Share and Enjoy
 271
 272 Apple Developer Technical Support
 273 Networking, Communications, Hardware
 274
 275 6 Aug 2002
 276
 277
 278 To Do List
 279 ----------
 280 • port to a System V that's not Solaris
 281 • use sig_atomic_t for signal to main thread flags