0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
83a28ca274521e15086fc39febde507bcc4e145eMark Andrews<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>introduction to the lightweight resolver library</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
4b01d45a49f1c2cc4bddc9a1b4c78232867de134Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The BIND 9 lightweight resolver library is a simple, name service
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein independent stub resolver library. It provides hostname-to-address
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and address-to-hostname lookup services to applications by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein transmitting lookup requests to a resolver daemon
821350367e2c7313c02eb275e8e05d5193b47cfdJeremy C. Reed running on the local host. The resolver daemon performs the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lookup using the DNS or possibly other name service protocols,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and returns the results to the application through the library.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The library and resolver daemon communicate using a simple
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein UDP-based protocol.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The lwresd library implements multiple name service APIs.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The standard
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein functions are all supported. To allow the lwres library to coexist
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein with system libraries that define functions of the same name,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the library defines these functions with names prefixed by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein To define the standard names, applications must include the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein which contains macro definitions mapping the standard function names
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein prefixed ones. Operating system vendors who integrate the lwres
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein library into their base distributions should rename the functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in the library proper so that the renaming macros are not needed.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The library also provides a native API consisting of the functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These may be called by applications that require more detailed
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein control over the lookup process than the standard functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein In addition to these name service independent address lookup
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein functions, the library implements a new, experimental API
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein for looking up arbitrary DNS resource records, using the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Finally, there is a low-level API for converting lookup
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein requests and responses to and from raw lwres protocol packets.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This API can be used by clients requiring nonblocking operation,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and is also used when implementing the server side of the lwres
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein protocol, for example in the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein resolver daemon. The use of this low-level API in clients
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and servers is outlined in the following sections.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein When a client program wishes to make an lwres request using the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein native low-level API, it typically performs the following
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein sequence of actions.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (1) Allocate or use an existing <type>lwres_packet_t</type>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt (2) Set <varname remap="structfield">pkt.recvlength</varname> to the maximum length
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein we will accept.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is done so the receiver of our packets knows how large our receive
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein buffer is. The "default" is a constant in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt (3) Set <varname remap="structfield">pkt.serial</varname>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to a unique serial number. This value is echoed
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein back to the application by the remote server.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt (4) Set <varname remap="structfield">pkt.pktflags</varname>. Usually this is set to
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt (5) Set <varname remap="structfield">pkt.result</varname> to 0.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (6) Call <function>lwres_*request_render()</function>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein or marshall in the data using the primitives
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein such as <function>lwres_packet_render()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and storing the packet data.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (7) Transmit the resulting buffer.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (8) Call <function>lwres_*response_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to parse any packets received.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (9) Verify that the opcode and serial match a request, and process the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein packet specific information contained in the body.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein When implementing the server side of the lightweight resolver
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein protocol using the lwres library, a sequence of actions like the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein following is typically involved in processing each request packet.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Note that the same <type>lwres_packet_t</type> is used
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in both the <function>_parse()</function> and <function>_render()</function> calls,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein with only a few modifications made
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to the packet header's contents between uses. This method is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein as it keeps the serial, opcode, and other fields correct.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (1) When a packet is received, call <function>lwres_*request_parse()</function> to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (2) Process the request in the data specific type.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt (3) Set the <varname remap="structfield">pkt.result</varname>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <varname remap="structfield">pkt.recvlength</varname> as above. All other fields
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein be left untouched since they were filled in by the <function>*_parse()</function> call
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein above. If using <function>lwres_*response_render()</function>,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <varname remap="structfield">pkt.pktflags</varname> will be set up
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (4) Call the data specific rendering function, such as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gabnresponse_render()</function>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (5) Send the resulting packet to the client.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>