lwres.docbook revision dafcb997e390efa4423883dafd100c975c4095d6
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2001 Internet Software Consortium.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<!-- $Id: lwres.docbook,v 1.4 2004/03/05 05:12:55 marka Exp $ -->
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</refentryinfo>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refpurpose>introduction to the lightweight resolver library</refpurpose>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refsynopsisdiv>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</funcsynopsis>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</refsynopsisdiv>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThe BIND 9 lightweight resolver library is a simple, name service
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonindependent stub resolver library. It provides hostname-to-address
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonand address-to-hostname lookup services to applications by
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssontransmitting lookup requests to a resolver daemon
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonrunning on the local host. The resover daemon performs the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonlookup using the DNS or possibly other name service protocols,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonand returns the results to the application through the library.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThe library and resolver daemon communicate using a simple
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonUDP-based protocol.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThe lwresd library implements multiple name service APIs.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonfunctions are all supported. To allow the lwres library to coexist
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonwith system libraries that define functions of the same name,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonthe library defines these functions with names prefixed by
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonTo define the standard names, applications must include the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<filename><lwres/netdb.h></filename>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonwhich contains macro definitions mapping the standard function names
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonprefixed ones. Operating system vendors who integrate the lwres
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonlibrary into their base distributions should rename the functions
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonin the library proper so that the renaming macros are not needed.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThe library also provides a native API consisting of the functions
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<function>lwres_getnamebyaddr()</function>.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThese may be called by applications that require more detailed
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssoncontrol over the lookup process than the standard functions
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonIn addition to these name service independent address lookup
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonfunctions, the library implements a new, experimental API
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonfor looking up arbitrary DNS resource records, using the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonFinally, there is a low-level API for converting lookup
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonrequests and responses to and from raw lwres protocol packets.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThis API can be used by clients requiring nonblocking operation,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonand is also used when implementing the server side of the lwres
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonprotocol, for example in the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonresolver daemon. The use of this low-level API in clients
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonand servers is outlined in the following sections.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonWhen a client program wishes to make an lwres request using the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonnative low-level API, it typically performs the following
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonsequence of actions.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(1) Allocate or use an existing <type>lwres_packet_t</type>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonThis is done so the receiver of our packets knows how large our receive
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonbuffer is. The "default" is a constant in
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(3) Set <structfield>pkt.serial</structfield>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonto a unique serial number. This value is echoed
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonback to the application by the remote server.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(5) Set <structfield>pkt.result</structfield> to 0.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(6) Call <function>lwres_*request_render()</function>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonor marshall in the data using the primitives
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonsuch as <function>lwres_packet_render()</function>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonand storing the packet data.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(7) Transmit the resulting buffer.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(8) Call <function>lwres_*response_parse()</function>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonto parse any packets received.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(9) Verify that the opcode and serial match a request, and process the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonpacket specific information contained in the body.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonWhen implementing the server side of the lightweight resolver
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonprotocol using the lwres library, a sequence of actions like the
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonfollowing is typically involved in processing each request packet.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas GustafssonNote that the same <type>lwres_packet_t</type> is used
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonin both the <function>_parse()</function> and <function>_render()</function> calls,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonwith only a few modifications made
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonto the packet header's contents between uses. This method is recommended
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonas it keeps the serial, opcode, and other fields correct.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(1) When a packet is received, call <function>lwres_*request_parse()</function> to
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonunmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonas well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(2) Process the request in the data specific type.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(3) Set the <structfield>pkt.result</structfield>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<structfield>pkt.recvlength</structfield> as above. All other fields can
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonbe left untouched since they were filled in by the <function>*_parse()</function> call
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonabove. If using <function>lwres_*response_render()</function>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<structfield>pkt.pktflags</structfield> will be set up
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafssonproperly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(4) Call the data specific rendering function, such as
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<function>lwres_gabnresponse_render()</function>.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson(5) Send the resulting packet to the client.
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>,
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</citerefentry>.