mDNSPosix/ReadMe.txt

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