448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerCopyright (C) 2000, 2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerThis Source Code Form is subject to the terms of the Mozilla Public

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerLicense, v. 2.0. If a copy of the MPL was not distributed with this

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerfile, You can obtain one at http://mozilla.org/MPL/2.0/.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller$Id: lwres,v 1.6 2004/03/05 05:04:46 marka Exp $

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerThis document describes the bind v9 lightweight resolver.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerWHY LWRES?

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerCurrently, applications make queries directly to a DNS server. With

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerv4 records (A records) the client can typically do the proper DNS work

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerto get a hostname into an address or vice versa.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerWith ipv6 and A6 recods, however, this becomes harder. Add to that

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerDNAME and CNAME and DNSSEC, and a client is quickly overwhelmed.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerTo keep clients from having to make direct DNS queries for address

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerinformation, an API was developed to allow clients to ask high-level

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerinformation, such as "what addresses does foo.nominum.com have?" and

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller"what name does 1.2.3.4 have?"

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

1233cf61f92cf026493da1465aa5ef6e84f443adBrendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan MmillerGENERAL DESIGN

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

1233cf61f92cf026493da1465aa5ef6e84f443adBrendan MmillerThe lwres library converts structures into wire-format packets for

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmillertransmission, and unmarshalls them on receive.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerMarshalling and unmarshalling:

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerEach structure will have two functions defined, one to take a

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerwire-format packet and convert it into a structure, and another to

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillertake a structure and convert it into a wire-format packet. There

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmilleris a structure cleanup function that will take the unmarshalled

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerstructure and free any dynamically allocated elements.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan MmillerWire formats:

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerAll integer values are in network byte order.

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerAll addresses are in network byte order. That is, they are directly

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillerusable and do not need to be byte swapped, at least for ipv4 and ipv6.

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerAll character strings are prefixed with a length, and are NUL

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmillerterminated C strings. This is a concession for structure handling on

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmillerthe receive side, and allows a mapping structure to point to data

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmillercontained in the actual receive buffer, eliminating copying.

1233cf61f92cf026493da1465aa5ef6e84f443adBrendan Mmiller

1233cf61f92cf026493da1465aa5ef6e84f443adBrendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan MmillerNOOP (aka ping) packet format (request, response):

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller lwres_lwpacket_t header;

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller isc_uint16_t datalength;

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller < datalength bytes >

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan MmillerThe server simply returns the entire data region in the reply. This

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmillerallows the client to determine if the server is operational.

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan MmillerGETADDRSBYNAME (response):

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller lwres_lwpacket_t header;

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller isc_uint16_t naliases;

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller isc_uint16_t naddrs;

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller isc_uint16_t real_name_len;

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller < real_name_len bytes of name >

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller isc_uint8_t \0

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller < naliases of

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller isc_uint16_t len;

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller < len bytes of name >

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller isc_uint8_t \0

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller >

a3f1c4bb696d904f842314da867a84288809db8bBrendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller < naddrs of

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller isc_uint32_t family;

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller isc_uint16_t len;

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller < len bytes of address >

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller >

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan MmillerGETNAMEBYADDR (response):

aaa0f5ddd147facc5c535e28845db1d482c6c6d5Brendan Mmiller

448987059f6c769c5a4986c178356b90e823bb36Brendan Mmiller 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.