lwres.docbook revision 5cd4555ad444fd391002ae32450572054369fd42
e93624301705e3dc68992e3b488a764389eb8b98trawick<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
e93624301705e3dc68992e3b488a764389eb8b98trawick "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
0007bb1e01dd762bde7280beb57113309c1715a3trawick [<!ENTITY mdash "—">]>
0007bb1e01dd762bde7280beb57113309c1715a3trawick - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
0007bb1e01dd762bde7280beb57113309c1715a3trawick - Copyright (C) 2000, 2001 Internet Software Consortium.
a1be7357e2c08b9dfe52c277063d212d65b15feejim - Permission to use, copy, modify, and distribute this software for any
a1be7357e2c08b9dfe52c277063d212d65b15feejim - purpose with or without fee is hereby granted, provided that the above
a1be7357e2c08b9dfe52c277063d212d65b15feejim - copyright notice and this permission notice appear in all copies.
6682df9b639663c50f447e5690dd62cce7b1c086trawick - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
6682df9b639663c50f447e5690dd62cce7b1c086trawick - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
6682df9b639663c50f447e5690dd62cce7b1c086trawick - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
51c0f0fe0a49a180389009442a83f74b1916f96atrawick - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
51c0f0fe0a49a180389009442a83f74b1916f96atrawick - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
51c0f0fe0a49a180389009442a83f74b1916f96atrawick - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
51c0f0fe0a49a180389009442a83f74b1916f96atrawick - PERFORMANCE OF THIS SOFTWARE.
7e8bc9ca9d1e752f6ca6debec6be8addae8bd72etrawick<!-- $Id: lwres.docbook,v 1.8 2007/01/29 22:16:02 sra Exp $ -->
ecb511c254d5affe7cc018482d53c19aaf145878jerenkrantz <refentryinfo>
ecb511c254d5affe7cc018482d53c19aaf145878jerenkrantz </refentryinfo>
4da4d1ae427ee8827c2325dd121ac05a83afd579wrowe <refnamediv>
d56d6753a75f5b915120c797aedbfcf13bb14c8brbb <refpurpose>introduction to the lightweight resolver library</refpurpose>
d56d6753a75f5b915120c797aedbfcf13bb14c8brbb </refnamediv>
d56d6753a75f5b915120c797aedbfcf13bb14c8brbb <copyright>
4aaf7088758ca56823e585969320f2405a7cc5fcdougm <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
e0596968fe84a2bdaebe0192d8d64d2e9856d4d6brianp </copyright>
e0596968fe84a2bdaebe0192d8d64d2e9856d4d6brianp <copyright>
f33c2c86b419be97248c5289b71738b5f0c7ab0adirkx </copyright>
c5fdaba2e790a0a351d796b5fe3dcfb585be1ba2jim </docinfo>
c5fdaba2e790a0a351d796b5fe3dcfb585be1ba2jim <refsynopsisdiv>
c5fdaba2e790a0a351d796b5fe3dcfb585be1ba2jim <funcsynopsis>
c5fdaba2e790a0a351d796b5fe3dcfb585be1ba2jim<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
2fc50921b88defeb7127985dfe4b4130175e069ejwoolley</funcsynopsis>
2fc50921b88defeb7127985dfe4b4130175e069ejwoolley </refsynopsisdiv>
47638f4a67ce38e5a83e7a303d6f2d5c9ff47b4ebrianp The BIND 9 lightweight resolver library is a simple, name service
47638f4a67ce38e5a83e7a303d6f2d5c9ff47b4ebrianp independent stub resolver library. It provides hostname-to-address
82630c4a04be47f39298d3284b2c596244fb509bbrianp and address-to-hostname lookup services to applications by
82630c4a04be47f39298d3284b2c596244fb509bbrianp transmitting lookup requests to a resolver daemon
35d682920b0b7073bb9ff8c8794f0f73e3ee1a47slive running on the local host. The resover daemon performs the
35d682920b0b7073bb9ff8c8794f0f73e3ee1a47slive lookup using the DNS or possibly other name service protocols,
a2d4f1da4e19836b2d6a673f80f33381a926a8bddougm and returns the results to the application through the library.
a2d4f1da4e19836b2d6a673f80f33381a926a8bddougm The library and resolver daemon communicate using a simple
a2d4f1da4e19836b2d6a673f80f33381a926a8bddougm UDP-based protocol.
30b4a330a5f651eb5198fa93dbb9f3d3594564c9stoddard </refsect1>
983988ac7b8faaf037f4df0ab29729cd047a3ffdtrawick The lwresd library implements multiple name service APIs.
983988ac7b8faaf037f4df0ab29729cd047a3ffdtrawick The standard
797d596a95d4f9900e83ec18295b4ca4951bf763jerenkrantz functions are all supported. To allow the lwres library to coexist
797d596a95d4f9900e83ec18295b4ca4951bf763jerenkrantz with system libraries that define functions of the same name,
797d596a95d4f9900e83ec18295b4ca4951bf763jerenkrantz the library defines these functions with names prefixed by
5842e6b336b1cc0252b6cc2944dd81c7d3a19a1bbrianp To define the standard names, applications must include the
2532433e80d73506f7bcc18bd0dab686f1c39397minfrin header file
2532433e80d73506f7bcc18bd0dab686f1c39397minfrin which contains macro definitions mapping the standard function names
c148bc6b4eea544af816783400362f741c5f5fc2trawick prefixed ones. Operating system vendors who integrate the lwres
c148bc6b4eea544af816783400362f741c5f5fc2trawick library into their base distributions should rename the functions
9d432e23f6025b78322cbee43e8e89262a108e5eaaron in the library proper so that the renaming macros are not needed.
9d432e23f6025b78322cbee43e8e89262a108e5eaaron The library also provides a native API consisting of the functions
6a5bdbbacf4a62adecde52b8f23ebcc4fa2a08b8trawick These may be called by applications that require more detailed
6a5bdbbacf4a62adecde52b8f23ebcc4fa2a08b8trawick control over the lookup process than the standard functions
10306ac2c175f420e6989568f4c8535a5dbc1349minfrin In addition to these name service independent address lookup
10306ac2c175f420e6989568f4c8535a5dbc1349minfrin functions, the library implements a new, experimental API
b4e4d76bf454e1b603b410110356dbcf12f3bc42jim for looking up arbitrary DNS resource records, using the
adb1e17ae7e1cf5cf4f8f2b07d3389cb55f4becetrawick Finally, there is a low-level API for converting lookup
71f891073f6fa0209870791f64cbbf28d77ffdc1brianp requests and responses to and from raw lwres protocol packets.
71f891073f6fa0209870791f64cbbf28d77ffdc1brianp This API can be used by clients requiring nonblocking operation,
2864362ca8266097928e84f101010bdf814ffa08stoddard and is also used when implementing the server side of the lwres
2864362ca8266097928e84f101010bdf814ffa08stoddard protocol, for example in the
2864362ca8266097928e84f101010bdf814ffa08stoddard resolver daemon. The use of this low-level API in clients
2864362ca8266097928e84f101010bdf814ffa08stoddard and servers is outlined in the following sections.
893c106ae59d8e96d921524b123ae26dea8ad37fgstein </refsect1>
3aa6444bcee4e9fc32ec8860d832ff83a15784efianh When a client program wishes to make an lwres request using the
3aa6444bcee4e9fc32ec8860d832ff83a15784efianh native low-level API, it typically performs the following
e2bdfd25d9d0461e0a3ab18ceff2113215e3e115brianp sequence of actions.
b9fe73991e7c592a634242a7e11f924689f58e1fgstein (1) Allocate or use an existing <type>lwres_packet_t</type>,
d9fcdb415d8661cbd9451df8f88e003a1aa04ce9trawick (2) Set <structfield>pkt.recvlength</structfield> to the maximum length
d9fcdb415d8661cbd9451df8f88e003a1aa04ce9trawick we will accept.
d9fcdb415d8661cbd9451df8f88e003a1aa04ce9trawick This is done so the receiver of our packets knows how large our receive
d9fcdb415d8661cbd9451df8f88e003a1aa04ce9trawick buffer is. The "default" is a constant in
d9fcdb415d8661cbd9451df8f88e003a1aa04ce9trawick <filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
b5033962c73a470b6f36a3ac796c542a6ab4ddf6brianp to a unique serial number. This value is echoed
d7856f850b9b51165f23ae381a891bda894e1373ianh back to the application by the remote server.
d7856f850b9b51165f23ae381a891bda894e1373ianh (4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to
ab2053f3cdda69cfa5e4ce0800ea7af203cc6d5ddougm (6) Call <function>lwres_*request_render()</function>,
ab2053f3cdda69cfa5e4ce0800ea7af203cc6d5ddougm or marshall in the data using the primitives
88ecd979f1112454432371f55a1420240fae3743trawick and storing the packet data.
548e06e26f5377b2efbb7e0dab20f536e5e24160trawick (7) Transmit the resulting buffer.
c02a689f2274966ed5d1c16207f74b5128c35c86trawick (8) Call <function>lwres_*response_parse()</function>
c02a689f2274966ed5d1c16207f74b5128c35c86trawick to parse any packets received.
f51dbb1f5b66d94b5c190bfcd444aa73bdc2b176trawick (9) Verify that the opcode and serial match a request, and process the
aa202cda00837ed5381d5f67254e08c565a5c3a8stoddard packet specific information contained in the body.
aa202cda00837ed5381d5f67254e08c565a5c3a8stoddard </refsect1>
aa202cda00837ed5381d5f67254e08c565a5c3a8stoddard When implementing the server side of the lightweight resolver
aa202cda00837ed5381d5f67254e08c565a5c3a8stoddard protocol using the lwres library, a sequence of actions like the
aa202cda00837ed5381d5f67254e08c565a5c3a8stoddard following is typically involved in processing each request packet.
94f4821a5444a4fe782f772aef5db4d8b839675djerenkrantz in both the <function>_parse()</function> and <function>_render()</function> calls,
94f4821a5444a4fe782f772aef5db4d8b839675djerenkrantz with only a few modifications made
94f4821a5444a4fe782f772aef5db4d8b839675djerenkrantz to the packet header's contents between uses. This method is
2a49e30bae376c9744b96c8681ab88122ccaa46cjerenkrantz as it keeps the serial, opcode, and other fields correct.
afef080e47ef499a5cbceb7ad7fadbb3abca0b48minfrin (1) When a packet is received, call <function>lwres_*request_parse()</function> to
afef080e47ef499a5cbceb7ad7fadbb3abca0b48minfrin unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
afef080e47ef499a5cbceb7ad7fadbb3abca0b48minfrin as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
afef080e47ef499a5cbceb7ad7fadbb3abca0b48minfrin (2) Process the request in the data specific type.
afef080e47ef499a5cbceb7ad7fadbb3abca0b48minfrin <structfield>pkt.recvlength</structfield> as above. All other fields
c49200a2bdbb8fa1f2e5c3b87cc497ecdeefa8feminfrin be left untouched since they were filled in by the <function>*_parse()</function> call
c49200a2bdbb8fa1f2e5c3b87cc497ecdeefa8feminfrin above. If using <function>lwres_*response_render()</function>,
c49200a2bdbb8fa1f2e5c3b87cc497ecdeefa8feminfrin <structfield>pkt.pktflags</structfield> will be set up
c49200a2bdbb8fa1f2e5c3b87cc497ecdeefa8feminfrin properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
92d311b27a6182c2eed67317990c8c168584ee75trawick (4) Call the data specific rendering function, such as
92d311b27a6182c2eed67317990c8c168584ee75trawick (5) Send the resulting packet to the client.
6f0dd808a674b7c09a625b36f320030f4e339f8faaron </refsect1>
59511de77b389ced52253d055fc470ecfedfcd99aaron <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
59511de77b389ced52253d055fc470ecfedfcd99aaron </citerefentry>,
b5cdec7910a44654cb254b99c5a39d7c180c4bcajerenkrantz <citerefentry>
b5cdec7910a44654cb254b99c5a39d7c180c4bcajerenkrantz <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
b5cdec7910a44654cb254b99c5a39d7c180c4bcajerenkrantz </citerefentry>,
393bfaab1beb2410959a4a5e91f58446f01bac09rbb <citerefentry>
c10fe96ac7d024918e26af6c8ba5470273b75bb2jwoolley <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
6c2dc61d4760fa5e356f95c4b1685eec7f1d75dcaaron </citerefentry>,
6c2dc61d4760fa5e356f95c4b1685eec7f1d75dcaaron <citerefentry>
6c2dc61d4760fa5e356f95c4b1685eec7f1d75dcaaron <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
6c2dc61d4760fa5e356f95c4b1685eec7f1d75dcaaron </citerefentry>,
6c2dc61d4760fa5e356f95c4b1685eec7f1d75dcaaron <citerefentry>
6c2dc61d4760fa5e356f95c4b1685eec7f1d75dcaaron <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
01e8aca9299a0b872414c24c8b7724d6f88ae665ianh </citerefentry>,
01e8aca9299a0b872414c24c8b7724d6f88ae665ianh <citerefentry>
f783dff0c8b69344a6b67e97f16b91f8b0790799dougm <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
f783dff0c8b69344a6b67e97f16b91f8b0790799dougm </citerefentry>,
f783dff0c8b69344a6b67e97f16b91f8b0790799dougm <citerefentry>
f783dff0c8b69344a6b67e97f16b91f8b0790799dougm <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
6362515725d2b6d66ac3b26531f8c53ac75f8c20wrowe </citerefentry>,
f783dff0c8b69344a6b67e97f16b91f8b0790799dougm <citerefentry>
6362515725d2b6d66ac3b26531f8c53ac75f8c20wrowe <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
6362515725d2b6d66ac3b26531f8c53ac75f8c20wrowe </citerefentry>,
98ae9b96926a3dd99b195d7628c7e527e720f6acaaron <citerefentry>
98ae9b96926a3dd99b195d7628c7e527e720f6acaaron <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
98ae9b96926a3dd99b195d7628c7e527e720f6acaaron </citerefentry>,
98ae9b96926a3dd99b195d7628c7e527e720f6acaaron <citerefentry>
98ae9b96926a3dd99b195d7628c7e527e720f6acaaron <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
98ae9b96926a3dd99b195d7628c7e527e720f6acaaron </citerefentry>.
9379749d811388a7d0e3410940ddd6743a33d330jim </refsect1>
9379749d811388a7d0e3410940ddd6743a33d330jim - Local variables:
9379749d811388a7d0e3410940ddd6743a33d330jim - mode: sgml