update

doc/design/lwres

@@ -1,11 +1,30 @@
-$Id: lwres,v 1.1 2000/02/29 20:10:49 explorer Exp $
+$Id: lwres,v 1.2 2000/03/23 23:51:53 explorer Exp $
 
-General design:
+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
@@ -28,7 +47,7 @@ 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:
+NOOP (aka ping) packet format (request, response):
 
 	lwres_lwpacket_t header;
 	isc_uint16_t datalength;
@@ -38,7 +57,7 @@ The server simply returns the entire data region in the reply.  This
 allows the client to determine if the server is operational.
 
 
-GETADDRSBYNAME:
+GETADDRSBYNAME (response):
 
 	lwres_lwpacket_t header;
 
@@ -63,7 +82,7 @@ GETADDRSBYNAME:
 	>
 
 
-GETNAMEBYADDR:
+GETNAMEBYADDR (response):
 
 	lwres_lwpacket_t header;
 
@@ -78,3 +97,66 @@ GETNAMEBYADDR:
 		< 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.