view.h 25.9 KB
Newer Older
Bob Halley's avatar
add  
Bob Halley committed
1
/*
Automatic Updater's avatar
Automatic Updater committed
2
 * Copyright (C) 2004-2010  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2003  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Bob Halley's avatar
add  
Bob Halley committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
add  
Bob Halley committed
16 17
 */

18
/* $Id: view.h,v 1.126 2010/08/11 18:14:19 each Exp $ */
David Lawrence's avatar
David Lawrence committed
19

Bob Halley's avatar
add  
Bob Halley committed
20 21 22 23 24 25 26
#ifndef DNS_VIEW_H
#define DNS_VIEW_H 1

/*****
 ***** Module Info
 *****/

27
/*! \file dns/view.h
28
 * \brief
Bob Halley's avatar
add  
Bob Halley committed
29 30
 * DNS View
 *
Bob Halley's avatar
Bob Halley committed
31 32 33 34 35 36 37 38 39 40 41 42
 * A "view" is a DNS namespace, together with an optional resolver and a
 * forwarding policy.  A "DNS namespace" is a (possibly empty) set of
 * authoritative zones together with an optional cache and optional
 * "hints" information.
 *
 * Views start out "unfrozen".  In this state, core attributes like
 * the cache, set of zones, and forwarding policy may be set.  While
 * "unfrozen", the caller (e.g. nameserver configuration loading
 * code), must ensure exclusive access to the view.  When the view is
 * "frozen", the core attributes become immutable, and the view module
 * will ensure synchronization.  Freezing allows the view's core attributes
 * to be accessed without locking.
Bob Halley's avatar
add  
Bob Halley committed
43 44
 *
 * MP:
45
 *\li	Before the view is frozen, the caller must ensure synchronization.
Bob Halley's avatar
Bob Halley committed
46
 *
47
 *\li	After the view is frozen, the module guarantees appropriate
Bob Halley's avatar
Bob Halley committed
48
 *	synchronization of any data structures it creates and manipulates.
Bob Halley's avatar
add  
Bob Halley committed
49 50
 *
 * Reliability:
51
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
52 53
 *
 * Resources:
54
 *\li	TBS
Bob Halley's avatar
add  
Bob Halley committed
55 56
 *
 * Security:
57
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
58 59
 *
 * Standards:
60
 *\li	None.
61
 */
Bob Halley's avatar
add  
Bob Halley committed
62

Brian Wellington's avatar
Brian Wellington committed
63 64
#include <stdio.h>

Bob Halley's avatar
add  
Bob Halley committed
65
#include <isc/lang.h>
66
#include <isc/magic.h>
Bob Halley's avatar
add  
Bob Halley committed
67
#include <isc/event.h>
Brian Wellington's avatar
Brian Wellington committed
68
#include <isc/mutex.h>
69
#include <isc/net.h>
70
#include <isc/refcount.h>
71
#include <isc/rwlock.h>
Bob Halley's avatar
Bob Halley committed
72
#include <isc/stdtime.h>
Bob Halley's avatar
add  
Bob Halley committed
73

74
#include <dns/acl.h>
75
#include <dns/fixedname.h>
76
#include <dns/rdatastruct.h>
Bob Halley's avatar
add  
Bob Halley committed
77 78 79 80 81 82 83 84 85 86
#include <dns/types.h>

ISC_LANG_BEGINDECLS

struct dns_view {
	/* Unlocked. */
	unsigned int			magic;
	isc_mem_t *			mctx;
	dns_rdataclass_t		rdclass;
	char *				name;
87
	dns_zt_t *			zonetable;
88
	dns_dlzdb_t *			dlzdatabase;
Bob Halley's avatar
add  
Bob Halley committed
89
	dns_resolver_t *		resolver;
Bob Halley's avatar
add adb  
Bob Halley committed
90
	dns_adb_t *			adb;
Mark Andrews's avatar
Mark Andrews committed
91
	dns_requestmgr_t *		requestmgr;
92
	dns_acache_t *			acache;
93
	dns_cache_t *			cache;
Bob Halley's avatar
Bob Halley committed
94
	dns_db_t *			cachedb;
Bob Halley's avatar
Bob Halley committed
95
	dns_db_t *			hints;
96 97 98 99 100 101 102

	/*
	 * security roots.
	 * internal use only; access via * dns_view_getsecroots()
	 */
	dns_keytable_t *		secroots_priv;

Bob Halley's avatar
add  
Bob Halley committed
103
	isc_mutex_t			lock;
Bob Halley's avatar
Bob Halley committed
104
	isc_boolean_t			frozen;
105 106 107
	isc_task_t *			task;
	isc_event_t			resevent;
	isc_event_t			adbevent;
Mark Andrews's avatar
Mark Andrews committed
108
	isc_event_t			reqevent;
109
	isc_stats_t *			resstats;
110
	dns_stats_t *			resquerystats;
111
	isc_boolean_t			cacheshared;
112

113
	/* Configurable data. */
Brian Wellington's avatar
Brian Wellington committed
114 115
	dns_tsig_keyring_t *		statickeys;
	dns_tsig_keyring_t *		dynamickeys;
116
	dns_peerlist_t *		peers;
117
	dns_order_t *			order;
118
	dns_fwdtable_t *		fwdtable;
119 120
	isc_boolean_t			recursion;
	isc_boolean_t			auth_nxdomain;
Michael Graff's avatar
 
Michael Graff committed
121 122
	isc_boolean_t			additionalfromcache;
	isc_boolean_t			additionalfromauth;
Bob Halley's avatar
Bob Halley committed
123
	isc_boolean_t			minimalresponses;
124
	isc_boolean_t			enablednssec;
125
	isc_boolean_t			enablevalidation;
126
	isc_boolean_t			acceptexpired;
127
	dns_transfer_format_t		transfer_format;
128
	dns_acl_t *			queryacl;
129
	dns_acl_t *			queryonacl;
130
	dns_acl_t *			recursionacl;
131
	dns_acl_t *			recursiononacl;
132
	dns_acl_t *			sortlist;
133 134 135 136
	dns_acl_t *			notifyacl;
	dns_acl_t *			transferacl;
	dns_acl_t *			updateacl;
	dns_acl_t *			upfwdacl;
137 138 139 140
	dns_acl_t *			denyansweracl;
	dns_rbt_t *			answeracl_exclude;
	dns_rbt_t *			denyanswernames;
	dns_rbt_t *			answernames_exclude;
141 142
	isc_boolean_t			requestixfr;
	isc_boolean_t			provideixfr;
143
	isc_boolean_t			requestnsid;
144 145
	dns_ttl_t			maxcachettl;
	dns_ttl_t			maxncachettl;
146
	in_port_t			dstport;
147
	dns_aclenv_t			aclenv;
148
	dns_rdatatype_t			preferred_glue;
149
	isc_boolean_t			flush;
150
	dns_namelist_t *		delonly;
151
	isc_boolean_t			rootdelonly;
Mark Andrews's avatar
Mark Andrews committed
152
	dns_namelist_t *		rootexclude;
153
	isc_boolean_t			checknames;
154 155
	dns_name_t *			dlv;
	dns_fixedname_t			dlv_fixed;
156
	isc_uint16_t			maxudp;
157
	dns_v4_aaaa_t			v4_aaaa;
158
	dns_acl_t *			v4_aaaa_acl;
159

160 161 162 163 164
	/*
	 * Configurable data for server use only,
	 * locked by server configuration lock.
	 */
	dns_acl_t *			matchclients;
165 166
	dns_acl_t *			matchdestinations;
	isc_boolean_t			matchrecursiveonly;
167

168 169 170
	/* Locked by themselves. */
	isc_refcount_t			references;

Bob Halley's avatar
add  
Bob Halley committed
171
	/* Locked by lock. */
172
	unsigned int			weakrefs;
173
	unsigned int			attributes;
Bob Halley's avatar
add  
Bob Halley committed
174 175
	/* Under owner's locking control. */
	ISC_LINK(struct dns_view)	link;
176
	dns_viewlist_t *		viewlist;
Automatic Updater's avatar
Automatic Updater committed
177

178
	dns_zone_t *			managed_keys;
179 180 181 182 183 184 185 186

#ifdef BIND9
	/* File in which to store configuration for newly added zones */
	char *				new_zone_file;

	void *				new_zone_config;
	void				(*cfg_destroy)(void **);
#endif
Bob Halley's avatar
add  
Bob Halley committed
187 188
};

189
#define DNS_VIEW_MAGIC			ISC_MAGIC('V','i','e','w')
190
#define DNS_VIEW_VALID(view)		ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
Bob Halley's avatar
add  
Bob Halley committed
191

192 193
#define DNS_VIEWATTR_RESSHUTDOWN	0x01
#define DNS_VIEWATTR_ADBSHUTDOWN	0x02
Mark Andrews's avatar
Mark Andrews committed
194
#define DNS_VIEWATTR_REQSHUTDOWN	0x04
195

Bob Halley's avatar
add  
Bob Halley committed
196
isc_result_t
197 198
dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
		const char *name, dns_view_t **viewp);
199
/*%<
Bob Halley's avatar
Bob Halley committed
200 201 202 203
 * Create a view.
 *
 * Notes:
 *
204
 *\li	The newly created view has no cache, no resolver, and an empty
Bob Halley's avatar
Bob Halley committed
205 206 207 208
 *	zone table.  The view is not frozen.
 *
 * Requires:
 *
209
 *\li	'mctx' is a valid memory context.
Bob Halley's avatar
Bob Halley committed
210
 *
211
 *\li	'rdclass' is a valid class.
Bob Halley's avatar
Bob Halley committed
212
 *
213
 *\li	'name' is a valid C string.
Bob Halley's avatar
Bob Halley committed
214
 *
215
 *\li	viewp != NULL && *viewp == NULL
Bob Halley's avatar
Bob Halley committed
216 217 218
 *
 * Returns:
 *
219 220
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
221
 *
222
 *\li	Other errors are possible.
Bob Halley's avatar
Bob Halley committed
223
 */
Bob Halley's avatar
add  
Bob Halley committed
224 225 226

void
dns_view_attach(dns_view_t *source, dns_view_t **targetp);
227
/*%<
Bob Halley's avatar
Bob Halley committed
228 229 230 231
 * Attach '*targetp' to 'source'.
 *
 * Requires:
 *
232
 *\li	'source' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
233
 *
234
 *\li	'targetp' points to a NULL dns_view_t *.
Bob Halley's avatar
Bob Halley committed
235 236 237
 *
 * Ensures:
 *
238
 *\li	*targetp is attached to source.
239
 *
240
 *\li	While *targetp is attached, the view will not shut down.
Bob Halley's avatar
Bob Halley committed
241
 */
Bob Halley's avatar
add  
Bob Halley committed
242 243 244

void
dns_view_detach(dns_view_t **viewp);
245
/*%<
Bob Halley's avatar
Bob Halley committed
246 247 248 249
 * Detach '*viewp' from its view.
 *
 * Requires:
 *
250
 *\li	'viewp' points to a valid dns_view_t *
Bob Halley's avatar
Bob Halley committed
251 252 253
 *
 * Ensures:
 *
254
 *\li	*viewp is NULL.
255 256
 */

257 258
void
dns_view_flushanddetach(dns_view_t **viewp);
259
/*%<
260
 * Detach '*viewp' from its view.  If this was the last reference
Francis Dupont's avatar
Francis Dupont committed
261
 * uncommitted changed in zones will be flushed to disk.
262 263 264
 *
 * Requires:
 *
265
 *\li	'viewp' points to a valid dns_view_t *
266 267 268
 *
 * Ensures:
 *
269
 *\li	*viewp is NULL.
270 271
 */

272 273
void
dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
274
/*%<
275 276 277 278
 * Weakly attach '*targetp' to 'source'.
 *
 * Requires:
 *
279
 *\li	'source' is a valid, frozen view.
280
 *
281
 *\li	'targetp' points to a NULL dns_view_t *.
282 283
 *
 * Ensures:
Bob Halley's avatar
Bob Halley committed
284
 *
285
 *\li	*targetp is attached to source.
286
 *
287
 * \li	While *targetp is attached, the view will not be freed.
288 289 290 291
 */

void
dns_view_weakdetach(dns_view_t **targetp);
292
/*%<
293
 * Detach '*viewp' from its view.
Bob Halley's avatar
Bob Halley committed
294
 *
295 296
 * Requires:
 *
297
 *\li	'viewp' points to a valid dns_view_t *.
298 299 300
 *
 * Ensures:
 *
301
 *\li	*viewp is NULL.
Bob Halley's avatar
Bob Halley committed
302
 */
Bob Halley's avatar
add  
Bob Halley committed
303

Bob Halley's avatar
Bob Halley committed
304
isc_result_t
Bob Halley's avatar
Bob Halley committed
305 306 307 308
dns_view_createresolver(dns_view_t *view,
			isc_taskmgr_t *taskmgr, unsigned int ntasks,
			isc_socketmgr_t *socketmgr,
			isc_timermgr_t *timermgr,
309
			unsigned int options,
310
			dns_dispatchmgr_t *dispatchmgr,
311 312
			dns_dispatch_t *dispatchv4,
			dns_dispatch_t *dispatchv6);
313
/*%<
Bob Halley's avatar
add adb  
Bob Halley committed
314
 * Create a resolver and address database for the view.
Bob Halley's avatar
Bob Halley committed
315 316 317
 *
 * Requires:
 *
318
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
319
 *
320
 *\li	'view' does not have a resolver already.
Bob Halley's avatar
Bob Halley committed
321
 *
322
 *\li	The requirements of dns_resolver_create() apply to 'taskmgr',
323 324
 *	'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
 *	'dispatchv6'.
Bob Halley's avatar
Bob Halley committed
325 326
 *
 * Returns:
Bob Halley's avatar
Bob Halley committed
327
 *
328
 *\li   	#ISC_R_SUCCESS
Bob Halley's avatar
Bob Halley committed
329
 *
330
 *\li	Any error that dns_resolver_create() can return.
Bob Halley's avatar
Bob Halley committed
331
 */
332 333

void
334
dns_view_setcache(dns_view_t *view, dns_cache_t *cache);
335 336
void
dns_view_setcache2(dns_view_t *view, dns_cache_t *cache, isc_boolean_t shared);
337
/*%<
338 339 340
 * Set the view's cache database.  If 'shared' is true, this means the cache
 * is created by another view and is shared with that view.  dns_view_setcache()
 * is a backward compatible version equivalent to setcache2(..., ISC_FALSE).
Bob Halley's avatar
Bob Halley committed
341 342 343
 *
 * Requires:
 *
344
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
345
 *
346
 *\li	'cache' is a valid cache.
Bob Halley's avatar
Bob Halley committed
347 348 349
 *
 * Ensures:
 *
350
 * \li    	The cache of 'view' is 'cached.
Bob Halley's avatar
add adb  
Bob Halley committed
351
 *
352
 *\li	If this is not the first call to dns_view_setcache() for this
353
 *	view, then previously set cache is detached.
Bob Halley's avatar
Bob Halley committed
354
 */
355

Bob Halley's avatar
Bob Halley committed
356 357
void
dns_view_sethints(dns_view_t *view, dns_db_t *hints);
358
/*%<
Bob Halley's avatar
Bob Halley committed
359 360 361 362
 * Set the view's hints database.
 *
 * Requires:
 *
363
 *\li	'view' is a valid, unfrozen view, whose hints database has not been
Bob Halley's avatar
Bob Halley committed
364 365
 *	set.
 *
366
 *\li	'hints' is a valid zone database.
Bob Halley's avatar
Bob Halley committed
367 368 369
 *
 * Ensures:
 *
370
 * \li    	The hints database of 'view' is 'hints'.
Bob Halley's avatar
Bob Halley committed
371 372
 */

Brian Wellington's avatar
Brian Wellington committed
373 374
void
dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
375
/*%<
Brian Wellington's avatar
Brian Wellington committed
376 377 378 379
 * Set the view's static TSIG keys
 *
 * Requires:
 *
380
 *   \li   'view' is a valid, unfrozen view, whose static TSIG keyring has not
Brian Wellington's avatar
Brian Wellington committed
381 382
 *	been set.
 *
383
 *\li      'ring' is a valid TSIG keyring
Brian Wellington's avatar
Brian Wellington committed
384 385 386
 *
 * Ensures:
 *
387
 *\li      The static TSIG keyring of 'view' is 'ring'.
Brian Wellington's avatar
Brian Wellington committed
388 389
 */

390 391
void
dns_view_setdstport(dns_view_t *view, in_port_t dstport);
392
/*%<
393 394 395 396 397 398
 * Set the view's destination port.  This is the port to
 * which outgoing queries are sent.  The default is 53,
 * the standard DNS port.
 *
 * Requires:
 *
399
 *\li      'view' is a valid view.
400
 *
401
 *\li      'dstport' is a valid TCP/UDP port number.
402 403
 *
 * Ensures:
Francis Dupont's avatar
Francis Dupont committed
404
 *\li	External name servers will be assumed to be listening
405 406 407 408 409
 *	on 'dstport'.  For servers whose address has already
 *	obtained obtained at the time of the call, the view may
 *	continue to use the previously set port until the address
 *	times out from the view's address database.
 */
Brian Wellington's avatar
Brian Wellington committed
410 411


412
isc_result_t
413
dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
414
/*%<
415
 * Add zone 'zone' to 'view'.
Bob Halley's avatar
Bob Halley committed
416 417 418
 *
 * Requires:
 *
419
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
420
 *
421
 *\li	'zone' is a valid zone.
422
 */
423 424 425

void
dns_view_freeze(dns_view_t *view);
426
/*%<
427
 * Freeze view.  No changes can be made to view configuration while frozen.
Bob Halley's avatar
Bob Halley committed
428 429 430
 *
 * Requires:
 *
431
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
432 433 434
 *
 * Ensures:
 *
435
 *\li	'view' is frozen.
Bob Halley's avatar
Bob Halley committed
436 437
 */

438 439 440 441 442 443 444 445 446 447 448 449 450 451 452
void
dns_view_thaw(dns_view_t *view);
/*%<
 * Thaw view.  This allows zones to be added or removed at runtime.  This is
 * NOT thread-safe; the caller MUST have run isc_task_exclusive() prior to
 * thawing the view.
 *
 * Requires:
 *
 *\li	'view' is a valid, frozen view.
 *
 * Ensures:
 *
 *\li	'view' is no longer frozen.
 */
Bob Halley's avatar
Bob Halley committed
453 454
isc_result_t
dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
455 456
	      isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints,
	      dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
Bob Halley's avatar
Bob Halley committed
457
	      dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
458
/*%<
459 460 461 462 463
 * Find an rdataset whose owner name is 'name', and whose type is
 * 'type'.
 *
 * Notes:
 *
464 465
 *\li	See the description of dns_db_find() for information about 'options'.
 *	If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name'
466 467
 *	and 'type' are appropriate for glue retrieval.
 *
468
 *\li	If 'now' is zero, then the current time will be used.
469
 *
470
 *\li	If 'use_hints' is ISC_TRUE, and the view has a hints database, then
471
 *	it will be searched last.  If the answer is found in the hints
472 473
 *	database, the result code will be DNS_R_HINT.  If the name is found
 *	in the hints database but not the type, the result code will be
474
 *	#DNS_R_HINTNXRRSET.
475
 *
476
 *\li	'foundname' must meet the requirements of dns_db_find().
477
 *
478
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
479 480 481 482
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
 * Requires:
 *
483
 *\li	'view' is a valid, frozen view.
484
 *
485
 *\li	'name' is valid name.
486
 *
487
 *\li	'type' is a valid dns_rdatatype_t, and is not a meta query type
488
 *	except dns_rdatatype_any.
489
 *
490
 *\li	dbp == NULL || *dbp == NULL
491
 *
492
 *\li	nodep == NULL || *nodep == NULL.  If nodep != NULL, dbp != NULL.
493
 *
494
 *\li	'foundname' is a valid name with a dedicated buffer or NULL.
495
 *
496
 *\li	'rdataset' is a valid, disassociated rdataset.
497
 *
498
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
499 500 501
 *
 * Ensures:
 *
502
 *\li	In successful cases, 'rdataset', and possibly 'sigrdataset', are
503 504
 *	bound to the found data.
 *
505
 *\li	If dbp != NULL, it points to the database containing the data.
506
 *
507
 *\li	If nodep != NULL, it points to the database node containing the data.
508
 *
509
 *\li	If foundname != NULL, it contains the full name of the found data.
510
 *
511 512
 * Returns:
 *
513 514
 *\li	Any result that dns_db_find() can return, with the exception of
 *	#DNS_R_DELEGATION.
515 516 517 518 519 520 521
 */

isc_result_t
dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
		    isc_stdtime_t now, unsigned int options,
		    isc_boolean_t use_hints,
		    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
522
/*%<
Bob Halley's avatar
Bob Halley committed
523 524 525 526 527
 * Find an rdataset whose owner name is 'name', and whose type is
 * 'type'.
 *
 * Notes:
 *
528
 *\li	This routine is appropriate for simple, exact-match queries of the
Bob Halley's avatar
Bob Halley committed
529 530
 *	view.  'name' must be a canonical name; there is no DNAME or CNAME
 *	processing.
Bob Halley's avatar
Bob Halley committed
531
 *
532
 *\li	See the description of dns_db_find() for information about 'options'.
Bob Halley's avatar
Bob Halley committed
533 534 535
 *	If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
 *	and 'type' are appropriate for glue retrieval.
 *
536
 *\li	If 'now' is zero, then the current time will be used.
Bob Halley's avatar
Bob Halley committed
537
 *
538
 *\li	If 'use_hints' is ISC_TRUE, and the view has a hints database, then
Bob Halley's avatar
Bob Halley committed
539
 *	it will be searched last.  If the answer is found in the hints
540 541 542
 *	database, the result code will be DNS_R_HINT.  If the name is found
 *	in the hints database but not the type, the result code will be
 *	DNS_R_HINTNXRRSET.
Bob Halley's avatar
Bob Halley committed
543
 *
544
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
Bob Halley's avatar
Bob Halley committed
545 546 547 548
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
 * Requires:
 *
549
 *\li	'view' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
550
 *
551
 *\li	'name' is valid name.
Bob Halley's avatar
Bob Halley committed
552
 *
553
 *\li	'type' is a valid dns_rdatatype_t, and is not a meta query type
554
 *	(e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
Bob Halley's avatar
Bob Halley committed
555
 *
556
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
557
 *
558
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
559 560 561
 *
 * Ensures:
 *
562
 *\li	In successful cases, 'rdataset', and possibly 'sigrdataset', are
563
 *	bound to the found data.
Bob Halley's avatar
Bob Halley committed
564 565 566
 *
 * Returns:
 *
567 568 569 570 571 572 573 574
 *\li	#ISC_R_SUCCESS			Success; result is desired type.
 *\li	DNS_R_GLUE			Success; result is glue.
 *\li	DNS_R_HINT			Success; result is a hint.
 *\li	DNS_R_NCACHENXDOMAIN		Success; result is a ncache entry.
 *\li	DNS_R_NCACHENXRRSET		Success; result is a ncache entry.
 *\li	DNS_R_NXDOMAIN			The name does not exist.
 *\li	DNS_R_NXRRSET			The rrset does not exist.
 *\li	#ISC_R_NOTFOUND			No matching data found,
575
 *					or an error occurred.
Bob Halley's avatar
Bob Halley committed
576
 */
577

578
/*% See dns_view_findzonecut2() */
Bob Halley's avatar
Bob Halley committed
579 580 581 582 583
isc_result_t
dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
		     isc_stdtime_t now, unsigned int options,
		     isc_boolean_t use_hints,
		     dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
584 585 586 587 588 589

isc_result_t
dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
		      isc_stdtime_t now, unsigned int options,
		      isc_boolean_t use_hints, isc_boolean_t use_cache,
		      dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
590
/*%<
Bob Halley's avatar
Bob Halley committed
591 592
 * Find the best known zonecut containing 'name'.
 *
Andreas Gustafsson's avatar
Andreas Gustafsson committed
593 594 595
 * This uses local authority, cache, and optionally hints data.
 * No external queries are performed.
 *
Bob Halley's avatar
Bob Halley committed
596 597
 * Notes:
 *
598
 *\li	If 'now' is zero, then the current time will be used.
Bob Halley's avatar
Bob Halley committed
599
 *
600
 *\li	If 'use_hints' is ISC_TRUE, and the view has a hints database, then
Bob Halley's avatar
Bob Halley committed
601 602
 *	it will be searched last.
 *
603
 *\li	If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be
604 605
 *	searched.
 *
606
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
Bob Halley's avatar
Bob Halley committed
607 608
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
609
 *\li	If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
610
 *	(if any) will be the deepest known ancestor of 'name'.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
611
 *
Bob Halley's avatar
Bob Halley committed
612 613
 * Requires:
 *
614
 *\li	'view' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
615
 *
616
 *\li	'name' is valid name.
Bob Halley's avatar
Bob Halley committed
617
 *
618
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
619
 *
620
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
621 622 623
 *
 * Returns:
 *
624
 *\li	#ISC_R_SUCCESS				Success.
Bob Halley's avatar
Bob Halley committed
625
 *
626
 *\li	Many other results are possible.
Bob Halley's avatar
Bob Halley committed
627 628
 */

629 630 631
isc_result_t
dns_viewlist_find(dns_viewlist_t *list, const char *name,
		  dns_rdataclass_t rdclass, dns_view_t **viewp);
632
/*%<
633 634 635 636 637
 * Search for a view with name 'name' and class 'rdclass' in 'list'.
 * If found, '*viewp' is (strongly) attached to it.
 *
 * Requires:
 *
638
 *\li	'viewp' points to a NULL dns_view_t *.
639 640 641
 *
 * Returns:
 *
642 643
 *\li	#ISC_R_SUCCESS		A matching view was found.
 *\li	#ISC_R_NOTFOUND		No matching view was found.
644 645
 */

646 647
isc_result_t
dns_viewlist_findzone(dns_viewlist_t *list, dns_name_t *name, isc_boolean_t allclasses,
648
		      dns_rdataclass_t rdclass, dns_zone_t **zonep);
649 650 651 652 653 654 655 656 657 658

/*%<
 * Search zone with 'name' in view with 'rdclass' in viewlist 'list'
 * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored
 *
 * Returns:
 *\li	#ISC_R_SUCCESS          A matching zone was found.
 *\li	#ISC_R_NOTFOUND         No matching zone was found.
 */

659
isc_result_t
660
dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep);
661
/*%<
662 663 664 665 666 667
 * Search for the zone 'name' in the zone table of 'view'.
 * If found, 'zonep' is (strongly) attached to it.  There
 * are no partial matches.
 *
 * Requires:
 *
668
 *\li	'zonep' points to a NULL dns_zone_t *.
669 670
 *
 * Returns:
671 672 673
 *\li	#ISC_R_SUCCESS		A matching zone was found.
 *\li	#ISC_R_NOTFOUND		No matching zone was found.
 *\li	others			An error occurred.
674 675
 */

676 677
isc_result_t
dns_view_load(dns_view_t *view, isc_boolean_t stop);
678 679 680

isc_result_t
dns_view_loadnew(dns_view_t *view, isc_boolean_t stop);
681
/*%<
682 683
 * Load zones attached to this view.  dns_view_load() loads
 * all zones whose master file has changed since the last
684
 * load; dns_view_loadnew() loads only zones that have never
685 686 687 688
 * been loaded.
 *
 * If 'stop' is ISC_TRUE, stop on the first error and return it.
 * If 'stop' is ISC_FALSE, ignore errors.
Mark Andrews's avatar
Mark Andrews committed
689 690 691
 *
 * Requires:
 *
692
 *\li	'view' is valid.
Mark Andrews's avatar
Mark Andrews committed
693
 */
694

695 696 697
isc_result_t
dns_view_gettsig(dns_view_t *view, dns_name_t *keyname,
		 dns_tsigkey_t **keyp);
698
/*%<
699 700 701
 * Find the TSIG key configured in 'view' with name 'keyname',
 * if any.
 *
Francis Dupont's avatar
Francis Dupont committed
702
 * Requires:
703
 *\li	keyp points to a NULL dns_tsigkey_t *.
704 705
 *
 * Returns:
706 707 708
 *\li	#ISC_R_SUCCESS	A key was found and '*keyp' now points to it.
 *\li	#ISC_R_NOTFOUND	No key was found.
 *\li	others		An error occurred.
709 710 711 712 713
 */

isc_result_t
dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr,
		     dns_tsigkey_t **keyp);
714
/*%<
715 716 717
 * Find the TSIG key configured in 'view' for the server whose
 * address is 'peeraddr', if any.
 *
Francis Dupont's avatar
Francis Dupont committed
718
 * Requires:
719 720 721
 *	keyp points to a NULL dns_tsigkey_t *.
 *
 * Returns:
722 723 724
 *\li	#ISC_R_SUCCESS	A key was found and '*keyp' now points to it.
 *\li	#ISC_R_NOTFOUND	No key was found.
 *\li	others		An error occurred.
725 726
 */

Brian Wellington's avatar
Brian Wellington committed
727 728
isc_result_t
dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg);
729
/*%<
Brian Wellington's avatar
Brian Wellington committed
730 731 732 733
 * Verifies the signature of a message.
 *
 * Requires:
 *
734 735 736
 *\li	'view' is a valid view.
 *\li	'source' is a valid buffer containing the message
 *\li	'msg' is a valid message
Brian Wellington's avatar
Brian Wellington committed
737 738
 *
 * Returns:
739
 *\li	see dns_tsig_verify()
Brian Wellington's avatar
Brian Wellington committed
740 741
 */

Mark Andrews's avatar
Mark Andrews committed
742 743
void
dns_view_dialup(dns_view_t *view);
744
/*%<
745 746
 * Perform dialup-time maintenance on the zones of 'view'.
 */
Mark Andrews's avatar
Mark Andrews committed
747

748
isc_result_t
749
dns_view_dumpdbtostream(dns_view_t *view, FILE *fp);
750
/*%<
751 752 753 754 755 756 757
 * Dump the current state of the view 'view' to the stream 'fp'
 * for purposes of analysis or debugging.
 *
 * Currently the dumped state includes the view's cache; in the future
 * it may also include other state such as the address database.
 * It will not not include authoritative data since it is voluminous and
 * easily obtainable by other means.
758 759
 *
 * Requires:
760
 *
761
 *\li	'view' is valid.
762
 *
763
 *\li	'fp' refers to a file open for writing.
764 765
 *
 * Returns:
766 767
 * \li	ISC_R_SUCCESS	The cache was successfully dumped.
 * \li	others		An error occurred (see dns_master_dump)
768 769
 */

770 771
isc_result_t
dns_view_flushcache(dns_view_t *view);
772 773
isc_result_t
dns_view_flushcache2(dns_view_t *view, isc_boolean_t fixuponly);
774
/*%<
775 776 777 778 779
 * Flush the view's cache (and ADB).  If 'fixuponly' is true, it only updates
 * the internal reference to the cache DB with omitting actual flush operation.
 * 'fixuponly' is intended to be used for a view that shares a cache with
 * a different view.  dns_view_flushcache() is a backward compatible version
 * that always sets fixuponly to false.
780 781 782 783 784 785 786
 *
 * Requires:
 * 	'view' is valid.
 *
 * 	No other tasks are executing.
 *
 * Returns:
787 788
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
789 790
 */

791 792
isc_result_t
dns_view_flushname(dns_view_t *view, dns_name_t *);
793
/*%<
794 795 796
 * Flush the given name from the view's cache (and ADB).
 *
 * Requires:
797 798
 *\li	'view' is valid.
 *\li	'name' is valid.
799 800
 *
 * Returns:
801
 *\li	#ISC_R_SUCCESS
802 803 804
 *	other returns are failures.
 */

805 806
isc_result_t
dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name);
807
/*%<
808
 * Add the given name to the delegation only table.
809
 *
810 811
 *
 * Requires:
812 813
 *\li	'view' is valid.
 *\li	'name' is valid.
814