Copyright (C) 2000, 2001  Internet Software Consortium.
See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

$Id: lwres,v 1.5 2001/01/09 21:46:46 bwelling Exp $

This document describes the bind v9 lightweight resolver.

WHY LWRES?

Currently, applications make queries directly to a DNS server.  With
v4 records (A records) the client can typically do the proper DNS work
to get a hostname into an address or vice versa.

With ipv6 and A6 recods, however, this becomes harder.  Add to that
DNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.

To keep clients from having to make direct DNS queries for address
information, an API was developed to allow clients to ask high-level
information, such as "what addresses does foo.nominum.com have?" and
"what name does 1.2.3.4 have?"



GENERAL DESIGN

The lwres library converts structures into wire-format packets for
transmission, and unmarshalls them on receive.



Marshalling and unmarshalling:

Each structure will have two functions defined, one to take a
wire-format packet and convert it into a structure, and another to
take a structure and convert it into a wire-format packet.  There
is a structure cleanup function that will take the unmarshalled
structure and free any dynamically allocated elements.


Wire formats:

All integer values are in network byte order.

All addresses are in network byte order.  That is, they are directly
usable and do not need to be byte swapped, at least for ipv4 and ipv6.

All character strings are prefixed with a length, and are NUL
terminated C strings.  This is a concession for structure handling on
the receive side, and allows a mapping structure to point to data
contained in the actual receive buffer, eliminating copying.


NOOP (aka ping) packet format (request, response):

	lwres_lwpacket_t header;
	isc_uint16_t datalength;
	< datalength bytes >

The server simply returns the entire data region in the reply.  This
allows the client to determine if the server is operational.


GETADDRSBYNAME (response):

	lwres_lwpacket_t header;

	isc_uint16_t naliases;

	isc_uint16_t naddrs;

	isc_uint16_t real_name_len;
	< real_name_len bytes of name >
	isc_uint8_t \0

	< naliases of
		isc_uint16_t len;
		< len bytes of name >
		isc_uint8_t \0
	>

	< naddrs of
		isc_uint32_t family;
		isc_uint16_t len;
		< len bytes of address >
	>


GETNAMEBYADDR (response):

	lwres_lwpacket_t header;

	isc_uint16_t naliases;

	isc_uint16_t real_name_len;
	< real_name_len bytes of name >
	isc_uint8_t \0

	< naliases of
		isc_uint16_t len;
		< len bytes of name >
		isc_uint8_t \0
	>



FUNCTIONS PROVIDED

The lwres library provides three functions per data item.  One takes a
structure and marshalls it into a buffer.  Another unmarshalls that
data into a structure.  A third frees memory used to unmarshall the
data.

There are two structures used in a typical request/response.  The
basic sequence is for the client to marshall the request into a
buffer and to transmit the request to the server.  The server will
unmarshall the request, process it, and fill in a structure with the
response.  The response is marshalled by the server, transmitted to
the client, where it is unmarshalled and used by the client.



CLIENT CONTEXT

Each client instance has its own state that is created and maintained
through library calls.  Each thread needs its own client context, or
locking must be provided by the client to ensure private access to the
structure while lwres_*() calls are in progress.

When a client context is created, /etc/resolv.conf is read to find
various options, including search lists, sort lists, etc.



API

The simpliest interface is to call lwres_getaddrsbyname() or
lwres_getnamebyaddr(), both of which are blocking calls.  That is, a
packet is transmitted to the local lightweight resolver, and the call
will not return until a response is received or the timeout period
expires.

If a caller requires non-blocking operation, the caller must call the
lower-level marshalling and unmarshalling functions directly.  See the
source code implementing the blocking calls for more information, in
lib/lwres/lwresutil.c.



LIBC INTEGRATION

Several sample implementations for gethostbyname() etc. are provided
in the lib/lwres/ directory.  These are considered to be examples
only.  They have been merged into a local copy of NetBSD's libc, but
they are not drop-in replacements for most operating systems.  They do
not provide NIS support or /etc/hosts support.



LWRES DAEMON

The daemon (in bin/lwresd/) implements name->address and address->name
resolution using the bind9 dns library functions.  Currently, it will
read /etc/resolv.conf and use any "nameserver" lines as forwarders.
If none are listed it will become a full resolver itself, and not use
any forwarders.