278N/ACopyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")

278N/ACopyright (C) 2000, 2001 Internet Software Consortium.

278N/ASee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

278N/A

278N/A$Id: lwres,v 1.6 2004/03/05 05:04:46 marka Exp $

278N/A

278N/AThis document describes the bind v9 lightweight resolver.

278N/A

278N/AWHY LWRES?

278N/A

278N/ACurrently, applications make queries directly to a DNS server. With

278N/Av4 records (A records) the client can typically do the proper DNS work

278N/Ato get a hostname into an address or vice versa.

278N/A

278N/AWith ipv6 and A6 recods, however, this becomes harder. Add to that

278N/ADNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.

278N/A

278N/ATo keep clients from having to make direct DNS queries for address

278N/Ainformation, an API was developed to allow clients to ask high-level

278N/Ainformation, such as "what addresses does foo.nominum.com have?" and

278N/A"what name does 1.2.3.4 have?"

278N/A

278N/A

278N/A

278N/AGENERAL DESIGN

278N/A

278N/AThe lwres library converts structures into wire-format packets for

278N/Atransmission, and unmarshalls them on receive.

278N/A

278N/A

278N/A

278N/AMarshalling and unmarshalling:

278N/A

278N/AEach structure will have two functions defined, one to take a

278N/Awire-format packet and convert it into a structure, and another to

278N/Atake a structure and convert it into a wire-format packet. There

278N/Ais a structure cleanup function that will take the unmarshalled

278N/Astructure and free any dynamically allocated elements.

278N/A

278N/A

278N/AWire formats:

278N/A

278N/AAll integer values are in network byte order.

278N/A

278N/AAll addresses are in network byte order. That is, they are directly

278N/Ausable and do not need to be byte swapped, at least for ipv4 and ipv6.

278N/A

278N/AAll character strings are prefixed with a length, and are NUL

278N/Aterminated C strings. This is a concession for structure handling on

278N/Athe receive side, and allows a mapping structure to point to data

278N/Acontained in the actual receive buffer, eliminating copying.

278N/A

278N/A

278N/ANOOP (aka ping) packet format (request, response):

278N/A

278N/A lwres_lwpacket_t header;

278N/A isc_uint16_t datalength;

278N/A < datalength bytes >

278N/A

278N/AThe 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.