Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$Id: lwres.3,v 1.2 2000/07/27 09:44:02 tale Exp $
.Dd Jun 30, 2000 .Dt LWRES 3 .Os BIND9 9 .Sh NAME .Nm lwres .Nd introduction to the lightweight resolver .Sh SYNOPSIS .Fd #include <lwres/lwres.h> .Sh DESCRIPTION The lightweight resolver provides a simple way for clients to perform forward and reverse lookups. Instead of looking up the names or addresses directly, clients can send requests to the lightweight resolver daemon .Nm lwresd which does hard work of performing the lookups for them. Clients can just use the lightweight resolver library to format a request to get a hostname for an IP address or vice versa, send it to .Nm lwresd and wait for a response.
p The lightweight resolver in BIND 9 consists of three components: a client, a server and a protocol. Clients use the functions provided by the lightweight resolver library to encode requests and decode responses. The server for the lightweight resolver is .Nm lwresd . In reality this is implemented by the name server, .Nm named , though when operating as the lightweight resolver server, .Nm lwresd is functionally and logically distinct from the actual name server. The protocol consists of a number of opcodes, each of which has a request and response structure associated with it. The lightweight resolver library contains functions to convert these structures to and from the canonical format whenver they are sent to .Nm lwresd . .Sh RATIONALE
p Conventional DNS lookups of hostnames and IPv4 addresses are usually simple and straightforward. A client can issue queries to map a hostname to an IPv4 address or from an IPv4 address to a hostname. Many DNS queries can be needed to lookup IPv6 addresses. It may be necessary to resolve potentially variable-length partial IPv6 addresses: aggregation and site-level identifiers for instance. Keeping track of all of these queries and assembling the answers to return the hostname or IPv6 address is very hard work and error-prone. Further complexity can be caused by DNAME chains. If the answers are signed using DNSSEC, additional queries may be needed to verify the signatures. The consequence of this is that clients can be overwhelmed with the amount of work needed to resolve IPv6 addresses. BIND9 provides a lightweight resolver to eliminate these problems if applications had to resolve IPv6 addresses for themselves.
p Instead of looking up the hostnames or IPv6 addresses directly, clients can use the lightweight resolver to get the name server to do the work. Clients construct simple questions like \*qwhat is the hostname for the following address?\*q or \*qwhat are the addresses of hostname .Dv host.example.com?\*q The lightweight resolver functions take these questions and format them into queries which are sent to .Nm lwresd . Replies from the lightweight resolver server are then decoded to return an answer to the client which made the original request. .Sh CANONICAL FORMAT
p The lightweight resolver's canonical data format has been arranged for efficiency. All integer values are in network byte order. Addresses are also in network byte order. This means that, at least for IPv4 and IPv6 addresses, they can be used directly in network system calls without needing to be byte swapped. Character strings get prefixed by a length and are always terminated with a .Dv NUL character. This simplifies structure handling and parsing for both the server receiving a request and the client receiving a reply. It also eliminates data copying by enabling a mapping structure to directly point at data in the actual receive buffer. .Sh OPCODES
p Every lightweight resolver operation uses a unique opcode. Each opcode is assigned a number. Opcodes in the range 0x00000000 and 0x03ffffff are reserved for use by the lightweight resolver library. Opcodes between 0x04000000 and 0xffffffff have been set aside for use by applications.
p Three opcodes are currently defined: l -tag -width LWRES_OPCODE_GETADDRSBYNAME t Li LWRES_OPCODE_NOOP The no-op opcode is essentially an echo operation, comparable to .Xr ping 1 . The server simply returns the entire data region that had been sent by the client. Therefore clients can use this opcode to determine if the server is operational or not. It can also be used by clients to check the version number and any parameters of the lightweight resolver protocol that are supported by the server. t Li LWRES_OPCODE_GETADDRSBYNAME This opcode is used to get all the known addresses for a hostname. In principle, this could also return information from NIS/YP or
a /etc/hosts ,
though this is not implemented yet.
Flags can be set in the request structure that is used for this opcode
to indicate whether IPv4 or IPv6 addresses or both should be returned.
t Li LWRES_OPCODE_GETNAMEBYADDR This provides the complementary operation to
.Dv LWRES_OPCODE_GETADDRSBYNAME .
It returns the hostname for the address that was supplied in the
request structure.
.El
XXXJR
We don't need this section, at least not yet. 23/6/00
.Sh OPCODE REPLIES
.Pp
Replies to lightweight resolver operations contain return codes.
Results between 0x04000000 and 0xffffffff are application defined.
The lightweight resolver library reserves result codes between
0x00000000 and 0x03ffffff.
These occupy the same reserved range used for ISC return values that
are defined in
.Pa isc/resultclass.h .
This means that, if appropriate, it would be trivial to map those ISC
return values to lightweight resolver packet result codes.
.Sh STRUCTURE AND PACKET ENCODING/DECODING
Each opcode has two structures: one for the request and one for the
response.
Clients use the lightweight resolver functions to construct the
request structure and send it to the name server.
The name server decodes the request, carries out the operation and
fills in an opcode-specific response structure which is returned to
the client.
p For every opcode, three functions operate on these structures. A .Ar render function converts the structure to canonical form and a .Ar parse function translates from the canonical form to the op-code specific structure. Memory allocated to the opcode's request or reply structures is discarded using the .Ar free function. Clients will typically use the op-code specific .Ar xxx_request_render , .Ar xxx_response_parse and .Ar xxx_response_free functions. The name server will use the .Ar xxx_request_parse , .Ar xxx_response_render and .Ar xxx_request_free functions.
p
For example, the no-op opcode -
.Dv LWRES_OPCODE_NOOP
- uses
.Dv lwres_nooprequest_t
and
.Dv lwres_noopresponse_t
structures for the requests and responses used in the no-op operation.
.Fn lwres_nooprequest_render
takes a
.Dv lwres_nooprequest_t
structure and converts into a packet in lightweight resolver canonical
format.
Similarly
.Fn lwres_noopresponse_render
converts a
.Dv lwres_noopresponse_t
structure into a packet in lightweight resolver canonical format.
.Fn lwres_nooprequest_parse
takes a packet in canonical format and fills in a corresponding
.Dv lwres_nooprequest_t
structure.
A
.Dv lwres_noopresponse_t
structure is set up by\p
passing a response packet in canonical format to
.Fn lwres_noopresponse_render .
.Fn lwres_nooprequest_free
and
.Fn lwres_noopresponse_free
releases the memory allocated to the
.Dv lwres_nooprequest_t
and
.Dv lwres_noopresponse_t
structures respectively.
XXXJR
NOT YET.
This is just a placeholder to indicate where the section on the
lwres security API should be documented once this is implemented.
There's no point in documenting vapourware, especially if the
API is likely to change between now and then. 23/6/00
.Sh SECURITY
The lightweight resolver provides hooks for requesting the use of
DNSSEC for authenticating requests and responses.
This interface is not currently implemented and is likely to
change.
It is mentioned here to indicate the capabilities that can be expected
in future releases of the lightweight resolver.
.Pp
The following flag bits have been allocated.
.Bl -tag -width LWRES_FLAG_TRUSTNOTREQUIRED
.It Li LWRES_FLAG_TRUSTDEFAULT
Let the server decide whether to use DNSSEC or not.
.It Li LWRES_FLAG_TRUSTNOTREQUIRED
DNSSEC authentication of the DNS queries and replies is not required
.It Li LWRES_FLAG_TRUSTREQUIRED
Any DNSSEC data found when resolving the query must validate and the
server must be DNSSEC-aware.
.It Li LWRES_FLAG_TRUSTRESERVED
Reserved for future use.
.El
.Sh CLIENT SETUP
Every client that uses the lightweight resolver needs to create and
maintain its own state.
Library calls are provided to manage that data structure, a resolver
context.
If the client uses threads, it either has to provide its own locking
primitives on that context structure or else create a context for each
thread.
See
.Xr lwres_context 3 .
Once the context has been created,
.Fn lwres_conf_init
is called to read
a /etc/resolv.conf so that various options such as sort lists, search lists and so on can be applied. .Sh CLIENT INTERFACE The simplest interface to the lightweight resolver is provided by .Fn lwres_getaddrsbyname and .Fn lwres_getnamebyaddr . These functions are blocking calls. A client will wait after sending a request until either a response is returned or else a timeout interval occurs. If non-blocking operations are required, the client will need to call the opcode-specific .Ar request_render and .Ar response_parse directly. .Sh SERVER INTERFACE Service for the lightweight resolver is provided by the lightweight resolver daemon, .Nm lwresd . It listens on port number 921 of the loopback interface and expects to receive packets in the lightweight resolver's canonical format described above. .Sh SEE ALSO .Xr lwres_noop 3 , .Xr lwres_gabn 3 , .Xr lwres_gnba 3 , .Xr lwres_context 3 , .Xr lwres_config 3 , .Xr resolver 5 , .Xr lwres_getipnode 3 .Xr lwresd 8 , .Xr named 8 .