lwres.html revision 8a66318e41ed14c5a88130e8c362610e8faa2121
ad53c2449238379699243be05926645262e9581eChristian Maeder - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
e9458b1a7a19a63aa4c179f9ab20f4d50681c168Jens Elkner - Copyright (C) 2001 Internet Software Consortium.
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder - Permission to use, copy, modify, and distribute this software for any
98890889ffb2e8f6f722b00e265a211f13b5a861Corneliu-Claudiu Prodescu - purpose with or without fee is hereby granted, provided that the above
e899b993b4f642217274fda6f462fe1318ae3626Christian Maeder - copyright notice and this permission notice appear in all copies.
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
679d3f541f7a9ede4079e045f7758873bb901872Till Mossakowski - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
02dc9cda66fc907229f0c74658c5f0bec550f898Till Mossakowski - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
02dc9cda66fc907229f0c74658c5f0bec550f898Till Mossakowski - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
02dc9cda66fc907229f0c74658c5f0bec550f898Till Mossakowski - PERFORMANCE OF THIS SOFTWARE.
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder<!-- $Id: lwres.html,v 1.5 2004/03/05 08:32:19 marka Exp $ -->
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian MaederNAME="GENERATOR"
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian MaederCONTENT="Modular DocBook HTML Stylesheet Version 1.73
b09c4ce9ee62d8b62f6c7bb12956a3dea4defd95Till MossakowskiCLASS="REFENTRY"
b09c4ce9ee62d8b62f6c7bb12956a3dea4defd95Till MossakowskiBGCOLOR="#FFFFFF"
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian MaederTEXT="#000000"
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian MaederLINK="#0000FF"
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian MaederVLINK="#840084"
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian MaederALINK="#0000FF"
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian MaederCLASS="REFNAMEDIV"
e220b2051a2342a9291721e6c7f408860bed01b7Jorina Freya Gerken>lwres -- introduction to the lightweight resolver library</DIV
f3e815e0f960f2c002904b18ad75c149a3827d9fChristian MaederCLASS="REFSYNOPSISDIV"
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian MaederCLASS="FUNCSYNOPSIS"
df9a64f1f61bf944b2116f92fce7083ff291debcChristian MaederCLASS="FUNCSYNOPSISINFO"
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederCLASS="REFSECT1"
87ad371ce86a15cd4424f59fa2fb8393f496cca4Mihai Codescu>DESCRIPTION</H2
9fa5b06733fe318e18d9b8e0ef58e5d1ec953f7cMaciek Makowski>The BIND 9 lightweight resolver library is a simple, name service
22dac733a93bc32b8db195625edea6364079a89eChristian Maederindependent stub resolver library. It provides hostname-to-address
22dac733a93bc32b8db195625edea6364079a89eChristian Maederand address-to-hostname lookup services to applications by
22dac733a93bc32b8db195625edea6364079a89eChristian Maedertransmitting lookup requests to a resolver daemon
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederCLASS="COMMAND"
28cbeb7eb61216d3b5a27dca176333d1ff8d3357Mihai Codescurunning on the local host. The resover daemon performs the
22dac733a93bc32b8db195625edea6364079a89eChristian Maederlookup using the DNS or possibly other name service protocols,
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederand returns the results to the application through the library.
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederThe library and resolver daemon communicate using a simple
22dac733a93bc32b8db195625edea6364079a89eChristian MaederUDP-based protocol.</P
c246854fd9abd0cdb3d11a52a350ebad2fbaa09bChristian MaederCLASS="REFSECT1"
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian Maeder>The lwresd library implements multiple name service APIs.
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian MaederCLASS="FUNCTION"
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian Maeder>gethostbyname()</TT
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederCLASS="FUNCTION"
7a6c50ecdec40e0278e8ed4fdadfd669112d887dChristian Maeder>gethostbyaddr()</TT
7a6c50ecdec40e0278e8ed4fdadfd669112d887dChristian MaederCLASS="FUNCTION"
e46d78f7c6324ed9f1a191d46b6e5732e61e1835Simon Ulbricht>gethostbyname_r()</TT
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="FUNCTION"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder>gethostbyaddr_r()</TT
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="FUNCTION"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder>getaddrinfo()</TT
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian MaederCLASS="FUNCTION"
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian Maeder>getipnodebyname()</TT
e46d78f7c6324ed9f1a191d46b6e5732e61e1835Simon UlbrichtCLASS="FUNCTION"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder>getipnodebyaddr()</TT
22dac733a93bc32b8db195625edea6364079a89eChristian Maederfunctions are all supported. To allow the lwres library to coexist
22dac733a93bc32b8db195625edea6364079a89eChristian Maederwith system libraries that define functions of the same name,
22dac733a93bc32b8db195625edea6364079a89eChristian Maederthe library defines these functions with names prefixed by
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="LITERAL"
ea8e98e298f33f9362293f392c8fb192722b8904Eugen KuksaTo define the standard names, applications must include the
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="FILENAME"
94fab9c2984681c5be0eb1c718efa70dd8f7bd31Igor Stassiywhich contains macro definitions mapping the standard function names
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederCLASS="LITERAL"
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maederprefixed ones. Operating system vendors who integrate the lwres
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maederlibrary into their base distributions should rename the functions
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maederin the library proper so that the renaming macros are not needed.</P
e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder>The library also provides a native API consisting of the functions
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederCLASS="FUNCTION"
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder>lwres_getaddrsbyname()</TT
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian MaederCLASS="FUNCTION"
7688e20f844fe88f75c04016841ebb5e5e3d927fChristian Maeder>lwres_getnamebyaddr()</TT
0155c8d32b79581866f07cc593aa8a4c722ceef2Christian MaederThese may be called by applications that require more detailed
bfb2ae5ac1ccfacbfa29ffa240838461e18f4d49Christian Maedercontrol over the lookup process than the standard functions
b5a5755f7d034f5ebc9f7f45e878c68695e139c4Thiemo Wiedemeyer>In addition to these name service independent address lookup
0bc3e99a05ed12fafe271ab855c15c866b50827cMihai Codescufunctions, the library implements a new, experimental API
c488ac18796ad6383b1edf7fa2820edc8296c89eChristian Maederfor looking up arbitrary DNS resource records, using the
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian MaederCLASS="FUNCTION"
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder>lwres_getaddrsbyname()</TT
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaederfunction.</P
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder>Finally, there is a low-level API for converting lookup
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maederrequests and responses to and from raw lwres protocol packets.
b5a5755f7d034f5ebc9f7f45e878c68695e139c4Thiemo WiedemeyerThis API can be used by clients requiring nonblocking operation,
22dac733a93bc32b8db195625edea6364079a89eChristian Maederand is also used when implementing the server side of the lwres
22dac733a93bc32b8db195625edea6364079a89eChristian Maederprotocol, for example in the
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="COMMAND"
8a2beea4bd05c640b6848837c2ab0399f22afb72Christian Maederresolver daemon. The use of this low-level API in clients
c1d06b3018b34ede2b3fb6c7fe2ad28cd5ce5b68Christian Maederand servers is outlined in the following sections.</P
c72a6b711518a31fe947a03601426d06c59edbd2Christian MaederCLASS="REFSECT1"
c72a6b711518a31fe947a03601426d06c59edbd2Christian Maeder>CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder>When a client program wishes to make an lwres request using the
db7143998eee23e3d781f1f1e97e953bb831df1fTill Mossakowskinative low-level API, it typically performs the following
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maedersequence of actions.</P
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder>(1) Allocate or use an existing <SPAN
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder>lwres_packet_t</SPAN
9a9860760c6f30558e5e60049692b6fc63904590Markus GrossCLASS="VARNAME"
591c279c7bacf79bccdb1e7417cc44130527d895Christian MaederCLASS="STRUCTFIELD"
260bfc3b7dc8ed037b7d98ee044302415db6fcd7Christian Maeder> to the maximum length we will accept.
260bfc3b7dc8ed037b7d98ee044302415db6fcd7Christian MaederThis is done so the receiver of our packets knows how large our receive
260bfc3b7dc8ed037b7d98ee044302415db6fcd7Christian Maederbuffer is. The "default" is a constant in
a3963596b8a24e870708767e064a9e24cfa7e5edChristian MaederCLASS="FILENAME"
591c279c7bacf79bccdb1e7417cc44130527d895Christian MaederCLASS="CONSTANT"
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder>LWRES_RECVLENGTH = 4096</TT
92487d2ec0c4f9fa81e0213311e214861d232f42Thiemo WiedemeyerCLASS="STRUCTFIELD"
92487d2ec0c4f9fa81e0213311e214861d232f42Thiemo Wiedemeyerto a unique serial number. This value is echoed
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maederback to the application by the remote server.</P
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo WiedemeyerCLASS="STRUCTFIELD"
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder>. Usually this is set to 0.</P
38e6a7281140deb96436868d396e1a0a3c934c2cChristian MaederCLASS="STRUCTFIELD"
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="FUNCTION"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder>lwres_*request_render()</TT
87ad371ce86a15cd4424f59fa2fb8393f496cca4Mihai Codescuor marshall in the data using the primitives
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="FUNCTION"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder>lwres_packet_render()</TT
22dac733a93bc32b8db195625edea6364079a89eChristian Maederand storing the packet data.</P
ea8e98e298f33f9362293f392c8fb192722b8904Eugen Kuksa>(7) Transmit the resulting buffer.</P
ea8e98e298f33f9362293f392c8fb192722b8904Eugen Kuksa>(8) Call <TT
ea8e98e298f33f9362293f392c8fb192722b8904Eugen KuksaCLASS="FUNCTION"
e4e39c9a78ab34bafd75b292839c20506e7f539bMihai Codescu>lwres_*response_parse()</TT
ea8e98e298f33f9362293f392c8fb192722b8904Eugen Kuksato parse any packets received.</P
10f46e60ea9ea8787e4584ad0a9e5db6cfd76446Christian Maeder>(9) Verify that the opcode and serial match a request, and process the
10f46e60ea9ea8787e4584ad0a9e5db6cfd76446Christian Maederpacket specific information contained in the body.</P
3fe83d4c932a8266edcf0304a97814c59821d91fChristian MaederCLASS="REFSECT1"
9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder>SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
d24317c8197e565e60c8f41309de246249c1e57eChristian Maeder>When implementing the server side of the lightweight resolver
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maederprotocol using the lwres library, a sequence of actions like the
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maederfollowing is typically involved in processing each request packet.</P
fa8878c6145f652f615a04a5e9c15a1d1327bc92cmaeder>Note that the same <SPAN
e426842636f7f3b76ad57d4c7b16a024cf6cf08cCui JianCLASS="TYPE"
09aa12aebe61c224a53ed608808baf11130e03b1Christian Maeder>lwres_packet_t</SPAN
09aa12aebe61c224a53ed608808baf11130e03b1Christian Maederin both the <TT
9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian MaederCLASS="FUNCTION"
09aa12aebe61c224a53ed608808baf11130e03b1Christian MaederCLASS="FUNCTION"
e055d03c5a3acdcaa978bceadbd4e27926f54756Christian Maeder>_render()</TT
17be7914f897d0b0c6488eb1391f5695ec74f7e1Christian Maederwith only a few modifications made
e055d03c5a3acdcaa978bceadbd4e27926f54756Christian Maederto the packet header's contents between uses. This method is recommended
26210e52bda19c75ac6a4287d16ce9d8789b68deChristian Maederas it keeps the serial, opcode, and other fields correct.</P
26210e52bda19c75ac6a4287d16ce9d8789b68deChristian Maeder>(1) When a packet is received, call <TT
26210e52bda19c75ac6a4287d16ce9d8789b68deChristian MaederCLASS="FUNCTION"
26210e52bda19c75ac6a4287d16ce9d8789b68deChristian Maeder>lwres_*request_parse()</TT
26210e52bda19c75ac6a4287d16ce9d8789b68deChristian Maederunmarshall it. This returns a <SPAN
ad53c2449238379699243be05926645262e9581eChristian Maeder>lwres_packet_t</SPAN
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder> (also called <TT
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="VARNAME"
d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maederas well as a data specific type, such as <SPAN
f5257648a040fda02fc27a28b1d17f6ba53307c5Christian Maeder>lwres_gabnrequest_t</SPAN
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder>(2) Process the request in the data specific type.</P
f45fad43ee1673ab280fbc700821d5d20a493eaaChristian Maeder>(3) Set the <TT
f5257648a040fda02fc27a28b1d17f6ba53307c5Christian MaederCLASS="STRUCTFIELD"
d11391a2447a2005329a95b5d770f24e62bf5b63Christian MaederCLASS="STRUCTFIELD"
9d2674ede8060c67e3af884c58e1a7ab9d19a611Christian Maeder> as above. All other fields can
f5257648a040fda02fc27a28b1d17f6ba53307c5Christian Maederbe left untouched since they were filled in by the <TT
40f8e29910681011b2bd04b21e85eb6a8d348f9cEwaryst SchulzCLASS="FUNCTION"
d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder>*_parse()</TT
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maederabove. If using <TT
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian MaederCLASS="FUNCTION"
f5257648a040fda02fc27a28b1d17f6ba53307c5Christian Maeder>lwres_*response_render()</TT
eccd7c7446e270bda674c07248d04fccc41cba0bSimon UlbrichtCLASS="STRUCTFIELD"
d11391a2447a2005329a95b5d770f24e62bf5b63Christian Maeder> will be set up
22dac733a93bc32b8db195625edea6364079a89eChristian Maederproperly. Otherwise, the <TT
22dac733a93bc32b8db195625edea6364079a89eChristian MaederCLASS="CONSTANT"
ad1f65fa6375114f84888537c9b6d34deae8e16eChristian Maeder>LWRES_LWPACKETFLAG_RESPONSE</TT
9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder> bit should be
fa1bf658051ac503f27ff1b59edb093398eed6edThiemo Wiedemeyer>(4) Call the data specific rendering function, such as
9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian MaederCLASS="FUNCTION"
9192fdd8f0e682ac0f0183dd854d5210fbfa4ec5Christian Maeder>lwres_gabnresponse_render()</TT
fa1bf658051ac503f27ff1b59edb093398eed6edThiemo Wiedemeyer>(5) Send the resulting packet to the client.</P
d24317c8197e565e60c8f41309de246249c1e57eChristian MaederCLASS="REFSECT1"
a0efda9ffb465daf1e735c5ced1be3174af42dffChristian MaederCLASS="CITEREFENTRY"
a0efda9ffb465daf1e735c5ced1be3174af42dffChristian MaederCLASS="REFENTRYTITLE"
a0efda9ffb465daf1e735c5ced1be3174af42dffChristian Maeder>lwres_gethostent</SPAN
5b00a9d748d5bea461601ed7ed5198dfd30cf2d2Thiemo WiedemeyerCLASS="CITEREFENTRY"
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo WiedemeyerCLASS="REFENTRYTITLE"
be5ff99194b2ba0a1a35093e0ea21d4da332b526Christian Maeder>lwres_getipnode</SPAN
17be7914f897d0b0c6488eb1391f5695ec74f7e1Christian MaederCLASS="CITEREFENTRY"
17be7914f897d0b0c6488eb1391f5695ec74f7e1Christian MaederCLASS="REFENTRYTITLE"
17be7914f897d0b0c6488eb1391f5695ec74f7e1Christian Maeder>lwres_getnameinfo</SPAN
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="CITEREFENTRY"
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="REFENTRYTITLE"
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder>lwres_noop</SPAN
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="CITEREFENTRY"
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="REFENTRYTITLE"
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder>lwres_gabn</SPAN
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="CITEREFENTRY"
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="REFENTRYTITLE"
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder>lwres_gnba</SPAN
a5bd19ccaa5ad701cbfb9fdee0514f6e5d7fbc35Christian MaederCLASS="CITEREFENTRY"
a5bd19ccaa5ad701cbfb9fdee0514f6e5d7fbc35Christian MaederCLASS="REFENTRYTITLE"
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder>lwres_context</SPAN
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="CITEREFENTRY"
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="REFENTRYTITLE"
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder>lwres_config</SPAN
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="CITEREFENTRY"
cb677b28797cf29452620f58606e174ab93ac426Christian MaederCLASS="REFENTRYTITLE"
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder>resolver</SPAN
85e47ae3b5dc43834dd9b10af3bd42ca2e10fc88mscodescuCLASS="CITEREFENTRY"
85e47ae3b5dc43834dd9b10af3bd42ca2e10fc88mscodescuCLASS="REFENTRYTITLE"
85e47ae3b5dc43834dd9b10af3bd42ca2e10fc88mscodescu>lwresd</SPAN