adb.h 21.2 KB
Newer Older
Michael Graff's avatar
Michael Graff committed
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4 5
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
6
 * file, you can obtain one at https://mozilla.org/MPL/2.0/.
7 8 9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
Michael Graff's avatar
Michael Graff committed
10
 */
11

Michael Graff's avatar
Michael Graff committed
12
#ifndef DNS_ADB_H
13
#define DNS_ADB_H 1
Michael Graff's avatar
Michael Graff committed
14

15
/*****
16 17
***** Module Info
*****/
18

19
/*! \file dns/adb.h
20
 *\brief
21 22
 * DNS Address Database
 *
Bob Halley's avatar
Bob Halley committed
23 24 25
 * This module implements an address database (ADB) for mapping a name
 * to an isc_sockaddr_t. It also provides statistical information on
 * how good that address might be.
26
 *
27 28 29 30 31 32
 * A client will pass in a dns_name_t, and the ADB will walk through
 * the rdataset looking up addresses associated with the name.  If it
 * is found on the internal lists, a structure is filled in with the
 * address information and stats for found addresses.
 *
 * If the name cannot be found on the internal lists, a new entry will
Bob Halley's avatar
Bob Halley committed
33
 * be created for a name if all the information needed can be found
34 35
 * in the zone table or cache.  This new address will then be returned.
 *
36
 * If a request must be made to remote servers to satisfy a name lookup,
37 38 39 40 41 42
 * this module will start fetches to try to complete these addresses.  When
 * at least one more completes, an event is sent to the caller.  If none of
 * them resolve before the fetch times out, an event indicating this is
 * sent instead.
 *
 * Records are stored internally until a timer expires. The timer is the
43
 * smaller of the TTL or signature validity period.
44
 *
45 46 47
 * Lameness is stored per <qname,qtype> tuple, and this data hangs off each
 * address field.  When an address is marked lame for a given tuple the address
 * will not be returned to a caller.
48 49 50 51
 *
 *
 * MP:
 *
52
 *\li	The ADB takes care of all necessary locking.
53
 *
54
 *\li	Only the task which initiated the name lookup can cancel the lookup.
55 56 57 58
 *
 *
 * Security:
 *
59
 *\li	None, since all data stored is required to be pre-filtered.
60
 *	(Cache needs to be sane, fetches return bounds-checked and sanity-
Bob Halley's avatar
Bob Halley committed
61
 *       checked data, caller passes a good dns_name_t for the zone, etc)
62 63
 */

Michael Graff's avatar
Michael Graff committed
64
/***
Bob Halley's avatar
Bob Halley committed
65
 *** Imports
Michael Graff's avatar
Michael Graff committed
66 67
 ***/

68
#include <inttypes.h>
69
#include <stdbool.h>
70

Michael Graff's avatar
Michael Graff committed
71
#include <isc/lang.h>
Michael Graff's avatar
Michael Graff committed
72 73
#include <isc/magic.h>
#include <isc/mem.h>
74
#include <isc/sockaddr.h>
Michael Graff's avatar
Michael Graff committed
75

Bob Halley's avatar
Bob Halley committed
76
#include <dns/types.h>
Michael Graff's avatar
Michael Graff committed
77
#include <dns/view.h>
Michael Graff's avatar
Michael Graff committed
78 79

ISC_LANG_BEGINDECLS
80

Michael Graff's avatar
Michael Graff committed
81 82 83 84
/***
 *** Magic number checks
 ***/

Evan Hunt's avatar
Evan Hunt committed
85 86 87
#define DNS_ADBFIND_MAGIC	 ISC_MAGIC('a', 'd', 'b', 'H')
#define DNS_ADBFIND_VALID(x)	 ISC_MAGIC_VALID(x, DNS_ADBFIND_MAGIC)
#define DNS_ADBADDRINFO_MAGIC	 ISC_MAGIC('a', 'd', 'A', 'I')
88
#define DNS_ADBADDRINFO_VALID(x) ISC_MAGIC_VALID(x, DNS_ADBADDRINFO_MAGIC)
Michael Graff's avatar
Michael Graff committed
89

90 91 92 93
/***
 *** TYPES
 ***/

94
typedef struct dns_adbname dns_adbname_t;
95

Automatic Updater's avatar
Automatic Updater committed
96
/*!
97
 *\brief
Bob Halley's avatar
Bob Halley committed
98
 * Represents a lookup for a single name.
99 100 101 102
 *
 * On return, the client can safely use "list", and can reorder the list.
 * Items may not be _deleted_ from this list, however, or added to it
 * other than by using the dns_adb_*() API.
103
 */
104
struct dns_adbfind {
Michael Graff's avatar
Michael Graff committed
105
	/* Public */
106 107 108 109 110 111 112 113
	unsigned int	      magic;	      /*%< RO: magic */
	dns_adbaddrinfolist_t list;	      /*%< RO: list of addrs */
	unsigned int	      query_pending;  /*%< RO: partial list */
	unsigned int	      partial_result; /*%< RO: addrs missing */
	unsigned int	      options;	      /*%< RO: options */
	isc_result_t	      result_v4;      /*%< RO: v4 result */
	isc_result_t	      result_v6;      /*%< RO: v6 result */
	ISC_LINK(dns_adbfind_t) publink;      /*%< RW: client use */
Michael Graff's avatar
Michael Graff committed
114 115

	/* Private */
116 117 118 119 120 121 122 123
	isc_mutex_t    lock; /* locks all below */
	in_port_t      port;
	int	       name_bucket;
	unsigned int   flags;
	dns_adbname_t *adbname;
	dns_adb_t *    adb;
	isc_event_t    event;
	ISC_LINK(dns_adbfind_t) plink;
Michael Graff's avatar
Michael Graff committed
124
};
125

126 127 128 129 130 131 132 133 134 135 136 137 138 139
/*
 * _INET:
 * _INET6:
 *	return addresses of that type.
 *
 * _EMPTYEVENT:
 *	Only schedule an event if no addresses are known.
 *	Must set _WANTEVENT for this to be meaningful.
 *
 * _WANTEVENT:
 *	An event is desired.  Check this bit in the returned find to see
 *	if one will actually be generated.
 *
 * _AVOIDFETCHES:
Andreas Gustafsson's avatar
Andreas Gustafsson committed
140 141
 *	If set, fetches will not be generated unless no addresses are
 *	available in any of the address families requested.
142
 *
143 144 145
 * _STARTATZONE:
 *	Fetches will start using the closest zone data or use the root servers.
 *	This is useful for reestablishing glue that has expired.
146 147 148 149 150 151
 *
 * _GLUEOK:
 * _HINTOK:
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 *
Michael Graff's avatar
Michael Graff committed
152 153
 * _RETURNLAME:
 *	Return lame servers in a find, so that all addresses are returned.
154 155 156
 *
 * _LAMEPRUNED:
 *	At least one address was omitted from the list because it was lame.
157
 *	This bit will NEVER be set if _RETURNLAME is set in the createfind().
158
 */
159
/*% Return addresses of type INET. */
160
#define DNS_ADBFIND_INET 0x00000001
161
/*% Return addresses of type INET6. */
Evan Hunt's avatar
Evan Hunt committed
162
#define DNS_ADBFIND_INET6	0x00000002
163
#define DNS_ADBFIND_ADDRESSMASK 0x00000003
164 165 166 167
/*%
 *      Only schedule an event if no addresses are known.
 *      Must set _WANTEVENT for this to be meaningful.
 */
168
#define DNS_ADBFIND_EMPTYEVENT 0x00000004
169 170 171 172
/*%
 *	An event is desired.  Check this bit in the returned find to see
 *	if one will actually be generated.
 */
173
#define DNS_ADBFIND_WANTEVENT 0x00000008
174 175 176 177
/*%
 *	If set, fetches will not be generated unless no addresses are
 *	available in any of the address families requested.
 */
178
#define DNS_ADBFIND_AVOIDFETCHES 0x00000010
179 180 181 182
/*%
 *	Fetches will start using the closest zone data or use the root servers.
 *	This is useful for reestablishing glue that has expired.
 */
183
#define DNS_ADBFIND_STARTATZONE 0x00000020
184 185 186 187
/*%
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 */
188
#define DNS_ADBFIND_GLUEOK 0x00000040
189 190 191 192
/*%
 *	Glue or hints are ok.  These are used when matching names already
 *	in the adb, and when dns databases are searched.
 */
193
#define DNS_ADBFIND_HINTOK 0x00000080
194 195 196
/*%
 *	Return lame servers in a find, so that all addresses are returned.
 */
197
#define DNS_ADBFIND_RETURNLAME 0x00000100
198 199 200 201
/*%
 *      Only schedule an event if no addresses are known.
 *      Must set _WANTEVENT for this to be meaningful.
 */
202
#define DNS_ADBFIND_LAMEPRUNED 0x00000200
Evan Hunt's avatar
Evan Hunt committed
203 204 205 206
/*%
 *      The server's fetch quota is exceeded; it will be treated as
 *      lame for this query.
 */
207
#define DNS_ADBFIND_OVERQUOTA 0x00000400
208 209 210 211
/*%
 *	Don't perform a fetch even if there are no address records available.
 */
#define DNS_ADBFIND_NOFETCH 0x00000800
Michael Graff's avatar
Michael Graff committed
212

213
/*%
Michael Graff's avatar
Michael Graff committed
214 215 216
 * The answers to queries come back as a list of these.
 */
struct dns_adbaddrinfo {
217
	unsigned int magic; /*%< private */
Michael Graff's avatar
Michael Graff committed
218

219 220 221
	isc_sockaddr_t sockaddr; /*%< [rw] */
	unsigned int   srtt;	 /*%< [rw] microsecs */
	isc_dscp_t     dscp;
Evan Hunt's avatar
Evan Hunt committed
222

223 224 225
	unsigned int	flags; /*%< [rw] */
	dns_adbentry_t *entry; /*%< private */
	ISC_LINK(dns_adbaddrinfo_t) publink;
226 227
};

Automatic Updater's avatar
Automatic Updater committed
228
/*!<
229 230 231 232 233
 * The event sent to the caller task is just a plain old isc_event_t.  It
 * contains no data other than a simple status, passed in the "type" field
 * to indicate that another address resolved, or all partially resolved
 * addresses have failed to resolve.
 *
234
 * "sender" is the dns_adbfind_t used to issue this query.
235 236 237
 *
 * This is simply a standard event, with the "type" set to:
 *
238 239
 *\li	#DNS_EVENT_ADBMOREADDRESSES   -- another address resolved.
 *\li	#DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed,
240 241
 *					were canceled, or otherwise will
 *					not be usable.
242
 *\li	#DNS_EVENT_ADBCANCELED	     -- The request was canceled by a
243
 *					3rd party.
244
 *\li	#DNS_EVENT_ADBNAMEDELETED     -- The name was deleted, so this request
245 246 247
 *					was canceled.
 *
 * In each of these cases, the addresses returned by the initial call
248
 * to dns_adb_createfind() can still be used until they are no longer needed.
249 250 251
 */

/****
252 253
**** FUNCTIONS
****/
254

Michael Graff's avatar
Michael Graff committed
255
isc_result_t
Michael Graff's avatar
fix  
Michael Graff committed
256
dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr,
Michael Graff's avatar
Michael Graff committed
257
	       isc_taskmgr_t *taskmgr, dns_adb_t **newadb);
258
/*%<
259 260
 * Create a new ADB.
 *
Bob Halley's avatar
Bob Halley committed
261 262
 * Notes:
 *
263
 *\li	Generally, applications should not create an ADB directly, but
Bob Halley's avatar
Bob Halley committed
264 265
 *	should instead call dns_view_createresolver().
 *
266 267
 * Requires:
 *
268
 *\li	'mem' must be a valid memory context.
269
 *
270
 *\li	'view' be a pointer to a valid view.
Michael Graff's avatar
fix  
Michael Graff committed
271
 *
272
 *\li	'tmgr' be a pointer to a valid timer manager.
Michael Graff's avatar
Michael Graff committed
273
 *
274
 *\li	'taskmgr' be a pointer to a valid task manager.
Bob Halley's avatar
Bob Halley committed
275
 *
276
 *\li	'newadb' != NULL && '*newadb' == NULL.
Michael Graff's avatar
Michael Graff committed
277
 *
278 279
 * Returns:
 *
280 281
 *\li	#ISC_R_SUCCESS	after happiness.
 *\li	#ISC_R_NOMEMORY	after resource allocation failure.
282 283
 */

Mark Andrews's avatar
Mark Andrews committed
284 285
void
dns_adb_attach(dns_adb_t *adb, dns_adb_t **adbp);
286
/*%
Mark Andrews's avatar
Mark Andrews committed
287 288 289
 * Attach to an 'adb' to 'adbp'.
 *
 * Requires:
290 291
 *\li	'adb' to be a valid dns_adb_t, created via dns_adb_create().
 *\li	'adbp' to be a valid pointer to a *dns_adb_t which is initialized
Mark Andrews's avatar
Mark Andrews committed
292
 *	to NULL.
Mark Andrews's avatar
Mark Andrews committed
293 294
 */

Michael Graff's avatar
Michael Graff committed
295
void
296
dns_adb_detach(dns_adb_t **adb);
297
/*%
298 299 300 301
 * Delete the ADB. Sets *ADB to NULL. Cancels any outstanding requests.
 *
 * Requires:
 *
302
 *\li	'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via
303 304 305
 *	dns_adb_create().
 */

306 307
void
dns_adb_whenshutdown(dns_adb_t *adb, isc_task_t *task, isc_event_t **eventp);
308
/*%
309 310 311 312
 * Send '*eventp' to 'task' when 'adb' has shutdown.
 *
 * Requires:
 *
313
 *\li	'*adb' is a valid dns_adb_t.
314
 *
315
 *\li	eventp != NULL && *eventp is a valid event.
316 317 318
 *
 * Ensures:
 *
319
 *\li	*eventp == NULL
320
 *
321
 *\li	The event's sender field is set to the value of adb when the event
322 323 324 325 326
 *	is sent.
 */

void
dns_adb_shutdown(dns_adb_t *adb);
327
/*%<
328 329 330 331
 * Shutdown 'adb'.
 *
 * Requires:
 *
332
 * \li	'*adb' is a valid dns_adb_t.
333
 */
334

Michael Graff's avatar
Michael Graff committed
335
isc_result_t
336
dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,
337
		   void *arg, const dns_name_t *name, const dns_name_t *qname,
338
		   dns_rdatatype_t qtype, unsigned int options,
339
		   isc_stdtime_t now, dns_name_t *target, in_port_t port,
340
		   unsigned int depth, isc_counter_t *qc, dns_adbfind_t **find);
341
/*%<
Michael Graff's avatar
Michael Graff committed
342 343
 * Main interface for clients. The adb will look up the name given in
 * "name" and will build up a list of found addresses, and perhaps start
344 345 346 347
 * internal fetches to resolve names that are unknown currently.
 *
 * If other addresses resolve after this call completes, an event will
 * be sent to the <task, taskaction, arg> with the sender of that event
348
 * set to a pointer to the dns_adbfind_t returned by this function.
349
 *
Michael Graff's avatar
Michael Graff committed
350
 * If no events will be generated, the *find->result_v4 and/or result_v6
351
 * members may be examined for address lookup status.  The usual #ISC_R_SUCCESS,
352
 * #ISC_R_FAILURE, #DNS_R_NXDOMAIN, and #DNS_R_NXRRSET are returned, along with
353
 * #ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values.  In this
Michael Graff's avatar
Michael Graff committed
354 355 356 357 358
 * latter case, retrying may produce more addresses.
 *
 * If events will be returned, the result_v[46] members are only valid
 * when that event is actually returned.
 *
359 360 361 362 363 364 365 366 367
 * The list of addresses returned is unordered.  The caller must impose
 * any ordering required.  The list will not contain "known bad" addresses,
 * however.  For instance, it will not return hosts that are known to be
 * lame for the zone in question.
 *
 * The caller cannot (directly) modify the contents of the address list's
 * fields other than the "link" field.  All values can be read at any
 * time, however.
 *
Michael Graff's avatar
Michael Graff committed
368 369 370 371 372
 * The "now" parameter is used only for determining which entries that
 * have a specific time to live or expire time should be removed from
 * the running database.  If specified as zero, the current time will
 * be retrieved and used.
 *
373 374 375 376
 * If 'target' is not NULL and 'name' is an alias (i.e. the name is
 * CNAME'd or DNAME'd to another name), then 'target' will be updated with
 * the domain name that 'name' is aliased to.
 *
377 378 379 380
 * All addresses returned will have the sockaddr's port set to 'port.'
 * The caller may change them directly in the dns_adbaddrinfo_t since
 * they are copies of the internal address only.
 *
Bob Halley's avatar
Bob Halley committed
381 382 383
 * XXXMLG  Document options, especially the flags which control how
 *         events are sent.
 *
384 385
 * Requires:
 *
386
 *\li	*adb be a valid isc_adb_t object.
387
 *
388
 *\li	If events are to be sent, *task be a valid task,
Michael Graff's avatar
Michael Graff committed
389
 *	and isc_taskaction_t != NULL.
390
 *
391
 *\li	*name is a valid dns_name_t.
392
 *
393
 *\li	qname != NULL and *qname be a valid dns_name_t.
394
 *
395
 *\li	target == NULL or target is a valid name with a buffer.
396
 *
397
 *\li	find != NULL && *find == NULL.
398 399 400
 *
 * Returns:
 *
401
 *\li	#ISC_R_SUCCESS	Addresses might have been returned, and events will be
402
 *			delivered for unresolved addresses.
403
 *\li	#ISC_R_NOMORE	Addresses might have been returned, but no events
Michael Graff's avatar
Michael Graff committed
404 405
 *			will ever be posted for this context.  This is only
 *			returned if task != NULL.
406 407
 *\li	#ISC_R_NOMEMORY	insufficient resources
 *\li	#DNS_R_ALIAS	'name' is an alias for another name.
408
 *
Michael Graff's avatar
Michael Graff committed
409 410
 * Calls, and returns error codes from:
 *
411
 *\li	isc_stdtime_get()
Michael Graff's avatar
Michael Graff committed
412
 *
Michael Graff's avatar
Michael Graff committed
413
 * Notes:
414
 *
415
 *\li	No internal reference to "name" exists after this function
416 417 418
 *	returns.
 */

Michael Graff's avatar
Michael Graff committed
419
void
420
dns_adb_cancelfind(dns_adbfind_t *find);
421
/*%<
422 423
 * Cancels the find, and sends the event off to the caller.
 *
424
 * It is an error to call dns_adb_cancelfind() on a find where
425
 * no event is wanted, or will ever be sent.
426
 *
Bob Halley's avatar
Bob Halley committed
427 428
 * Note:
 *
429
 *\li	It is possible that the real completion event was posted just
Bob Halley's avatar
Bob Halley committed
430 431 432 433 434
 *	before the dns_adb_cancelfind() call was made.  In this case,
 *	dns_adb_cancelfind() will do nothing.  The event callback needs
 *	to be prepared to find this situation (i.e. result is valid but
 *	the caller expects it to be canceled).
 *
435 436
 * Requires:
 *
437
 *\li	'find' be a valid dns_adbfind_t pointer.
438
 *
439
 *\li	events would have been posted to the task.  This can be checked
440
 *	with (find->options & DNS_ADBFIND_WANTEVENT).
441 442 443
 *
 * Ensures:
 *
444
 *\li	The event was posted to the task.
445 446 447
 */

void
448
dns_adb_destroyfind(dns_adbfind_t **find);
449
/*%<
450
 * Destroys the find reference.
451
 *
Bob Halley's avatar
Bob Halley committed
452 453
 * Note:
 *
454
 *\li	This can only be called after the event was delivered for a
Bob Halley's avatar
Bob Halley committed
455 456 457
 *	find.  Additionally, the event MUST have been freed via
 *	isc_event_free() BEFORE this function is called.
 *
458
 * Requires:
459
 *
460
 *\li	'find' != NULL and *find be valid dns_adbfind_t pointer.
461 462 463
 *
 * Ensures:
 *
464
 *\li	No "address found" events will be posted to the originating task
465 466 467
 *	after this function returns.
 */

Michael Graff's avatar
Michael Graff committed
468 469
void
dns_adb_dump(dns_adb_t *adb, FILE *f);
470
/*%<
Bob Halley's avatar
Bob Halley committed
471
 * This function is only used for debugging.  It will dump as much of the
Michael Graff's avatar
Michael Graff committed
472 473 474 475
 * state of the running system as possible.
 *
 * Requires:
 *
476
 *\li	adb be valid.
Michael Graff's avatar
Michael Graff committed
477
 *
478
 *\li	f != NULL, and is a file open for writing.
Michael Graff's avatar
Michael Graff committed
479 480
 */

481
void
482
dns_adb_dumpfind(dns_adbfind_t *find, FILE *f);
483
/*%<
Bob Halley's avatar
Bob Halley committed
484 485
 * This function is only used for debugging.  Dump the data associated
 * with a find.
486 487 488
 *
 * Requires:
 *
489
 *\li	find is valid.
490
 *
491
 * \li	f != NULL, and is a file open for writing.
492 493
 */

494
isc_result_t
495 496 497
dns_adb_marklame(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
		 const dns_name_t *qname, dns_rdatatype_t type,
		 isc_stdtime_t expire_time);
498
/*%<
499
 * Mark the given address as lame for the <qname,qtype>.  expire_time should
Michael Graff's avatar
Michael Graff committed
500 501
 * be set to the time when the entry should expire.  That is, if it is to
 * expire 10 minutes in the future, it should set it to (now + 10 * 60).
502 503 504
 *
 * Requires:
 *
505
 *\li	adb be valid.
506
 *
507
 *\li	addr be valid.
508
 *
509
 *\li	qname be the qname used in the dns_adb_createfind() call.
510 511 512
 *
 * Returns:
 *
513 514
 *\li	#ISC_R_SUCCESS		-- all is well.
 *\li	#ISC_R_NOMEMORY		-- could not mark address as lame.
515
 */
516

517
/*
518 519 520 521 522 523
 * Reasonable defaults for RTT adjustments
 *
 * (Note: these values function both as scaling factors and as
 * indicators of the type of RTT adjustment operation taking place.
 * Adjusting the scaling factors is fine, as long as they all remain
 * unique values.)
524
 */
Evan Hunt's avatar
Evan Hunt committed
525 526 527
#define DNS_ADB_RTTADJDEFAULT 7	 /*%< default scale */
#define DNS_ADB_RTTADJREPLACE 0	 /*%< replace with our rtt */
#define DNS_ADB_RTTADJAGE     10 /*%< age this rtt */
528

529
void
530 531
dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int rtt,
		   unsigned int factor);
532
/*%<
Automatic Updater's avatar
Automatic Updater committed
533
 * Mix the round trip time into the existing smoothed rtt.
Bob Halley's avatar
Bob Halley committed
534
 *
535 536
 * Requires:
 *
537
 *\li	adb be valid.
538
 *
539
 *\li	addr be valid.
540
 *
541
 *\li	0 <= factor <= 10
542
 *
543
 * Note:
544
 *
545
 *\li	The srtt in addr will be updated to reflect the new global
546 547 548
 *	srtt value.  This may include changes made by others.
 */

549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566
void
dns_adb_agesrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr, isc_stdtime_t now);
/*
 * dns_adb_agesrtt is equivalent to dns_adb_adjustsrtt with factor
 * equal to DNS_ADB_RTTADJAGE and the current time passed in.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 *
 * Note:
 *
 *\li	The srtt in addr will be updated to reflect the new global
 *	srtt value.  This may include changes made by others.
 */

Michael Graff's avatar
Michael Graff committed
567
void
568 569
dns_adb_changeflags(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int bits,
		    unsigned int mask);
570 571 572
/*%
 * Change Flags.
 *
Michael Graff's avatar
Michael Graff committed
573 574
 * Set the flags as given by:
 *
575
 *\li	newflags = (oldflags & ~mask) | (bits & mask);
Michael Graff's avatar
Michael Graff committed
576 577 578
 *
 * Requires:
 *
579
 *\li	adb be valid.
Michael Graff's avatar
Michael Graff committed
580
 *
581
 *\li	addr be valid.
Michael Graff's avatar
Michael Graff committed
582
 */
583

584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633
void
dns_adb_setudpsize(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int size);
/*%
 * Update seen UDP response size.  The largest seen will be returned by
 * dns_adb_getudpsize().
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

unsigned int
dns_adb_getudpsize(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Return the largest seen UDP response size.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

void
dns_adb_plainresponse(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Record a successful plain DNS response.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

void
dns_adb_timeout(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Record a plain DNS UDP query failed.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

void
634
dns_adb_ednsto(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
635
/*%
636
 * Record a EDNS UDP query failed.
637 638 639 640 641 642 643 644
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

645
isc_result_t
646
dns_adb_findaddrinfo(dns_adb_t *adb, const isc_sockaddr_t *sa,
647
		     dns_adbaddrinfo_t **addrp, isc_stdtime_t now);
648
/*%<
649 650 651 652
 * Return a dns_adbaddrinfo_t that is associated with address 'sa'.
 *
 * Requires:
 *
653
 *\li	adb is valid.
654
 *
655
 *\li	sa is valid.
656
 *
657
 *\li	addrp != NULL && *addrp == NULL
658 659
 *
 * Returns:
660 661 662
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
 *\li	#ISC_R_SHUTTINGDOWN
663 664 665 666
 */

void
dns_adb_freeaddrinfo(dns_adb_t *adb, dns_adbaddrinfo_t **addrp);
667
/*%<
668 669 670 671
 * Free a dns_adbaddrinfo_t allocated by dns_adb_findaddrinfo().
 *
 * Requires:
 *
672
 *\li	adb is valid.
673
 *
674
 *\li	*addrp is a valid dns_adbaddrinfo_t *.
675 676
 */

677 678
void
dns_adb_flush(dns_adb_t *adb);
679
/*%<
680 681 682
 * Flushes all cached data from the adb.
 *
 * Requires:
683
 *\li 	adb is valid.
684 685
 */

686
void
687
dns_adb_setadbsize(dns_adb_t *adb, size_t size);
688
/*%<
689 690 691 692 693 694 695
 * Set a target memory size.  If memory usage exceeds the target
 * size entries will be removed before they would have expired on
 * a random basis.
 *
 * If 'size' is 0 then memory usage is unlimited.
 *
 * Requires:
696
 *\li	'adb' is valid.
697 698
 */

699
void
700
dns_adb_flushname(dns_adb_t *adb, const dns_name_t *name);
701
/*%<
702
 * Flush 'name' from the adb cache.
Automatic Updater's avatar
Automatic Updater committed
703
 *
704
 * Requires:
705 706
 *\li	'adb' is valid.
 *\li	'name' is valid.
707 708
 */

709
void
710
dns_adb_flushnames(dns_adb_t *adb, const dns_name_t *name);
711 712 713 714 715 716 717 718
/*%<
 * Flush 'name' and all subdomains from the adb cache.
 *
 * Requires:
 *\li	'adb' is valid.
 *\li	'name' is valid.
 */

719
void
720
dns_adb_setcookie(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
721
		  const unsigned char *cookie, size_t len);
722
/*%<
723
 * Record the COOKIE associated with this address.  If
724
 * cookie is NULL or len is zero the recorded COOKIE is cleared.
725 726 727 728 729 730 731
 *
 * Requires:
 *\li	'adb' is valid.
 *\li	'addr' is valid.
 */

size_t
732
dns_adb_getcookie(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
733
		  unsigned char *cookie, size_t len);
734
/*
735
 * Retrieve the saved COOKIE value and store it in 'cookie' which has
736
 * size 'len'.
737 738 739 740 741 742
 *
 * Requires:
 *\li	'adb' is valid.
 *\li	'addr' is valid.
 *
 * Returns:
743
 *	The size of the cookie or zero if it doesn't fit in the buffer
744 745
 *	or it doesn't exist.
 */
746

Evan Hunt's avatar
Evan Hunt committed
747
void
748 749
dns_adb_setquota(dns_adb_t *adb, uint32_t quota, uint32_t freq, double low,
		 double high, double discount);
Evan Hunt's avatar
Evan Hunt committed
750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778
/*%<
 * Set the baseline ADB quota, and configure parameters for the
 * quota adjustment algorithm.
 *
 * If the number of fetches currently waiting for responses from this
 * address exceeds the current quota, then additional fetches are spilled.
 *
 * 'quota' is the highest permissible quota; it will adjust itself
 * downward in response to detected congestion.
 *
 * After every 'freq' fetches have either completed or timed out, an
 * exponentially weighted moving average of the ratio of timeouts
 * to responses is calculated.  If the EWMA goes above a 'high'
 * threshold, then the quota is adjusted down one step; if it drops
 * below a 'low' threshold, then the quota is adjusted back up one
 * step.
 *
 * The quota adjustment is based on the function (1 / 1 + (n/10)^(3/2)),
 * for values of n from 0 to 99.  It starts at 100% of the baseline
 * quota, and descends after 100 steps to 2%.
 *
 * 'discount' represents the discount rate of the moving average. Higher
 * values cause older values to be discounted sooner, providing a faster
 * response to changes in the timeout ratio.
 *
 * Requires:
 *\li	'adb' is valid.
 */

779
bool
Evan Hunt's avatar
Evan Hunt committed
780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804
dns_adbentry_overquota(dns_adbentry_t *entry);
/*%<
 * Returns true if the specified ADB has too many active fetches.
 *
 * Requires:
 *\li	'entry' is valid.
 */

void
dns_adb_beginudpfetch(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
void
dns_adb_endudpfetch(dns_adb_t *adb, dns_adbaddrinfo_t *addr);
/*%
 * Begin/end a UDP fetch on a particular address.
 *
 * These functions increment or decrement the fetch counter for
 * the ADB entry so that the fetch quota can be enforced.
 *
 * Requires:
 *
 *\li	adb be valid.
 *
 *\li	addr be valid.
 */

Michael Graff's avatar
Michael Graff committed
805 806
ISC_LANG_ENDDECLS

Michael Graff's avatar
Michael Graff committed
807
#endif /* DNS_ADB_H */