lwres.html revision 2cd182921e1b04ccda0a56995c4cc491c882af04
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2001 Internet Software Consortium.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - Permission to use, copy, modify, and distribute this software for any
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder - PERFORMANCE OF THIS SOFTWARE.
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowski<!-- $Id: lwres.html,v 1.8 2004/08/23 00:05:47 marka Exp $ -->
760ae19a92dde8249679a674f93f58d26a7c5f6bChristian Maeder<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederNAME="GENERATOR"
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="REFENTRY"
8410667510a76409aca9bb24ff0eda0420088274Christian MaederBGCOLOR="#FFFFFF"
8410667510a76409aca9bb24ff0eda0420088274Christian MaederTEXT="#000000"
8410667510a76409aca9bb24ff0eda0420088274Christian MaederLINK="#0000FF"
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus LuettichVLINK="#840084"
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus LuettichALINK="#0000FF"
e593b89bfd4952698dc37feced21cefe869d87a2Christian MaederCLASS="REFNAMEDIV"
c6fcd42c6d6d9dae8c7835c24fcb7ce8531a9050Christian Maeder>lwres -- introduction to the lightweight resolver library</DIV
c55a0f77be7e88d3620b419ec8961f4379a586e3Klaus LuettichCLASS="REFSYNOPSISDIV"
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="FUNCSYNOPSIS"
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="FUNCSYNOPSISINFO"
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus LuettichCLASS="REFSECT1"
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder>DESCRIPTION</H2
77a65251ee036c6aaf09c2775315a4ee24259fbdJorina Freya Gerken>The BIND 9 lightweight resolver library is a simple, name service
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederindependent stub resolver library. It provides hostname-to-address
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederand address-to-hostname lookup services to applications by
4d7d7f9a423490731c73403c7806bd66967da946Christian Maedertransmitting lookup requests to a resolver daemon
97812b7ce9860bf514a8822a63503451795dbc65Klaus LuettichCLASS="COMMAND"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederrunning on the local host. The resover daemon performs the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederlookup using the DNS or possibly other name service protocols,
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederand returns the results to the application through the library.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederThe library and resolver daemon communicate using a simple
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederUDP-based protocol.</P
4e7050bcbcf0f372a5bad32ecd0282bccabf0983Klaus LuettichCLASS="REFSECT1"
ebe517300051f765f2ed856a789dd5613d681ab0Klaus Luettich>The lwresd library implements multiple name service APIs.
6ae5607d2def114f998fd49bac4eef12a2620fafChristian MaederCLASS="FUNCTION"
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder>gethostbyname()</CODE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="FUNCTION"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>gethostbyaddr()</CODE
ebe517300051f765f2ed856a789dd5613d681ab0Klaus LuettichCLASS="FUNCTION"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>gethostbyname_r()</CODE
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian MaederCLASS="FUNCTION"
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder>gethostbyaddr_r()</CODE
ce50fe187cdae64e75e510daafb78156280bdb91Christian MaederCLASS="FUNCTION"
4e7050bcbcf0f372a5bad32ecd0282bccabf0983Klaus Luettich>getaddrinfo()</CODE
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian MaederCLASS="FUNCTION"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>getipnodebyname()</CODE
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="FUNCTION"
9df11f85fd7f8c4745d64464876e84ec4e263692Christian Maeder>getipnodebyaddr()</CODE
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersfunctions are all supported. To allow the lwres library to coexist
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus Luettichwith system libraries that define functions of the same name,
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus Luettichthe library defines these functions with names prefixed by
c432483b64662e8db604a58758cd18ea7fa65659Christian MaederCLASS="LITERAL"
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian MaederTo define the standard names, applications must include the
c5e10ba19c9854112e5d29f491759e8e89f83652Christian MaederCLASS="FILENAME"
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowskiwhich contains macro definitions mapping the standard function names
eeb419aa20c97b4af973e97ee6ae77a8eed29e15Till MossakowskiCLASS="LITERAL"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersprefixed ones. Operating system vendors who integrate the lwres
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maederlibrary into their base distributions should rename the functions
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maederin the library proper so that the renaming macros are not needed.</P
7d09621f989f5e6dfbf603b36b2fccbacf639a3cTill Mossakowski>The library also provides a native API consisting of the functions
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till MossakowskiCLASS="FUNCTION"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>lwres_getaddrsbyname()</CODE
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till MossakowskiCLASS="FUNCTION"
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski>lwres_getnamebyaddr()</CODE
b49276c9f50038e0bd499ad49f7bd6444566a834Christian MaederThese may be called by applications that require more detailed
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maedercontrol over the lookup process than the standard functions
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder>In addition to these name service independent address lookup
c0c2380bced8159ff0297ece14eba948bd236471Christian Maederfunctions, the library implements a new, experimental API
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederfor looking up arbitrary DNS resource records, using the
6e049108aa87dc46bcff96fae50a4625df1d9648Klaus LuettichCLASS="FUNCTION"
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>lwres_getaddrsbyname()</CODE
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>Finally, there is a low-level API for converting lookup
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maederrequests and responses to and from raw lwres protocol packets.
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian MaederThis API can be used by clients requiring nonblocking operation,
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maederand is also used when implementing the server side of the lwres
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maederprotocol, for example in the
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian MaederCLASS="COMMAND"
53818ced114da21321063fff307aa41c1ab31dd3Achim Mahnkeresolver daemon. The use of this low-level API in clients
53818ced114da21321063fff307aa41c1ab31dd3Achim Mahnkeand servers is outlined in the following sections.</P
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFSECT1"
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maeder>CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>When a client program wishes to make an lwres request using the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maedernative low-level API, it typically performs the following
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckerssequence of actions.</P
88c800932dd7053322501ea2039d9f234be6866cKlaus Luettich>(1) Allocate or use an existing <SPAN
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder>lwres_packet_t</SPAN
33d042fe6a9eb27a4c48f840b80838f3e7d98e34Christian MaederCLASS="VARNAME"
621799f077b3a1ed0f5a35382cfad0602c255b20Klaus Luettich>(2) Set <CODE
05a8b581f98b928baca6dab60cd20277659ac760Christian MaederCLASS="STRUCTFIELD"
fa21fba9ceb1ddf7b3efd54731a12ed8750191d8Christian Maeder> to the maximum length we will accept.
b49276c9f50038e0bd499ad49f7bd6444566a834Christian MaederThis is done so the receiver of our packets knows how large our receive
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederbuffer is. The "default" is a constant in
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="FILENAME"
b905126bab9454b89041f92b3c50bb9efc85e427Klaus LuettichCLASS="CONSTANT"
51e836611726885f6d2719d959ed1b51f8fd06f4Klaus Luettich>LWRES_RECVLENGTH = 4096</CODE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>(3) Set <CODE
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian MaederCLASS="STRUCTFIELD"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederto a unique serial number. This value is echoed
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederback to the application by the remote server.</P
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>(4) Set <CODE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="STRUCTFIELD"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>. Usually this is set to 0.</P
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>(5) Set <CODE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="STRUCTFIELD"
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettich>(6) Call <CODE
b905126bab9454b89041f92b3c50bb9efc85e427Klaus LuettichCLASS="FUNCTION"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_*request_render()</CODE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maederor marshall in the data using the primitives
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="FUNCTION"
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>lwres_packet_render()</CODE
ef67402074be14deb95e4ff564737d5593144130Klaus Luettichand storing the packet data.</P
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder>(7) Transmit the resulting buffer.</P
5958fabb264ec3f5b2125ac5602121bd34814a79Klaus Luettich>(8) Call <CODE
5958fabb264ec3f5b2125ac5602121bd34814a79Klaus LuettichCLASS="FUNCTION"
e7e1ab2ac3f1fded8611bb92ae00e8f3b8c693fbKlaus Luettich>lwres_*response_parse()</CODE
1323eba62fc519b068f5aaec4f9d2be05ffabea9Klaus Luettichto parse any packets received.</P
1323eba62fc519b068f5aaec4f9d2be05ffabea9Klaus Luettich>(9) Verify that the opcode and serial match a request, and process the
725a68ec81cba9b8aa8647bebfb5baa449803e7eKlaus Luettichpacket specific information contained in the body.</P
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFSECT1"
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder>SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich>When implementing the server side of the lightweight resolver
4e7050bcbcf0f372a5bad32ecd0282bccabf0983Klaus Luettichprotocol using the lwres library, a sequence of actions like the
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederfollowing is typically involved in processing each request packet.</P
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder>Note that the same <SPAN
4e7050bcbcf0f372a5bad32ecd0282bccabf0983Klaus Luettich>lwres_packet_t</SPAN
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian Maederin both the <CODE
e593b89bfd4952698dc37feced21cefe869d87a2Christian MaederCLASS="FUNCTION"
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian Maeder>_parse()</CODE
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till MossakowskiCLASS="FUNCTION"
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder>_render()</CODE
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederwith only a few modifications made
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederto the packet header's contents between uses. This method is recommended
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederas it keeps the serial, opcode, and other fields correct.</P
94d3aa05411444596b44ede4531f05dd7ac20fdfChristian Maeder>(1) When a packet is received, call <CODE
dc929508a3bd3c666e9b0182d56898fcafb5d66fChristian MaederCLASS="FUNCTION"
dc929508a3bd3c666e9b0182d56898fcafb5d66fChristian Maeder>lwres_*request_parse()</CODE
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maederunmarshall it. This returns a <SPAN
ddc9315cc0b1f5dd3d8f99a77f1c75064db33b48Christian Maeder>lwres_packet_t</SPAN
ddc9315cc0b1f5dd3d8f99a77f1c75064db33b48Christian Maeder> (also called <VAR
5d522dff4d0fabf57dd476d4c3de15d354a89f62Christian MaederCLASS="VARNAME"
8410667510a76409aca9bb24ff0eda0420088274Christian Maederas well as a data specific type, such as <SPAN
8410667510a76409aca9bb24ff0eda0420088274Christian Maeder>lwres_gabnrequest_t</SPAN
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>(2) Process the request in the data specific type.</P
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>(3) Set the <CODE
c0c2380bced8159ff0297ece14eba948bd236471Christian MaederCLASS="STRUCTFIELD"
d17834302eaa101395b4b806cd73670fd864445fChristian MaederCLASS="STRUCTFIELD"
88c66e48620750c42b94db9feb01b42ae23dba97Till Mossakowski> as above. All other fields can
ce8b15da31cd181b7e90593cbbca98f47eda29d6Till Mossakowskibe left untouched since they were filled in by the <CODE
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian MaederCLASS="FUNCTION"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>*_parse()</CODE
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersabove. If using <CODE
ac43fa22d2d3f91a17674ac164cba3cf39a17795Klaus LuettichCLASS="FUNCTION"
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers>lwres_*response_render()</CODE
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="STRUCTFIELD"
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder> will be set up
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckersproperly. Otherwise, the <CODE
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="CONSTANT"
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder>LWRES_LWPACKETFLAG_RESPONSE</CODE
88c66e48620750c42b94db9feb01b42ae23dba97Till Mossakowski> bit should be
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder>(4) Call the data specific rendering function, such as
ba0ec5e897ef99d420c8c14c2374e0f32b7043dbKlaus LuettichCLASS="FUNCTION"
ba0ec5e897ef99d420c8c14c2374e0f32b7043dbKlaus Luettich>lwres_gabnresponse_render()</CODE
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>(5) Send the resulting packet to the client.</P
6e049108aa87dc46bcff96fae50a4625df1d9648Klaus LuettichCLASS="REFSECT1"
d67a33b40578beef2e255a274f89bb9c34aaf056Christian MaederCLASS="CITEREFENTRY"
d67a33b40578beef2e255a274f89bb9c34aaf056Christian MaederCLASS="REFENTRYTITLE"
26f228bf3a3fea810223396e5794c217a79a8d5bChristian Maeder>lwres_gethostent</SPAN
ba904a15082557e939db689fcfba0c68c9a4f740Christian MaederCLASS="CITEREFENTRY"
6ae5607d2def114f998fd49bac4eef12a2620fafChristian MaederCLASS="REFENTRYTITLE"
6ae5607d2def114f998fd49bac4eef12a2620fafChristian Maeder>lwres_getipnode</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
26f228bf3a3fea810223396e5794c217a79a8d5bChristian Maeder>lwres_getnameinfo</SPAN
75cda7e5b890d050d560d970af244a183f28328fKlaus LuettichCLASS="CITEREFENTRY"
b9625461755578f3eed04676d42a63fd2caebd0cChristian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_noop</SPAN
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix ReckersCLASS="CITEREFENTRY"
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian MaederCLASS="REFENTRYTITLE"
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian Maeder>lwres_gabn</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
470ca7a2797069ae4b27c34c1b71419f67be1f84Christian Maeder>lwres_gnba</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_context</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>lwres_config</SPAN
481d4fe351800ab00fd323db8974559431227305Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder>resolver</SPAN
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="CITEREFENTRY"
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian MaederCLASS="REFENTRYTITLE"