Copyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")

This Source Code Form is subject to the terms of the Mozilla Public

License, v. 2.0. If a copy of the MPL was not distributed with this

file, You can obtain one at http://mozilla.org/MPL/2.0/.

$Id: lwres,v 1.6 2004/03/05 05:04:46 marka 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.