5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCopyright (C) 2000, 2001 Internet Software Consortium.

1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

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

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThis document describes the bind v9 lightweight resolver.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsWHY LWRES?

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCurrently, applications make queries directly to a DNS server. With

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsv4 records (A records) the client can typically do the proper DNS work

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsto get a hostname into an address or vice versa.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsWith ipv6 and A6 recods, however, this becomes harder. Add to that

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsDNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

1fdd2470b625a58b57d0b155e6caf8c4fc0afe8aAutomatic UpdaterTo keep clients from having to make direct DNS queries for address

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsinformation, an API was developed to allow clients to ask high-level

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsinformation, such as "what addresses does foo.nominum.com have?" and

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews"what name does 1.2.3.4 have?"

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsGENERAL DESIGN

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThe lwres library converts structures into wire-format packets for

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewstransmission, and unmarshalls them on receive.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsMarshalling and unmarshalling:

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsEach structure will have two functions defined, one to take a

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewswire-format packet and convert it into a structure, and another to

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewstake a structure and convert it into a wire-format packet. There

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsis a structure cleanup function that will take the unmarshalled

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsstructure and free any dynamically allocated elements.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsWire formats:

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsAll integer values are in network byte order.

cedb0bd0c1e3c461b7e479a16d3adfd5b150f1f4Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsAll addresses are in network byte order. That is, they are directly

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsusable and do not need to be byte swapped, at least for ipv4 and ipv6.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsAll character strings are prefixed with a length, and are NUL

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsterminated C strings. This is a concession for structure handling on

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsthe receive side, and allows a mapping structure to point to data

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewscontained in the actual receive buffer, eliminating copying.

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsNOOP (aka ping) packet format (request, response):

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews lwres_lwpacket_t header;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t datalength;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < datalength bytes >

922312472e2e05ebc64993d465999c5351b83036Automatic Updater

922312472e2e05ebc64993d465999c5351b83036Automatic UpdaterThe server simply returns the entire data region in the reply. This

922312472e2e05ebc64993d465999c5351b83036Automatic Updaterallows the client to determine if the server is operational.

2a31bd531072824ef252c18303859d6af7451b00Francis Dupont

2a31bd531072824ef252c18303859d6af7451b00Francis Dupont

2a31bd531072824ef252c18303859d6af7451b00Francis DupontGETADDRSBYNAME (response):

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews lwres_lwpacket_t header;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews isc_uint16_t naliases;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t naddrs;

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t real_name_len;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < real_name_len bytes of name >

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews isc_uint8_t \0

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < naliases of

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews isc_uint16_t len;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < len bytes of name >

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint8_t \0

0c6ada0a814f3c5417daa1654129bc2af56ed504Automatic Updater >

0c6ada0a814f3c5417daa1654129bc2af56ed504Automatic Updater

0c6ada0a814f3c5417daa1654129bc2af56ed504Automatic Updater < naddrs of

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews isc_uint32_t family;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t len;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < len bytes of address >

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews >

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

71c66a876ecca77923638d3f94cc0783152b2f03Mark AndrewsGETNAMEBYADDR (response):

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews lwres_lwpacket_t header;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t naliases;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t real_name_len;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < real_name_len bytes of name >

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint8_t \0

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < naliases of

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint16_t len;

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews < len bytes of name >

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews isc_uint8_t \0

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews >

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsFUNCTIONS PROVIDED

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThe lwres library provides three functions per data item. One takes a

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsstructure and marshalls it into a buffer. Another unmarshalls that

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsdata into a structure. A third frees memory used to unmarshall the

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsdata.

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.