# nss-mdns @PACKAGE_VERSION@

Copyright 2004,2005 Lennart Poettering <@PACKAGE_BUGREPORT@>

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

## News

Sat Nov 19 2005:

Version 0.7 released. Changes include: Portability patch for ARM from Philipp Zabel; make sure not to print any messages to STDERR; deal with OOM situations properly; if multiple addresses are assigned to the same interface make sure to send a query packet only once; other cleanups

Sun Aug 21 2005:

Version 0.6 released. Changes include: honour search list in `/etc/resolv.conf`; try to contact Avahi for resolving.

Sat Jun 4 2005:

Version 0.5 released. Changes include: only lookup hostnames ending in `.local`; add support for a configuration file (`/etc/mdns.allow`) to allow lookups for other names.

Sun May 15 2005:

Version 0.4 released. Changes include: small portability fix for big endian architectures; send "legacy unicast" packets instead of normal mDNS packets (this should reduce traffic and improve response time)

Jan Sun 16 2005:

Version 0.3 released. Changes include: add Debianization; use `ip6.arpa` instead of `ip6.int` for reverse IPv6 lookups.

Fri Dec 17 2004:

Version 0.2 released. Changes include: send mDNS queries on every interface that supports multicasts, instead of only the one with the default route, making `nss-mdns` more robust on multi-homed hosts; gcc 2.95 compatiblity.

Mon Dec 6 2004:

Version 0.1 released

## Overview

`nss-mdns` is a plugin for the GNU Name Service Switch (NSS) functionality of the GNU C Library (`glibc`) providing host name resolution via Multicast DNS (aka Zeroconf, aka Apple Rendezvous, aka Apple Bonjour), effectively allowing name resolution by common Unix/Linux programs in the ad-hoc mDNS domain `.local`.

`nss-mdns` provides client functionality only, which means that you have to run a mDNS responder daemon seperately from `nss-mdns` if you want to register the local host name via mDNS. I recommend Avahi.

`nss-mdns` is very lightweight (23 KByte stripped binary `.so` compiled with `-DNDEBUG=1 -Os` on i386, `gcc` 4.0), has no dependencies besides the `glibc` and requires only minimal configuration.

Optionally `nss-mdns` can try to contact a running avahi-daemon to make use of its superior record cacheing.

## Current Status

It works!

While `nss-mdns` supports resolving IPv6 addresses it does so via IPv4 multicasts only. (Unless, of course, it finds a running Avahi daemon which supports IPv6 properly.)

## Documentation

After compiling and installing `nss-mdns` you'll find three new NSS modules in `/lib`:

- `libnss_mdns.so.2`
- `libnss_mdns4.so.2`
- `libnss_mdns6.so.2`

`libnss_mdns.so.2` resolves both IPv6 and IPv4 addresses, `libnss_mdns4.so.2` only IPv4 addresses and `libnss_mdns6.so.2` only IPv6 addresses. Due to the fact that most mDNS responders only register local IPv4 addresses via mDNS, most people will want to use `libnss_mdns4.so.2` exclusively. Using `libnss_mdns.so.2` or `libnss_mdns6.so.2` in such a situation causes long timeouts when resolving hosts since most modern Unix/Linux applications check for IPv6 addresses first, followed by a lookup for IPv4.

To activate one of the NSS modules you have to edit `/etc/nsswitch.conf` and add `mdns4` (resp. `mdns`, `mdns6`) to the line starting with "`hosts:`". On Debian this looks like this:

    # /etc/nsswitch.conf

    passwd:         compat
    group:          compat
    shadow:         compat

    hosts:          files dns mdns4
    networks:       files

    protocols:      db files
    services:       db files
    ethers:         db files
    rpc:            db files

    netgroup:       nis

That's it. You should now be able to resolve hosts from the `.local` domain with all your applications. For a quick check use `glibc`'s `getent` tool:

    $ getent hosts foo.local
    192.168.50.4    foo.local

Replace foo whith a host name that has been registered with an mDNS responder.

If you run a firewall, don't forget to allow UDP traffic to the the mDNS multicast address `224.0.0.251` on port 5353.

Starting with version 0.5, `nss-mdns` has a simple configuration file `/etc/mdns.allow` for enabling name lookups via mDNS in other domains than `.local`. The file contains valid domain suffixes, seperated by newlines. Empty lines are ignored as are comments starting with #. To enable mDNS lookups of all names, regardless of the domain suffix add a line consisting of `*` only (similar to `nss-mdns` mode of operation of versions <= 0.4):

    # /etc/mdns.allow
    *

If the configuration file is absent or unreadable `nss-mdns` behaves as if a configuration file with the following contents is read:

    # /etc/mdns.allow
    .local.
    .local

i.e. only hostnames ending with `.local` are resolved via mDNS.

If the configuration file is existent but empty, mDNS name lookups are disabled completely.

## Requirements

Currently, `nss-mdns` is tested on Linux only. A fairly modern `glibc` installation with development headers (2.0 or newer) is required. Not suprisingly `nss-mdns` requires a kernel compiled with IPv4 multicasting support enabled.

`nss-mdns` was developed and tested on Debian GNU/Linux "testing" from December 2004, it should work on most other Linux distributions (and maybe Unix versions) since it uses GNU autoconf and GNU libtool for source code configuration and shared library management.

## Installation

As this package is made with the GNU autotools you should run `./configure` inside the distribution directory for configuring the source tree. After that you should run `make` for compilation and `make install` (as root) for installation of `nss-mdns`.

## Acknowledgements

SHIROYAMA Takayuki for a patch.

Sean Meiners for search list support.

Philipp Zabel for ARM support.

## Download

The newest release is always available from @PACKAGE_URL@

The current release is @PACKAGE_VERSION@

Get `nss-mdns`'s development sources from the Subversion repository (viewcvs):

    svn checkout svn://svn.0pointer.de/nss-mdns/trunk nss-mdns

You may find an up to date Debian package of `nss-mdns` on the Debian package repository. Many other distributions ship it, too.

If you want to be notified whenever I release a new version of this software use the subscription feature of Freshmeat.

$Id: README.html.in 88 2005-11-20 00:56:17Z lennart $