lwres.html revision ddccd5811feff696ba460dabfb666ce61040f545
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Copyright (C) 2000, 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCONTENT="Modular DocBook HTML Stylesheet Version 1.61
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBGCOLOR="#FFFFFF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonVLINK="#840084"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonALINK="#0000FF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFNAMEDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres -- introduction to the lightweight resolver library</DIV
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSYNOPSISDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSIS"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSISINFO"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>DESCRIPTION</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The BIND 9 lightweight resolver library is a simple, name service
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonindependent stub resolver library. It provides hostname-to-address
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand address-to-hostname lookup services to applications by
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontransmitting lookup requests to a resolver daemon
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="COMMAND"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonrunning on the local host. The resover daemon performs the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlookup using the DNS or possibly other name service protocols,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand returns the results to the application through the library.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe library and resolver daemon communicate using a simple
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonUDP-based protocol.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The lwresd library implements multiple name service APIs.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>gethostbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>gethostbyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>gethostbyname_r()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>gethostbyaddr_r()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>getaddrinfo()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>getipnodebyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>getipnodebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfunctions are all supported. To allow the lwres library to coexist
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwith system libraries that define functions of the same name,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthe library defines these functions with names prefixed by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="LITERAL"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonTo define the standard names, applications must include the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FILENAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich contains macro definitions mapping the standard function names
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="LITERAL"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprefixed ones. Operating system vendors who integrate the lwres
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlibrary into their base distributions should rename the functions
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin the library proper so that the renaming macros are not needed.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The library also provides a native API consisting of the functions
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese may be called by applications that require more detailed
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncontrol over the lookup process than the standard functions
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>In addition to these name service independent address lookup
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfunctions, the library implements a new, experimental API
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor looking up arbitrary DNS resource records, using the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Finally, there is a low-level API for converting lookup
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonrequests and responses to and from raw lwres protocol packets.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis API can be used by clients requiring nonblocking operation,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand is also used when implementing the server side of the lwres
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprotocol, for example in the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="COMMAND"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonresolver daemon. The use of this low-level API in clients
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand servers is outlined in the following sections.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>When a client program wishes to make an lwres request using the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonnative low-level API, it typically performs the following
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonsequence of actions.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(1) Allocate or use an existing <SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARNAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson> to the maximum length we will accept.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis is done so the receiver of our packets knows how large our receive
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbuffer is. The "default" is a constant in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FILENAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_RECVLENGTH = 4096</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto a unique serial number. This value is echoed
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonback to the application by the remote server.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>. Usually this is set to 0.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_*request_render()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonor marshall in the data using the primitives
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet_render()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand storing the packet data.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(7) Transmit the resulting buffer.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_*response_parse()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto parse any packets received.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(9) Verify that the opcode and serial match a request, and process the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonpacket specific information contained in the body.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>When implementing the server side of the lightweight resolver
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprotocol using the lwres library, a sequence of actions like the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing is typically involved in processing each request packet.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Note that the same <SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin both the <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwith only a few modifications made
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the packet header's contents between uses. This method is recommended
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonas it keeps the serial, opcode, and other fields correct.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(1) When a packet is received, call <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_*request_parse()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonunmarshall it. This returns a <SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson> (also called <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARNAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonas well as a data specific type, such as <SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gabnrequest_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(2) Process the request in the data specific type.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(3) Set the <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson> as above. All other fields can
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbe left untouched since they were filled in by the <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonabove. If using <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_*response_render()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="STRUCTFIELD"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson> will be set up
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonproperly. Otherwise, the <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_LWPACKETFLAG_RESPONSE</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson> bit should be
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(4) Call the data specific rendering function, such as
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gabnresponse_render()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(5) Send the resulting packet to the client.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gethostent</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnode</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnameinfo</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_noop</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gabn</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gnba</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_config</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>resolver</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"