/contrib/bind9/lib/dns/include/dns/adb.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 634 lines · 101 code · 42 blank · 491 comment · 0 complexity · 90d2d816366c81b31628403fcbcbaffb MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2008, 2011, 2012 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 1999-2003 Internet Software Consortium.
  4. *
  5. * Permission to use, copy, modify, and/or distribute this software for any
  6. * purpose with or without fee is hereby granted, provided that the above
  7. * copyright notice and this permission notice appear in all copies.
  8. *
  9. * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. * PERFORMANCE OF THIS SOFTWARE.
  16. */
  17. /* $Id$ */
  18. #ifndef DNS_ADB_H
  19. #define DNS_ADB_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/adb.h
  24. *\brief
  25. * DNS Address Database
  26. *
  27. * This module implements an address database (ADB) for mapping a name
  28. * to an isc_sockaddr_t. It also provides statistical information on
  29. * how good that address might be.
  30. *
  31. * A client will pass in a dns_name_t, and the ADB will walk through
  32. * the rdataset looking up addresses associated with the name. If it
  33. * is found on the internal lists, a structure is filled in with the
  34. * address information and stats for found addresses.
  35. *
  36. * If the name cannot be found on the internal lists, a new entry will
  37. * be created for a name if all the information needed can be found
  38. * in the zone table or cache. This new address will then be returned.
  39. *
  40. * If a request must be made to remote servers to satisfy a name lookup,
  41. * this module will start fetches to try to complete these addresses. When
  42. * at least one more completes, an event is sent to the caller. If none of
  43. * them resolve before the fetch times out, an event indicating this is
  44. * sent instead.
  45. *
  46. * Records are stored internally until a timer expires. The timer is the
  47. * smaller of the TTL or signature validity period.
  48. *
  49. * Lameness is stored per <qname,qtype> tuple, and this data hangs off each
  50. * address field. When an address is marked lame for a given tuple the address
  51. * will not be returned to a caller.
  52. *
  53. *
  54. * MP:
  55. *
  56. *\li The ADB takes care of all necessary locking.
  57. *
  58. *\li Only the task which initiated the name lookup can cancel the lookup.
  59. *
  60. *
  61. * Security:
  62. *
  63. *\li None, since all data stored is required to be pre-filtered.
  64. * (Cache needs to be sane, fetches return bounds-checked and sanity-
  65. * checked data, caller passes a good dns_name_t for the zone, etc)
  66. */
  67. /***
  68. *** Imports
  69. ***/
  70. #include <isc/lang.h>
  71. #include <isc/magic.h>
  72. #include <isc/mem.h>
  73. #include <isc/sockaddr.h>
  74. #include <dns/types.h>
  75. #include <dns/view.h>
  76. ISC_LANG_BEGINDECLS
  77. /***
  78. *** Magic number checks
  79. ***/
  80. #define DNS_ADBFIND_MAGIC ISC_MAGIC('a','d','b','H')
  81. #define DNS_ADBFIND_VALID(x) ISC_MAGIC_VALID(x, DNS_ADBFIND_MAGIC)
  82. #define DNS_ADBADDRINFO_MAGIC ISC_MAGIC('a','d','A','I')
  83. #define DNS_ADBADDRINFO_VALID(x) ISC_MAGIC_VALID(x, DNS_ADBADDRINFO_MAGIC)
  84. /***
  85. *** TYPES
  86. ***/
  87. typedef struct dns_adbname dns_adbname_t;
  88. /*!
  89. *\brief
  90. * Represents a lookup for a single name.
  91. *
  92. * On return, the client can safely use "list", and can reorder the list.
  93. * Items may not be _deleted_ from this list, however, or added to it
  94. * other than by using the dns_adb_*() API.
  95. */
  96. struct dns_adbfind {
  97. /* Public */
  98. unsigned int magic; /*%< RO: magic */
  99. dns_adbaddrinfolist_t list; /*%< RO: list of addrs */
  100. unsigned int query_pending; /*%< RO: partial list */
  101. unsigned int partial_result; /*%< RO: addrs missing */
  102. unsigned int options; /*%< RO: options */
  103. isc_result_t result_v4; /*%< RO: v4 result */
  104. isc_result_t result_v6; /*%< RO: v6 result */
  105. ISC_LINK(dns_adbfind_t) publink; /*%< RW: client use */
  106. /* Private */
  107. isc_mutex_t lock; /* locks all below */
  108. in_port_t port;
  109. int name_bucket;
  110. unsigned int flags;
  111. dns_adbname_t *adbname;
  112. dns_adb_t *adb;
  113. isc_event_t event;
  114. ISC_LINK(dns_adbfind_t) plink;
  115. };
  116. /*
  117. * _INET:
  118. * _INET6:
  119. * return addresses of that type.
  120. *
  121. * _EMPTYEVENT:
  122. * Only schedule an event if no addresses are known.
  123. * Must set _WANTEVENT for this to be meaningful.
  124. *
  125. * _WANTEVENT:
  126. * An event is desired. Check this bit in the returned find to see
  127. * if one will actually be generated.
  128. *
  129. * _AVOIDFETCHES:
  130. * If set, fetches will not be generated unless no addresses are
  131. * available in any of the address families requested.
  132. *
  133. * _STARTATZONE:
  134. * Fetches will start using the closest zone data or use the root servers.
  135. * This is useful for reestablishing glue that has expired.
  136. *
  137. * _GLUEOK:
  138. * _HINTOK:
  139. * Glue or hints are ok. These are used when matching names already
  140. * in the adb, and when dns databases are searched.
  141. *
  142. * _RETURNLAME:
  143. * Return lame servers in a find, so that all addresses are returned.
  144. *
  145. * _LAMEPRUNED:
  146. * At least one address was omitted from the list because it was lame.
  147. * This bit will NEVER be set if _RETURNLAME is set in the createfind().
  148. */
  149. /*% Return addresses of type INET. */
  150. #define DNS_ADBFIND_INET 0x00000001
  151. /*% Return addresses of type INET6. */
  152. #define DNS_ADBFIND_INET6 0x00000002
  153. #define DNS_ADBFIND_ADDRESSMASK 0x00000003
  154. /*%
  155. * Only schedule an event if no addresses are known.
  156. * Must set _WANTEVENT for this to be meaningful.
  157. */
  158. #define DNS_ADBFIND_EMPTYEVENT 0x00000004
  159. /*%
  160. * An event is desired. Check this bit in the returned find to see
  161. * if one will actually be generated.
  162. */
  163. #define DNS_ADBFIND_WANTEVENT 0x00000008
  164. /*%
  165. * If set, fetches will not be generated unless no addresses are
  166. * available in any of the address families requested.
  167. */
  168. #define DNS_ADBFIND_AVOIDFETCHES 0x00000010
  169. /*%
  170. * Fetches will start using the closest zone data or use the root servers.
  171. * This is useful for reestablishing glue that has expired.
  172. */
  173. #define DNS_ADBFIND_STARTATZONE 0x00000020
  174. /*%
  175. * Glue or hints are ok. These are used when matching names already
  176. * in the adb, and when dns databases are searched.
  177. */
  178. #define DNS_ADBFIND_GLUEOK 0x00000040
  179. /*%
  180. * Glue or hints are ok. These are used when matching names already
  181. * in the adb, and when dns databases are searched.
  182. */
  183. #define DNS_ADBFIND_HINTOK 0x00000080
  184. /*%
  185. * Return lame servers in a find, so that all addresses are returned.
  186. */
  187. #define DNS_ADBFIND_RETURNLAME 0x00000100
  188. /*%
  189. * Only schedule an event if no addresses are known.
  190. * Must set _WANTEVENT for this to be meaningful.
  191. */
  192. #define DNS_ADBFIND_LAMEPRUNED 0x00000200
  193. /*%
  194. * The answers to queries come back as a list of these.
  195. */
  196. struct dns_adbaddrinfo {
  197. unsigned int magic; /*%< private */
  198. isc_sockaddr_t sockaddr; /*%< [rw] */
  199. unsigned int srtt; /*%< [rw] microseconds */
  200. unsigned int flags; /*%< [rw] */
  201. dns_adbentry_t *entry; /*%< private */
  202. ISC_LINK(dns_adbaddrinfo_t) publink;
  203. };
  204. /*!<
  205. * The event sent to the caller task is just a plain old isc_event_t. It
  206. * contains no data other than a simple status, passed in the "type" field
  207. * to indicate that another address resolved, or all partially resolved
  208. * addresses have failed to resolve.
  209. *
  210. * "sender" is the dns_adbfind_t used to issue this query.
  211. *
  212. * This is simply a standard event, with the "type" set to:
  213. *
  214. *\li #DNS_EVENT_ADBMOREADDRESSES -- another address resolved.
  215. *\li #DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed,
  216. * were canceled, or otherwise will
  217. * not be usable.
  218. *\li #DNS_EVENT_ADBCANCELED -- The request was canceled by a
  219. * 3rd party.
  220. *\li #DNS_EVENT_ADBNAMEDELETED -- The name was deleted, so this request
  221. * was canceled.
  222. *
  223. * In each of these cases, the addresses returned by the initial call
  224. * to dns_adb_createfind() can still be used until they are no longer needed.
  225. */
  226. /****
  227. **** FUNCTIONS
  228. ****/
  229. isc_result_t
  230. dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr,
  231. isc_taskmgr_t *taskmgr, dns_adb_t **newadb);
  232. /*%<
  233. * Create a new ADB.
  234. *
  235. * Notes:
  236. *
  237. *\li Generally, applications should not create an ADB directly, but
  238. * should instead call dns_view_createresolver().
  239. *
  240. * Requires:
  241. *
  242. *\li 'mem' must be a valid memory context.
  243. *
  244. *\li 'view' be a pointer to a valid view.
  245. *
  246. *\li 'tmgr' be a pointer to a valid timer manager.
  247. *
  248. *\li 'taskmgr' be a pointer to a valid task manager.
  249. *
  250. *\li 'newadb' != NULL && '*newadb' == NULL.
  251. *
  252. * Returns:
  253. *
  254. *\li #ISC_R_SUCCESS after happiness.
  255. *\li #ISC_R_NOMEMORY after resource allocation failure.
  256. */
  257. void
  258. dns_adb_attach(dns_adb_t *adb, dns_adb_t **adbp);
  259. /*%
  260. * Attach to an 'adb' to 'adbp'.
  261. *
  262. * Requires:
  263. *\li 'adb' to be a valid dns_adb_t, created via dns_adb_create().
  264. *\li 'adbp' to be a valid pointer to a *dns_adb_t which is initialized
  265. * to NULL.
  266. */
  267. void
  268. dns_adb_detach(dns_adb_t **adb);
  269. /*%
  270. * Delete the ADB. Sets *ADB to NULL. Cancels any outstanding requests.
  271. *
  272. * Requires:
  273. *
  274. *\li 'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via
  275. * dns_adb_create().
  276. */
  277. void
  278. dns_adb_whenshutdown(dns_adb_t *adb, isc_task_t *task, isc_event_t **eventp);
  279. /*%
  280. * Send '*eventp' to 'task' when 'adb' has shutdown.
  281. *
  282. * Requires:
  283. *
  284. *\li '*adb' is a valid dns_adb_t.
  285. *
  286. *\li eventp != NULL && *eventp is a valid event.
  287. *
  288. * Ensures:
  289. *
  290. *\li *eventp == NULL
  291. *
  292. *\li The event's sender field is set to the value of adb when the event
  293. * is sent.
  294. */
  295. void
  296. dns_adb_shutdown(dns_adb_t *adb);
  297. /*%<
  298. * Shutdown 'adb'.
  299. *
  300. * Requires:
  301. *
  302. * \li '*adb' is a valid dns_adb_t.
  303. */
  304. isc_result_t
  305. dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,
  306. void *arg, dns_name_t *name, dns_name_t *qname,
  307. dns_rdatatype_t qtype, unsigned int options,
  308. isc_stdtime_t now, dns_name_t *target,
  309. in_port_t port, dns_adbfind_t **find);
  310. /*%<
  311. * Main interface for clients. The adb will look up the name given in
  312. * "name" and will build up a list of found addresses, and perhaps start
  313. * internal fetches to resolve names that are unknown currently.
  314. *
  315. * If other addresses resolve after this call completes, an event will
  316. * be sent to the <task, taskaction, arg> with the sender of that event
  317. * set to a pointer to the dns_adbfind_t returned by this function.
  318. *
  319. * If no events will be generated, the *find->result_v4 and/or result_v6
  320. * members may be examined for address lookup status. The usual #ISC_R_SUCCESS,
  321. * #ISC_R_FAILURE, #DNS_R_NXDOMAIN, and #DNS_R_NXRRSET are returned, along with
  322. * #ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values. In this
  323. * latter case, retrying may produce more addresses.
  324. *
  325. * If events will be returned, the result_v[46] members are only valid
  326. * when that event is actually returned.
  327. *
  328. * The list of addresses returned is unordered. The caller must impose
  329. * any ordering required. The list will not contain "known bad" addresses,
  330. * however. For instance, it will not return hosts that are known to be
  331. * lame for the zone in question.
  332. *
  333. * The caller cannot (directly) modify the contents of the address list's
  334. * fields other than the "link" field. All values can be read at any
  335. * time, however.
  336. *
  337. * The "now" parameter is used only for determining which entries that
  338. * have a specific time to live or expire time should be removed from
  339. * the running database. If specified as zero, the current time will
  340. * be retrieved and used.
  341. *
  342. * If 'target' is not NULL and 'name' is an alias (i.e. the name is
  343. * CNAME'd or DNAME'd to another name), then 'target' will be updated with
  344. * the domain name that 'name' is aliased to.
  345. *
  346. * All addresses returned will have the sockaddr's port set to 'port.'
  347. * The caller may change them directly in the dns_adbaddrinfo_t since
  348. * they are copies of the internal address only.
  349. *
  350. * XXXMLG Document options, especially the flags which control how
  351. * events are sent.
  352. *
  353. * Requires:
  354. *
  355. *\li *adb be a valid isc_adb_t object.
  356. *
  357. *\li If events are to be sent, *task be a valid task,
  358. * and isc_taskaction_t != NULL.
  359. *
  360. *\li *name is a valid dns_name_t.
  361. *
  362. *\li qname != NULL and *qname be a valid dns_name_t.
  363. *
  364. *\li target == NULL or target is a valid name with a buffer.
  365. *
  366. *\li find != NULL && *find == NULL.
  367. *
  368. * Returns:
  369. *
  370. *\li #ISC_R_SUCCESS Addresses might have been returned, and events will be
  371. * delivered for unresolved addresses.
  372. *\li #ISC_R_NOMORE Addresses might have been returned, but no events
  373. * will ever be posted for this context. This is only
  374. * returned if task != NULL.
  375. *\li #ISC_R_NOMEMORY insufficient resources
  376. *\li #DNS_R_ALIAS 'name' is an alias for another name.
  377. *
  378. * Calls, and returns error codes from:
  379. *
  380. *\li isc_stdtime_get()
  381. *
  382. * Notes:
  383. *
  384. *\li No internal reference to "name" exists after this function
  385. * returns.
  386. */
  387. void
  388. dns_adb_cancelfind(dns_adbfind_t *find);
  389. /*%<
  390. * Cancels the find, and sends the event off to the caller.
  391. *
  392. * It is an error to call dns_adb_cancelfind() on a find where
  393. * no event is wanted, or will ever be sent.
  394. *
  395. * Note:
  396. *
  397. *\li It is possible that the real completion event was posted just
  398. * before the dns_adb_cancelfind() call was made. In this case,
  399. * dns_adb_cancelfind() will do nothing. The event callback needs
  400. * to be prepared to find this situation (i.e. result is valid but
  401. * the caller expects it to be canceled).
  402. *
  403. * Requires:
  404. *
  405. *\li 'find' be a valid dns_adbfind_t pointer.
  406. *
  407. *\li events would have been posted to the task. This can be checked
  408. * with (find->options & DNS_ADBFIND_WANTEVENT).
  409. *
  410. * Ensures:
  411. *
  412. *\li The event was posted to the task.
  413. */
  414. void
  415. dns_adb_destroyfind(dns_adbfind_t **find);
  416. /*%<
  417. * Destroys the find reference.
  418. *
  419. * Note:
  420. *
  421. *\li This can only be called after the event was delivered for a
  422. * find. Additionally, the event MUST have been freed via
  423. * isc_event_free() BEFORE this function is called.
  424. *
  425. * Requires:
  426. *
  427. *\li 'find' != NULL and *find be valid dns_adbfind_t pointer.
  428. *
  429. * Ensures:
  430. *
  431. *\li No "address found" events will be posted to the originating task
  432. * after this function returns.
  433. */
  434. void
  435. dns_adb_dump(dns_adb_t *adb, FILE *f);
  436. /*%<
  437. * This function is only used for debugging. It will dump as much of the
  438. * state of the running system as possible.
  439. *
  440. * Requires:
  441. *
  442. *\li adb be valid.
  443. *
  444. *\li f != NULL, and is a file open for writing.
  445. */
  446. void
  447. dns_adb_dumpfind(dns_adbfind_t *find, FILE *f);
  448. /*%<
  449. * This function is only used for debugging. Dump the data associated
  450. * with a find.
  451. *
  452. * Requires:
  453. *
  454. *\li find is valid.
  455. *
  456. * \li f != NULL, and is a file open for writing.
  457. */
  458. isc_result_t
  459. dns_adb_marklame(dns_adb_t *adb, dns_adbaddrinfo_t *addr, dns_name_t *qname,
  460. dns_rdatatype_t type, isc_stdtime_t expire_time);
  461. /*%<
  462. * Mark the given address as lame for the <qname,qtype>. expire_time should
  463. * be set to the time when the entry should expire. That is, if it is to
  464. * expire 10 minutes in the future, it should set it to (now + 10 * 60).
  465. *
  466. * Requires:
  467. *
  468. *\li adb be valid.
  469. *
  470. *\li addr be valid.
  471. *
  472. *\li qname be the qname used in the dns_adb_createfind() call.
  473. *
  474. * Returns:
  475. *
  476. *\li #ISC_R_SUCCESS -- all is well.
  477. *\li #ISC_R_NOMEMORY -- could not mark address as lame.
  478. */
  479. /*
  480. * A reasonable default for RTT adjustments
  481. */
  482. #define DNS_ADB_RTTADJDEFAULT 7 /*%< default scale */
  483. #define DNS_ADB_RTTADJREPLACE 0 /*%< replace with our rtt */
  484. #define DNS_ADB_RTTADJAGE 10 /*%< age this rtt */
  485. void
  486. dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
  487. unsigned int rtt, unsigned int factor);
  488. /*%<
  489. * Mix the round trip time into the existing smoothed rtt.
  490. * The formula used
  491. * (where srtt is the existing rtt value, and rtt and factor are arguments to
  492. * this function):
  493. *
  494. *\code
  495. * new_srtt = (old_srtt / 10 * factor) + (rtt / 10 * (10 - factor));
  496. *\endcode
  497. *
  498. * XXXRTH Do we want to publish the formula? What if we want to change how
  499. * this works later on? Recommend/require that the units are
  500. * microseconds?
  501. *
  502. * Requires:
  503. *
  504. *\li adb be valid.
  505. *
  506. *\li addr be valid.
  507. *
  508. *\li 0 <= factor <= 10
  509. *
  510. * Note:
  511. *
  512. *\li The srtt in addr will be updated to reflect the new global
  513. * srtt value. This may include changes made by others.
  514. */
  515. void
  516. dns_adb_changeflags(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
  517. unsigned int bits, unsigned int mask);
  518. /*%
  519. * Change Flags.
  520. *
  521. * Set the flags as given by:
  522. *
  523. *\li newflags = (oldflags & ~mask) | (bits & mask);
  524. *
  525. * Requires:
  526. *
  527. *\li adb be valid.
  528. *
  529. *\li addr be valid.
  530. */
  531. isc_result_t
  532. dns_adb_findaddrinfo(dns_adb_t *adb, isc_sockaddr_t *sa,
  533. dns_adbaddrinfo_t **addrp, isc_stdtime_t now);
  534. /*%<
  535. * Return a dns_adbaddrinfo_t that is associated with address 'sa'.
  536. *
  537. * Requires:
  538. *
  539. *\li adb is valid.
  540. *
  541. *\li sa is valid.
  542. *
  543. *\li addrp != NULL && *addrp == NULL
  544. *
  545. * Returns:
  546. *\li #ISC_R_SUCCESS
  547. *\li #ISC_R_NOMEMORY
  548. *\li #ISC_R_SHUTTINGDOWN
  549. */
  550. void
  551. dns_adb_freeaddrinfo(dns_adb_t *adb, dns_adbaddrinfo_t **addrp);
  552. /*%<
  553. * Free a dns_adbaddrinfo_t allocated by dns_adb_findaddrinfo().
  554. *
  555. * Requires:
  556. *
  557. *\li adb is valid.
  558. *
  559. *\li *addrp is a valid dns_adbaddrinfo_t *.
  560. */
  561. void
  562. dns_adb_flush(dns_adb_t *adb);
  563. /*%<
  564. * Flushes all cached data from the adb.
  565. *
  566. * Requires:
  567. *\li adb is valid.
  568. */
  569. void
  570. dns_adb_setadbsize(dns_adb_t *adb, isc_uint32_t size);
  571. /*%<
  572. * Set a target memory size. If memory usage exceeds the target
  573. * size entries will be removed before they would have expired on
  574. * a random basis.
  575. *
  576. * If 'size' is 0 then memory usage is unlimited.
  577. *
  578. * Requires:
  579. *\li 'adb' is valid.
  580. */
  581. void
  582. dns_adb_flushname(dns_adb_t *adb, dns_name_t *name);
  583. /*%<
  584. * Flush 'name' from the adb cache.
  585. *
  586. * Requires:
  587. *\li 'adb' is valid.
  588. *\li 'name' is valid.
  589. */
  590. ISC_LANG_ENDDECLS
  591. #endif /* DNS_ADB_H */