lwres.html revision d6fa26d0adaec6c910115be34fe7a5a5f402c14f
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - This Source Code Form is subject to the terms of the Mozilla Public
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - License, v. 2.0. If a copy of the MPL was not distributed with this
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - file, You can obtain one at http://mozilla.org/MPL/2.0/.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
5dbfd19ad5fcc2b779f40f80fa05c1bd28fd0b4eTheo Schlossnagle<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
2d08521bd15501c8370ba2153b9cca4f094979d0Garrett D'Amore<a name="id-1"></a><div class="titlepage"></div>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<p>lwres — introduction to the lightweight resolver library</p>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The BIND 9 lightweight resolver library is a simple, name service
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe independent stub resolver library. It provides hostname-to-address
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and address-to-hostname lookup services to applications by
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe transmitting lookup requests to a resolver daemon
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="command"><strong>lwresd</strong></span>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe running on the local host. The resolver daemon performs the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lookup using the DNS or possibly other name service protocols,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and returns the results to the application through the library.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The library and resolver daemon communicate using a simple
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe UDP-based protocol.
9d12795f87b63c2e39e87bff369182edd34677d3Robert Mustacchi The lwresd library implements multiple name service APIs.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The standard
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">gethostbyname_r()</code>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">gethostbyaddr_r()</code>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">getipnodebyname()</code>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">getipnodebyaddr()</code>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe functions are all supported. To allow the lwres library to coexist
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe with system libraries that define functions of the same name,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe the library defines these functions with names prefixed by
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe To define the standard names, applications must include the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="filename"><lwres/netdb.h></code>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe which contains macro definitions mapping the standard function names
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe prefixed ones. Operating system vendors who integrate the lwres
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe library into their base distributions should rename the functions
89b9271284be1a4e3e3053d7bc12f9bbf8145b06Robert Mustacchi in the library proper so that the renaming macros are not needed.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The library also provides a native API consisting of the functions
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">lwres_getaddrsbyname()</code>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">lwres_getnamebyaddr()</code>.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe These may be called by applications that require more detailed
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe control over the lookup process than the standard functions
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe In addition to these name service independent address lookup
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe functions, the library implements a new, experimental API
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe for looking up arbitrary DNS resource records, using the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">lwres_getaddrsbyname()</code>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Finally, there is a low-level API for converting lookup
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe requests and responses to and from raw lwres protocol packets.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This API can be used by clients requiring nonblocking operation,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and is also used when implementing the server side of the lwres
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe protocol, for example in the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="command"><strong>lwresd</strong></span>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe resolver daemon. The use of this low-level API in clients
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and servers is outlined in the following sections.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<a name="id-1.9"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe When a client program wishes to make an lwres request using the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe native low-level API, it typically performs the following
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe sequence of actions.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (1) Allocate or use an existing <span class="type">lwres_packet_t</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (2) Set <code class="varname">pkt.recvlength</code> to the maximum length
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe we will accept.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This is done so the receiver of our packets knows how large our receive
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe buffer is. The "default" is a constant in
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>.
a5eb7107f06a6e23e8e77e8d3a84c1ff90a73ac6Bryan Cantrill (3) Set <code class="varname">pkt.serial</code>
a5eb7107f06a6e23e8e77e8d3a84c1ff90a73ac6Bryan Cantrill to a unique serial number. This value is echoed
a5eb7107f06a6e23e8e77e8d3a84c1ff90a73ac6Bryan Cantrill back to the application by the remote server.
1767006bb066ef500b90b432fba79d63d0d09b36Bryan Cantrill (4) Set <code class="varname">pkt.pktflags</code>. Usually this is set to
ce83b99835cc4643ab0fefd88dea62427d9ced5eRobert Mustacchi (5) Set <code class="varname">pkt.result</code> to 0.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (6) Call <code class="function">lwres_*request_render()</code>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe or marshall in the data using the primitives
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe such as <code class="function">lwres_packet_render()</code>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and storing the packet data.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (7) Transmit the resulting buffer.
7a5aac98bc37534537d4896efd4efd30627d221eJerry Jelinek (8) Call <code class="function">lwres_*response_parse()</code>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe to parse any packets received.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (9) Verify that the opcode and serial match a request, and process the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe packet specific information contained in the body.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<a name="id-1.10"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe When implementing the server side of the lightweight resolver
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe protocol using the lwres library, a sequence of actions like the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe following is typically involved in processing each request packet.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Note that the same <span class="type">lwres_packet_t</span> is used
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe with only a few modifications made
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe to the packet header's contents between uses. This method is
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe as it keeps the serial, opcode, and other fields correct.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below)
9d12795f87b63c2e39e87bff369182edd34677d3Robert Mustacchi as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (2) Process the request in the data specific type.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (3) Set the <code class="varname">pkt.result</code>,
296749875bd503e7a14e25b4c57d3142cb496df1Joshua M. Clulow <code class="varname">pkt.recvlength</code> as above. All other fields
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe be left untouched since they were filled in by the <code class="function">*_parse()</code> call
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe above. If using <code class="function">lwres_*response_render()</code>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="varname">pkt.pktflags</code> will be set up
d2b9ba291ef0d1dc8807b6d46996674c723924d0Robert Mustacchi properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (4) Call the data specific rendering function, such as
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <code class="function">lwres_gabnresponse_render()</code>.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe (5) Send the resulting packet to the client.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>.