f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"

80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"

a34684a59b60a4173c25035d0c627ef17e6dc215rpluem [<!ENTITY mdash "&#8212;">]>

5b88c8507d5ef6d0c4cfbc78230294968175b638minfrin

6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<refentry>

6c3b9cebb551140fbb25d58bae08b539b3802133ylavic

6c3b9cebb551140fbb25d58bae08b539b3802133ylavic <refentryinfo>

4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic <date>Jun 30, 2000</date>

4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic </refentryinfo>

0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic

0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic <refmeta>

0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic <refentrytitle>lwres</refentrytitle>

0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic <manvolnum>3</manvolnum>

69301145375a889e7e37caf7cc7321ac0f91801erpluem <refmiscinfo>BIND9</refmiscinfo>

69301145375a889e7e37caf7cc7321ac0f91801erpluem </refmeta>

69301145375a889e7e37caf7cc7321ac0f91801erpluem <refnamediv>

506bfe33206b2fece40ef25f695af39dd4130facjkaluza <refname>lwres</refname>

506bfe33206b2fece40ef25f695af39dd4130facjkaluza <refpurpose>introduction to the lightweight resolver library</refpurpose>

506bfe33206b2fece40ef25f695af39dd4130facjkaluza </refnamediv>

506bfe33206b2fece40ef25f695af39dd4130facjkaluza

d58a848a016d401b965111e50ef829e1641f7834minfrin <docinfo>

d58a848a016d401b965111e50ef829e1641f7834minfrin <copyright>

d58a848a016d401b965111e50ef829e1641f7834minfrin <year>2004</year>

2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf <year>2005</year>

2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf </copyright>

17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic <copyright>

17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic <year>2000</year>

17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic <year>2001</year>

17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic <holder>Internet Software Consortium.</holder>

17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic </copyright>

e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic </docinfo>

e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic

e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic <refsynopsisdiv>

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <funcsynopsis>

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</funcsynopsis>

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic </refsynopsisdiv>

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <refsect1>

330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <title>DESCRIPTION</title>

d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <para>

d7205b1a86c51c27b71a2c458dc453fd53a261c1covener The BIND 9 lightweight resolver library is a simple, name service

d7205b1a86c51c27b71a2c458dc453fd53a261c1covener independent stub resolver library. It provides hostname-to-address

d7205b1a86c51c27b71a2c458dc453fd53a261c1covener and address-to-hostname lookup services to applications by

d7205b1a86c51c27b71a2c458dc453fd53a261c1covener transmitting lookup requests to a resolver daemon

44ff304057225e944e220e981d434a046d14cf06covener <command>lwresd</command>

44ff304057225e944e220e981d434a046d14cf06covener running on the local host. The resover daemon performs the

44ff304057225e944e220e981d434a046d14cf06covener lookup using the DNS or possibly other name service protocols,

44ff304057225e944e220e981d434a046d14cf06covener and returns the results to the application through the library.

5d1ba75b8794925e67591c209085a49279791de9covener The library and resolver daemon communicate using a simple

5d1ba75b8794925e67591c209085a49279791de9covener UDP-based protocol.

5d1ba75b8794925e67591c209085a49279791de9covener </para>

032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand </refsect1>

032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand

032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand <refsect1>

032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand <title>OVERVIEW</title>

caad2986f81ab263f7af41467dd622dc9add17f3ylavic <para>

caad2986f81ab263f7af41467dd622dc9add17f3ylavic The lwresd library implements multiple name service APIs.

caad2986f81ab263f7af41467dd622dc9add17f3ylavic The standard

caad2986f81ab263f7af41467dd622dc9add17f3ylavic <function>gethostbyname()</function>,

45a10d38e6051fd7bdf9d742aaae633d97ff02abjailletc <function>gethostbyaddr()</function>,

f7317ff316c2b141feea31bddb74d5d3fa1584edjorton <function>gethostbyname_r()</function>,

f7317ff316c2b141feea31bddb74d5d3fa1584edjorton <function>gethostbyaddr_r()</function>,

2165214331e4afafca4048f66f303d0253d7b001covener <function>getaddrinfo()</function>,

a34684a59b60a4173c25035d0c627ef17e6dc215rpluem <function>getipnodebyname()</function>,

a34684a59b60a4173c25035d0c627ef17e6dc215rpluem and

1e2d421a36999d292042a5539971070d54aa6c63ylavic <function>getipnodebyaddr()</function>

1e2d421a36999d292042a5539971070d54aa6c63ylavic functions are all supported. To allow the lwres library to coexist

1e2d421a36999d292042a5539971070d54aa6c63ylavic with system libraries that define functions of the same name,

fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh the library defines these functions with names prefixed by

fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh <literal>lwres_</literal>.

fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh To define the standard names, applications must include the

0b67eb8568cd58bb77082703951679b42cf098actrawick header file

0b67eb8568cd58bb77082703951679b42cf098actrawick <filename>&lt;lwres/netdb.h&gt;</filename>

0b67eb8568cd58bb77082703951679b42cf098actrawick which contains macro definitions mapping the standard function names

0b67eb8568cd58bb77082703951679b42cf098actrawick into

5ef3c61605a3a021ff71f488983cb0065f8e1a79covener <literal>lwres_</literal>

fb1985a97912b25ec6564c73e610a31e5fc6e25fcovener prefixed ones. Operating system vendors who integrate the lwres

09c87c777bed1655621bb20e1c46cb6b1a63279dcovener library into their base distributions should rename the functions

6502b7b32f980cc2093bb3ebce37e5e4dc68fba4ylavic in the library proper so that the renaming macros are not needed.

6502b7b32f980cc2093bb3ebce37e5e4dc68fba4ylavic </para>

3060ce7f798fbda7999cd4ddf89b525d2b294185covener <para>

c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic The library also provides a native API consisting of the functions

c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic <function>lwres_getaddrsbyname()</function>

c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic and

e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletc <function>lwres_getnamebyaddr()</function>.

e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletc These may be called by applications that require more detailed

e466c40e1801982602ee0200c9e8b61cc148742djailletc control over the lookup process than the standard functions

e466c40e1801982602ee0200c9e8b61cc148742djailletc provide.

457468b82e59d01eba00dd9d0817309c8f5e414ejim </para>

457468b82e59d01eba00dd9d0817309c8f5e414ejim <para>

457468b82e59d01eba00dd9d0817309c8f5e414ejim In addition to these name service independent address lookup

04983e3bd1754764eec7d6bb772fe3b0bf391771jorton functions, the library implements a new, experimental API

04983e3bd1754764eec7d6bb772fe3b0bf391771jorton for looking up arbitrary DNS resource records, using the

15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem <function>lwres_getaddrsbyname()</function>

15660979a30d251681463de2e0584853890082accovener function.

15660979a30d251681463de2e0584853890082accovener </para>

49dacedb6c387b786b7911082ff35121a45f414bcovener <para>

49dacedb6c387b786b7911082ff35121a45f414bcovener Finally, there is a low-level API for converting lookup

cfd9415521847b2f9394fad04fb701cfb955f503rjung requests and responses to and from raw lwres protocol packets.

cfd9415521847b2f9394fad04fb701cfb955f503rjung This API can be used by clients requiring nonblocking operation,

cfd9415521847b2f9394fad04fb701cfb955f503rjung and is also used when implementing the server side of the lwres

28c31fb73c1264bd1d0ff932573677030b024c7dwrowe protocol, for example in the

28c31fb73c1264bd1d0ff932573677030b024c7dwrowe <command>lwresd</command>

28c31fb73c1264bd1d0ff932573677030b024c7dwrowe resolver daemon. The use of this low-level API in clients

28c31fb73c1264bd1d0ff932573677030b024c7dwrowe and servers is outlined in the following sections.

28c31fb73c1264bd1d0ff932573677030b024c7dwrowe </para>

8491e0600f69b0405e156ea8a419653c065c645bcovener </refsect1>

63b9f1f5880391261705f696d7d65507bbe9ace3covener <refsect1>

63b9f1f5880391261705f696d7d65507bbe9ace3covener <title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>

63b9f1f5880391261705f696d7d65507bbe9ace3covener <para>

49dacedb6c387b786b7911082ff35121a45f414bcovener When a client program wishes to make an lwres request using the

49dacedb6c387b786b7911082ff35121a45f414bcovener native low-level API, it typically performs the following

49dacedb6c387b786b7911082ff35121a45f414bcovener sequence of actions.

49dacedb6c387b786b7911082ff35121a45f414bcovener </para>

3c990331fc6702119e4f5b8ba9eae3021aea5265jim <para>

3c990331fc6702119e4f5b8ba9eae3021aea5265jim (1) Allocate or use an existing <type>lwres_packet_t</type>,

3c990331fc6702119e4f5b8ba9eae3021aea5265jim called <varname>pkt</varname> below.

3c990331fc6702119e4f5b8ba9eae3021aea5265jim </para>

fc42512879dd0504532f52fe5d0d0383dda96a1eniq <para>

fc42512879dd0504532f52fe5d0d0383dda96a1eniq (2) Set <structfield>pkt.recvlength</structfield> to the maximum length

fc42512879dd0504532f52fe5d0d0383dda96a1eniq we will accept.

0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq This is done so the receiver of our packets knows how large our receive

0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq buffer is. The "default" is a constant in

0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq <filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.

da0442c0440caef34706e2c2f3af05cb65921cc0jailletc </para>

983528026996668ea295be95aedb9c7a346af470ylavic <para>

da0442c0440caef34706e2c2f3af05cb65921cc0jailletc (3) Set <structfield>pkt.serial</structfield>

da0442c0440caef34706e2c2f3af05cb65921cc0jailletc to a unique serial number. This value is echoed

06b8f183140c8e02e0974e938a05078b511d1603covener back to the application by the remote server.

06b8f183140c8e02e0974e938a05078b511d1603covener </para>

06b8f183140c8e02e0974e938a05078b511d1603covener <para>

15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem (4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to

259878293a997ff49f5ddfc53d3739cbdc25444ecovener 0.

259878293a997ff49f5ddfc53d3739cbdc25444ecovener </para>

259878293a997ff49f5ddfc53d3739cbdc25444ecovener <para>

259878293a997ff49f5ddfc53d3739cbdc25444ecovener (5) Set <structfield>pkt.result</structfield> to 0.

15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem </para>

b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin <para>

b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin (6) Call <function>lwres_*request_render()</function>,

b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin or marshall in the data using the primitives

65967d05f839dbf27cf91d91fa79585eeae19660minfrin such as <function>lwres_packet_render()</function>

65967d05f839dbf27cf91d91fa79585eeae19660minfrin and storing the packet data.

65967d05f839dbf27cf91d91fa79585eeae19660minfrin </para>

65967d05f839dbf27cf91d91fa79585eeae19660minfrin <para>

8152945ae46857b170cb227e79bb799f4fc7710dminfrin (7) Transmit the resulting buffer.

8152945ae46857b170cb227e79bb799f4fc7710dminfrin </para>

8152945ae46857b170cb227e79bb799f4fc7710dminfrin <para>

8152945ae46857b170cb227e79bb799f4fc7710dminfrin (8) Call <function>lwres_*response_parse()</function>

75f5c2db254c0167a0e396254460de09b775d203trawick to parse any packets received.

75f5c2db254c0167a0e396254460de09b775d203trawick </para>

75f5c2db254c0167a0e396254460de09b775d203trawick <para>

4f0358189bfa57b8e75bd6b94db264302a8f336amrumph (9) Verify that the opcode and serial match a request, and process the

4f0358189bfa57b8e75bd6b94db264302a8f336amrumph packet specific information contained in the body.

4f0358189bfa57b8e75bd6b94db264302a8f336amrumph </para>

5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick </refsect1>

5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick <refsect1>

5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick <title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>

5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick <para>

54d750a84a175d8e338880514d440773eb986b50covener When implementing the server side of the lightweight resolver

54d750a84a175d8e338880514d440773eb986b50covener protocol using the lwres library, a sequence of actions like the

54d750a84a175d8e338880514d440773eb986b50covener following is typically involved in processing each request packet.

54d750a84a175d8e338880514d440773eb986b50covener </para>

54d750a84a175d8e338880514d440773eb986b50covener <para>

54d750a84a175d8e338880514d440773eb986b50covener Note that the same <type>lwres_packet_t</type> is used

54d750a84a175d8e338880514d440773eb986b50covener in both the <function>_parse()</function> and <function>_render()</function> calls,

54d750a84a175d8e338880514d440773eb986b50covener with only a few modifications made

7a3aa12f0eda24793ee26d6a179bd53132e9dae8covener to the packet header's contents between uses. This method is

54d750a84a175d8e338880514d440773eb986b50covener recommended

54d750a84a175d8e338880514d440773eb986b50covener as it keeps the serial, opcode, and other fields correct.

83b50288fa7d306324bba68832011ea08f5c7832covener </para>

4e30ef014533a7e93c92d88306291f5e49c9692ftrawick <para>

83b50288fa7d306324bba68832011ea08f5c7832covener (1) When a packet is received, call <function>lwres_*request_parse()</function> to

5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)

5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.

5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick </para>

2e15620d724fb8e3a5be183b917359a2fd6e9468covener <para>

2e15620d724fb8e3a5be183b917359a2fd6e9468covener (2) Process the request in the data specific type.

2e15620d724fb8e3a5be183b917359a2fd6e9468covener </para>

2e15620d724fb8e3a5be183b917359a2fd6e9468covener <para>

1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener (3) Set the <structfield>pkt.result</structfield>,

1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener <structfield>pkt.recvlength</structfield> as above. All other fields

1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener can

1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener be left untouched since they were filled in by the <function>*_parse()</function> call

b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener above. If using <function>lwres_*response_render()</function>,

b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener <structfield>pkt.pktflags</structfield> will be set up

b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be

f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd set.

f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd </para>

f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd <para>

179565be4043d7e5f9161aa75271fa0a001866d9covener (4) Call the data specific rendering function, such as

179565be4043d7e5f9161aa75271fa0a001866d9covener <function>lwres_gabnresponse_render()</function>.

179565be4043d7e5f9161aa75271fa0a001866d9covener </para>

111436a32ba1254291e4883292fb116d15fe8f64covener <para>

fce4949fb0b309a5744afcd503c6ed2d35621ee2covener (5) Send the resulting packet to the client.

fce4949fb0b309a5744afcd503c6ed2d35621ee2covener </para>

fce4949fb0b309a5744afcd503c6ed2d35621ee2covener <para></para>

fce4949fb0b309a5744afcd503c6ed2d35621ee2covener </refsect1>

7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick <refsect1>

7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick <title>SEE ALSO</title>

7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick <para><citerefentry>

ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>

ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz </citerefentry>,

ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz

273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza <citerefentry>

273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>

273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza </citerefentry>,

efe780dcf13b2b95effabf897d694d8f23feac74trawick

fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin <citerefentry>

fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>

fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin </citerefentry>,

993d1261a278d7322bccef219101220b7b4fb8c5jkaluza

993d1261a278d7322bccef219101220b7b4fb8c5jkaluza <citerefentry>

993d1261a278d7322bccef219101220b7b4fb8c5jkaluza <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>

ba050a6f942b9fa0e81ed73437588005c569655ccovener </citerefentry>,

ba050a6f942b9fa0e81ed73437588005c569655ccovener

ba050a6f942b9fa0e81ed73437588005c569655ccovener <citerefentry>

ba050a6f942b9fa0e81ed73437588005c569655ccovener <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>

135ddda3a989215d2bedbcf1529bfb269c3eda23niq </citerefentry>,

135ddda3a989215d2bedbcf1529bfb269c3eda23niq

135ddda3a989215d2bedbcf1529bfb269c3eda23niq <citerefentry>

001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedooh <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>

001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedooh </citerefentry>,

001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedooh

efe780dcf13b2b95effabf897d694d8f23feac74trawick <citerefentry>

793214f67dede32edfd9ee96c664ead04d175cbbjfclere <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>

cc5a4a08dc9783fcbc52ce86f11e01c281a43810minfrin </citerefentry>,

9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener

9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener <citerefentry>

9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>

249d09d51808cb7981af99762c3b3736ca126cd5jkaluza </citerefentry>,

249d09d51808cb7981af99762c3b3736ca126cd5jkaluza

249d09d51808cb7981af99762c3b3736ca126cd5jkaluza <citerefentry>

249d09d51808cb7981af99762c3b3736ca126cd5jkaluza <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>

56589be3d7a3e9343370df240010c6928cc78b39jkaluza </citerefentry>,

56589be3d7a3e9343370df240010c6928cc78b39jkaluza

56589be3d7a3e9343370df240010c6928cc78b39jkaluza <citerefentry>

77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>

77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc </citerefentry>.

77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc

77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc </para>

f87299dab99bc04b51a6b8cad51b6795db862c0atrawick </refsect1>

f87299dab99bc04b51a6b8cad51b6795db862c0atrawick</refentry><!--

85eacfc96a04547ef25aabbc06440039715084c2jorton