README

   1
   2                                  nss-mdns 0.10
   3
   4    Copyright 2004-2007 Lennart Poettering <mzaffzqaf (at) 0pointer (dot)
   5    de>
   6      * [1]License
   7      * [2]News
   8      * [3]Overview
   9      * [4]Current Status
  10      * [5]Documentation
  11      * [6]Requirements
  12      * [7]Installation
  13      * [8]Acknowledgements
  14      * [9]Download
  15
  16 License
  17
  18    This program is free software; you can redistribute it and/or modify
  19    it under the terms of the GNU Lesser General Public License as
  20    published by the Free Software Foundation; either version 2 of the
  21    License, or (at your option) any later version.
  22
  23    This program is distributed in the hope that it will be useful, but
  24    WITHOUT ANY WARRANTY; without even the implied warranty of
  25    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  26    Lesser General Public License for more details.
  27
  28    You should have received a copy of the GNU Lesser General Public
  29    License along with this program; if not, write to the Free Software
  30    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  31
  32 News
  33
  34    Sat May 12 2007:
  35
  36    [10]Version 0.10 released. Changes include: Ported to FreeBSD;
  37    alignment fixes for SPARC.
  38
  39    Mon Jan 1 2007:
  40
  41    [11]Version 0.9 released. Changes include: Make most shared library
  42    symbols private to not conflict with any symbols of the program we're
  43    loaded into. Fix a potential endless loop in the mDNS packet parsing
  44    code.
  45
  46    Please note that due to security reasons from this release on the
  47    minimal mDNS stack included in nss-mdns (dubbed "legacy") is no longer
  48    built by default. Thus, nss-mdns will not work unless [12]Avahi is
  49    running! That makes Avahi essentially a hard dependency of nss-mdns.
  50    Pass --enable-legacy to reenable the mini mDNS stack again. Please
  51    note as well that this release does not honour /etc/resolv.conf domain
  52    search lists by default anymore. It created a lot of problems and was
  53    never recommended anyway. You may reenable this functionality by
  54    passing --enable-search-domains.
  55
  56    Sat Apr 29 2006:
  57
  58    [13]Version 0.8 released. Changes include: Build time option to
  59    disable "legacy unicast" mDNS requests, i.e. resolve exclusively with
  60    Avahi; build a special _minimal flavour of the shared objects to
  61    minimize unnecessary name lookup timeouts; fix IPv6 resolving when
  62    using Avahi.
  63
  64    Please note that starting with nss-mdns 0.8 we encourage you to use a
  65    different /etc/nsswitch.conf configuration line. See below for more
  66    information!
  67
  68    Sat Nov 19 2005:
  69
  70    [14]Version 0.7 released. Changes include: Portability patch for ARM
  71    from Philipp Zabel; make sure not to print any messages to STDERR;
  72    deal with OOM situations properly; if multiple addresses are assigned
  73    to the same interface make sure to send a query packet only once;
  74    other cleanups
  75
  76    Sun Aug 21 2005:
  77
  78    [15]Version 0.6 released. Changes include: honour search list in
  79    /etc/resolv.conf; try to contact [16]Avahi for resolving.
  80
  81    Sat Jun 4 2005:
  82
  83    [17]Version 0.5 released. Changes include: only lookup hostnames
  84    ending in .local; add support for a configuration file
  85    (/etc/mdns.allow) to allow lookups for other names.
  86
  87    Sun May 15 2005:
  88
  89    [18]Version 0.4 released. Changes include: small portability fix for
  90    big endian architectures; send "legacy unicast" packets instead of
  91    normal mDNS packets (this should reduce traffic and improve response
  92    time)
  93
  94    Jan Sun 16 2005:
  95
  96    [19]Version 0.3 released. Changes include: add Debianization; use
  97    ip6.arpa instead of ip6.int for reverse IPv6 lookups.
  98
  99    Fri Dec 17 2004:
 100
 101    [20]Version 0.2 released. Changes include: send mDNS queries on every
 102    interface that supports multicasts, instead of only the one with the
 103    default route, making nss-mdns more robust on multi-homed hosts; gcc
 104    2.95 compatiblity.
 105
 106    Mon Dec 6 2004:
 107
 108    [21]Version 0.1 released
 109
 110 Overview
 111
 112    nss-mdns is a plugin for the GNU Name Service Switch (NSS)
 113    functionality of the GNU C Library (glibc) providing host name
 114    resolution via [22]Multicast DNS (aka Zeroconf, aka Apple Rendezvous,
 115    aka Apple Bonjour), effectively allowing name resolution by common
 116    Unix/Linux programs in the ad-hoc mDNS domain .local.
 117
 118    nss-mdns provides client functionality only, which means that you have
 119    to run a mDNS responder daemon seperately from nss-mdns if you want to
 120    register the local host name via mDNS. I recommend [23]Avahi.
 121
 122    nss-mdns is very lightweight (9 KByte stripped binary .so compiled
 123    with -DNDEBUG=1 -Os on i386, gcc 4.0), has no dependencies besides the
 124    glibc and requires only minimal configuration.
 125
 126    By default nss-mdns tries to contact a running [24]avahi-daemon for
 127    resolving host names and addresses and making use of its superior
 128    record cacheing. Optionally nss-mdns can be compiled with a mini mDNS
 129    stack that can be used to resolve host names without a local Avahi
 130    installation. Both Avahi support and this mini mDNS stack are
 131    optional, however at least one of them needs to be enabled. If both
 132    are enabled a connection to Avahi is tried first, and if that fails
 133    the mini mDNS stack is used.
 134
 135 Current Status
 136
 137    It works!
 138
 139    If the mini MDNS stack is used, nss-mdns supports resolving IPv6
 140    addresses but does so via IPv4 multicasts only. If Avahi is used for
 141    resolving IPv6 is supported properly.
 142
 143 Documentation
 144
 145    After compiling and installing nss-mdns you'll find six new NSS
 146    modules in /lib:
 147      * libnss_mdns.so.2
 148      * libnss_mdns4.so.2
 149      * libnss_mdns6.so.2
 150      * libnss_mdns_minimal.so.2
 151      * libnss_mdns4_minimal.so.2
 152      * libnss_mdns6_minimal.so.2
 153
 154    libnss_mdns.so.2 resolves both IPv6 and IPv4 addresses,
 155    libnss_mdns4.so.2 only IPv4 addresses and libnss_mdns6.so.2 only IPv6
 156    addresses. Due to the fact that most mDNS responders only register
 157    local IPv4 addresses via mDNS, most people will want to use
 158    libnss_mdns4.so.2 exclusively. Using libnss_mdns.so.2 or
 159    libnss_mdns6.so.2 in such a situation causes long timeouts when
 160    resolving hosts since most modern Unix/Linux applications check for
 161    IPv6 addresses first, followed by a lookup for IPv4.
 162
 163    libnss_mdns{4,6,}_minimal.so (new in version 0.8) is mostly identical
 164    to the versions without _minimal. However, they differ in one way. The
 165    minimal versions will always deny to resolve host names that don't end
 166    in .local or addresses that aren't in the range 169.254.x.x (the range
 167    used by [25]IPV4LL/APIPA/RFC3927.) Combining the _minimal and the
 168    normal NSS modules allows us to make mDNS authoritative for Zeroconf
 169    host names and addresses (and thus creating no extra burden on DNS
 170    servers with always failing requests) and use it as fallback for
 171    everything else.
 172
 173    To activate one of the NSS modules you have to edit /etc/nsswitch.conf
 174    and add mdns4 and mdns4_minimal (resp. mdns, mdns6) to the line
 175    starting with "hosts:". On Debian this looks like this:
 176 # /etc/nsswitch.conf
 177
 178 passwd:         compat
 179 group:          compat
 180 shadow:         compat
 181
 182 hosts:          files mdns4_minimal [NOTFOUND=return] dns mdns4
 183 networks:       files
 184
 185 protocols:      db files
 186 services:       db files
 187 ethers:         db files
 188 rpc:            db files
 189
 190 netgroup:       nis
 191
 192    That's it. You should now be able to resolve hosts from the .local
 193    domain with all your applications. For a quick check use glibc's
 194    getent tool:
 195 $ getent hosts foo.local
 196 192.168.50.4    foo.local
 197
 198    Replace foo whith a host name that has been registered with an mDNS
 199    responder. (Don't try to use the tools host or nslookup for these
 200    tests! They bypass the NSS and thus nss-mdns and issue their DNS
 201    queries directly.)
 202
 203    If you run a firewall, don't forget to allow UDP traffic to the the
 204    mDNS multicast address 224.0.0.251 on port 5353.
 205
 206    Please note: The line above makes nss-mdns authoritative for the
 207    .local domain. If you have a unicast DNS domain with the same name you
 208    will no longer be able to resolve hosts from it. mDNS and a unicast
 209    DNS domain named .local are inherently incompatible. Please contact
 210    your local admistrator and ask him to move to a different domain name
 211    since .local is to be used exclusively for Zeroconf technology.
 212    [26]Further information.
 213
 214    Starting with version 0.5, nss-mdns has a simple configuration file
 215    /etc/mdns.allow for enabling name lookups via mDNS in other domains
 216    than .local. The file contains valid domain suffixes, seperated by
 217    newlines. Empty lines are ignored as are comments starting with #. To
 218    enable mDNS lookups of all names, regardless of the domain suffix add
 219    a line consisting of * only (similar to nss-mdns mode of operation of
 220    versions <= 0.4):
 221 # /etc/mdns.allow
 222 *
 223
 224    If the configuration file is absent or unreadable nss-mdns behaves as
 225    if a configuration file with the following contents is read:
 226 # /etc/mdns.allow
 227 .local.
 228 .local
 229
 230    i.e. only hostnames ending with .local are resolved via mDNS.
 231
 232    If the configuration file is existent but empty, mDNS name lookups are
 233    disabled completely. Please note that usually mDNS is not used for
 234    anything but .local, hence you usually don't want to touch this file.
 235
 236 Requirements
 237
 238    Currently, nss-mdns is tested on Linux only. A fairly modern glibc
 239    installation with development headers (2.0 or newer) is required. Not
 240    suprisingly nss-mdns requires a kernel compiled with IPv4 multicasting
 241    support enabled. [27]Avahi is recommended for its superior cacheing
 242    capabilities and for security reasons. Unless you compile nss-mdns
 243    with --enable-legacy Avahi is a hard dependency when nss-mdns is used,
 244    however not a build-time requirement.
 245
 246    nss-mdns was developed and tested on Debian GNU/Linux "testing" from
 247    December 2004, it should work on most other Linux distributions (and
 248    maybe Unix versions) since it uses GNU autoconf and GNU libtool for
 249    source code configuration and shared library management.
 250
 251 Installation
 252
 253    As this package is made with the GNU autotools you should run
 254    ./configure inside the distribution directory for configuring the
 255    source tree. After that you should run make for compilation and make
 256    install (as root) for installation of nss-mdns.
 257
 258 Acknowledgements
 259
 260    SHIROYAMA Takayuki, Anand Kumria and Bastien Nocera, Sjoerd Simons for
 261    patches.
 262
 263    Sean Meiners for search list support.
 264
 265    Philipp Zabel for ARM support.
 266
 267    Bruce M Simpson for porting it to FreeBSD.
 268
 269 Download
 270
 271    The newest release is always available from
 272    [28]http://0pointer.de/lennart/projects/nss-mdns/
 273
 274    The current release is [29]0.10
 275
 276    Get nss-mdns's development sources from the [30]Subversion
 277    [31]repository ([32]viewcvs):
 278 svn checkout svn://svn.0pointer.de/nss-mdns/trunk nss-mdns
 279
 280    You may find an up to date Debian package of nss-mdns on the
 281    [33]Debian package repository. Many other distributions ship it, too.
 282
 283    If you want to be notified whenever I release a new version of this
 284    software use the subscription feature of [34]Freshmeat.
 285      _________________________________________________________________
 286
 287
 288     Lennart Poettering <mzaffzqaf (at) 0pointer (dot) de>, May 2007
 289
 290    $Id: README.html.in 116 2007-05-12 14:54:24Z lennart $
 291
 292 References
 293
 294    1. README#license
 295    2. README#news
 296    3. README#overview
 297    4. README#status
 298    5. README#documentation
 299    6. README#requirements
 300    7. README#installation
 301    8. README#acks
 302    9. README#download
 303   10. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.10.tar.gz
 304   11. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.9.tar.gz
 305   12. http://avahi.org/
 306   13. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.8.tar.gz
 307   14. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.7.tar.gz
 308   15. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.6.tar.gz
 309   16. http://avahi.org/
 310   17. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.5.tar.gz
 311   18. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.4.tar.gz
 312   19. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.3.tar.gz
 313   20. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.2.tar.gz
 314   21. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.1.tar.gz
 315   22. http://www.multicastdns.org/
 316   23. http://avahi.org/
 317   24. http://avahi.org/
 318   25. http://files.zeroconf.org/rfc3927.txt
 319   26. http://avahi.org/wiki/AvahiAndUnicastDotLocal
 320   27. http://avahi.org/
 321   28. http://0pointer.de/lennart/projects/nss-mdns/
 322   29. http://0pointer.de/lennart/projects/nss-mdns/nss-mdns-0.10.tar.gz
 323   30. http://subversion.tigris.org/
 324   31. svn://svn.0pointer.de/nss-mdns
 325   32. http://0pointer.de/cgi-bin/viewcvs.cgi/?root=nss-mdns
 326   33. http://packages.debian.org/libnss-mdns
 327   34. http://freshmeat.net/projects/nss-mdns/