view.h 34.7 KB
Newer Older
Bob Halley's avatar
add  
Bob Halley committed
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4 5 6
 * 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
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 8 9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
Bob Halley's avatar
add  
Bob Halley committed
10 11 12 13 14 15
 */

#ifndef DNS_VIEW_H
#define DNS_VIEW_H 1

/*****
16 17
***** Module Info
*****/
Bob Halley's avatar
add  
Bob Halley committed
18

19
/*! \file dns/view.h
20
 * \brief
Bob Halley's avatar
add  
Bob Halley committed
21 22
 * DNS View
 *
Bob Halley's avatar
Bob Halley committed
23 24 25 26 27 28 29 30 31 32 33 34
 * 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
35 36
 *
 * MP:
37
 *\li	Before the view is frozen, the caller must ensure synchronization.
Bob Halley's avatar
Bob Halley committed
38
 *
39
 *\li	After the view is frozen, the module guarantees appropriate
Bob Halley's avatar
Bob Halley committed
40
 *	synchronization of any data structures it creates and manipulates.
Bob Halley's avatar
add  
Bob Halley committed
41 42
 *
 * Reliability:
43
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
44 45
 *
 * Resources:
46
 *\li	TBS
Bob Halley's avatar
add  
Bob Halley committed
47 48
 *
 * Security:
49
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
50 51
 *
 * Standards:
52
 *\li	None.
53
 */
Bob Halley's avatar
add  
Bob Halley committed
54

55
#include <inttypes.h>
56
#include <stdbool.h>
Brian Wellington's avatar
Brian Wellington committed
57 58
#include <stdio.h>

59
#include <isc/event.h>
Bob Halley's avatar
add  
Bob Halley committed
60
#include <isc/lang.h>
61
#include <isc/magic.h>
Brian Wellington's avatar
Brian Wellington committed
62
#include <isc/mutex.h>
63
#include <isc/net.h>
64
#include <isc/refcount.h>
65
#include <isc/rwlock.h>
Bob Halley's avatar
Bob Halley committed
66
#include <isc/stdtime.h>
Bob Halley's avatar
add  
Bob Halley committed
67

68
#include <dns/acl.h>
69
#include <dns/catz.h>
70
#include <dns/clientinfo.h>
Evan Hunt's avatar
Evan Hunt committed
71
#include <dns/dnstap.h>
72
#include <dns/fixedname.h>
73
#include <dns/rdatastruct.h>
74
#include <dns/rpz.h>
75
#include <dns/rrl.h>
Bob Halley's avatar
add  
Bob Halley committed
76
#include <dns/types.h>
77
#include <dns/zt.h>
Bob Halley's avatar
add  
Bob Halley committed
78 79 80 81 82

ISC_LANG_BEGINDECLS

struct dns_view {
	/* Unlocked. */
83 84 85 86 87 88 89 90 91 92 93
	unsigned int	  magic;
	isc_mem_t *	  mctx;
	dns_rdataclass_t  rdclass;
	char *		  name;
	dns_zt_t *	  zonetable;
	dns_resolver_t *  resolver;
	dns_adb_t *	  adb;
	dns_requestmgr_t *requestmgr;
	dns_cache_t *	  cache;
	dns_db_t *	  cachedb;
	dns_db_t *	  hints;
94 95

	/*
Evan Hunt's avatar
Evan Hunt committed
96
	 * security roots and negative trust anchors.
97 98
	 * internal use only; access via * dns_view_getsecroots()
	 */
99 100 101 102 103 104 105 106 107 108 109 110 111
	dns_keytable_t *secroots_priv;
	dns_ntatable_t *ntatable_priv;

	isc_mutex_t  lock;
	bool	     frozen;
	isc_task_t * task;
	isc_event_t  resevent;
	isc_event_t  adbevent;
	isc_event_t  reqevent;
	isc_stats_t *adbstats;
	isc_stats_t *resstats;
	dns_stats_t *resquerystats;
	bool	     cacheshared;
112

113
	/* Configurable data. */
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
	dns_tsig_keyring_t *  statickeys;
	dns_tsig_keyring_t *  dynamickeys;
	dns_peerlist_t *      peers;
	dns_order_t *	      order;
	dns_fwdtable_t *      fwdtable;
	bool		      recursion;
	bool		      qminimization;
	bool		      qmin_strict;
	bool		      auth_nxdomain;
	bool		      use_glue_cache;
	bool		      minimal_any;
	dns_minimaltype_t     minimalresponses;
	bool		      enablevalidation;
	bool		      acceptexpired;
	bool		      requireservercookie;
	bool		      synthfromdnssec;
	bool		      trust_anchor_telemetry;
	bool		      root_key_sentinel;
	dns_transfer_format_t transfer_format;
	dns_acl_t *	      cacheacl;
	dns_acl_t *	      cacheonacl;
	dns_acl_t *	      queryacl;
	dns_acl_t *	      queryonacl;
	dns_acl_t *	      recursionacl;
	dns_acl_t *	      recursiononacl;
	dns_acl_t *	      sortlist;
	dns_acl_t *	      notifyacl;
	dns_acl_t *	      transferacl;
	dns_acl_t *	      updateacl;
	dns_acl_t *	      upfwdacl;
	dns_acl_t *	      denyansweracl;
	dns_acl_t *	      nocasecompress;
	bool		      msgcompression;
	dns_rbt_t *	      answeracl_exclude;
	dns_rbt_t *	      denyanswernames;
	dns_rbt_t *	      answernames_exclude;
	dns_rrl_t *	      rrl;
	bool		      provideixfr;
	bool		      requestnsid;
	bool		      sendcookie;
	dns_ttl_t	      maxcachettl;
	dns_ttl_t	      maxncachettl;
	dns_ttl_t	      mincachettl;
	dns_ttl_t	      minncachettl;
	uint32_t	      nta_lifetime;
	uint32_t	      nta_recheck;
	char *		      nta_file;
	dns_ttl_t	      prefetch_trigger;
	dns_ttl_t	      prefetch_eligible;
	in_port_t	      dstport;
	dns_aclenv_t	      aclenv;
	dns_rdatatype_t	      preferred_glue;
	bool		      flush;
	dns_namelist_t *      delonly;
	bool		      rootdelonly;
	dns_namelist_t *      rootexclude;
	bool		      checknames;
	uint16_t	      maxudp;
	dns_ttl_t	      staleanswerttl;
	dns_stale_answer_t    staleanswersok;	  /* rndc setting */
174 175 176 177 178 179 180 181 182 183 184 185 186 187
	bool		      staleanswersenable; /* named.conf setting
						   * */
	uint16_t	  nocookieudp;
	uint16_t	  padding;
	dns_acl_t *	  pad_acl;
	unsigned int	  maxbits;
	dns_dns64list_t	  dns64;
	unsigned int	  dns64cnt;
	dns_rpz_zones_t * rpzs;
	dns_catz_zones_t *catzs;
	dns_dlzdblist_t	  dlz_searched;
	dns_dlzdblist_t	  dlz_unsearched;
	uint32_t	  fail_ttl;
	dns_badcache_t *  failcache;
188

189 190 191 192
	/*
	 * Configurable data for server use only,
	 * locked by server configuration lock.
	 */
193 194 195
	dns_acl_t *matchclients;
	dns_acl_t *matchdestinations;
	bool	   matchrecursiveonly;
196

197
	/* Locked by themselves. */
198 199 200
	isc_refcount_t	     references;
	isc_refcount_t	     weakrefs;
	atomic_uint_fast32_t attributes;
201

Bob Halley's avatar
add  
Bob Halley committed
202
	/* Under owner's locking control. */
203 204
	ISC_LINK(struct dns_view) link;
	dns_viewlist_t *viewlist;
Automatic Updater's avatar
Automatic Updater committed
205

206 207 208 209 210 211
	dns_zone_t *managed_keys;
	dns_zone_t *redirect;
	dns_name_t *redirectzone; /* points to
				   * redirectfixed
				   * when valid */
	dns_fixedname_t redirectfixed;
212

Tinderbox User's avatar
Tinderbox User committed
213
	/*
214 215 216 217 218 219
	 * File and configuration data for zones added at runtime
	 * (only used in BIND9).
	 *
	 * XXX: This should be a pointer to an opaque type that
	 * named implements.
	 */
220 221 222 223 224 225 226 227 228 229 230 231 232 233
	char *	 new_zone_dir;
	char *	 new_zone_file;
	char *	 new_zone_db;
	void *	 new_zone_dbenv;
	uint64_t new_zone_mapsize;
	void *	 new_zone_config;
	void (*cfg_destroy)(void **);
	isc_mutex_t new_zone_lock;

	unsigned char secret[32]; /* Client secret */
	unsigned int  v6bias;

	dns_dtenv_t *	dtenv;	 /* Dnstap environment */
	dns_dtmsgtype_t dttypes; /* Dnstap message types
234
				  * to log */
235

236
	/* Registered module instances */
237 238
	void *plugins;
	void (*plugins_free)(isc_mem_t *, void **);
239 240

	/* Hook table */
241 242
	void *hooktable; /* ns_hooktable */
	void (*hooktable_free)(isc_mem_t *, void **);
Bob Halley's avatar
add  
Bob Halley committed
243 244
};

Evan Hunt's avatar
Evan Hunt committed
245
#define DNS_VIEW_MAGIC	     ISC_MAGIC('V', 'i', 'e', 'w')
246
#define DNS_VIEW_VALID(view) ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
Bob Halley's avatar
add  
Bob Halley committed
247

248 249 250
#define DNS_VIEWATTR_RESSHUTDOWN 0x01
#define DNS_VIEWATTR_ADBSHUTDOWN 0x02
#define DNS_VIEWATTR_REQSHUTDOWN 0x04
251

252 253 254 255 256 257 258
#ifdef HAVE_LMDB
#include <lmdb.h>
/*
 * MDB_NOTLS is used to prevent problems after configuration is reloaded, due
 * to the way LMDB's use of thread-local storage (TLS) interacts with the BIND9
 * thread model.
 */
259
#define DNS_LMDB_COMMON_FLAGS (MDB_CREATE | MDB_NOSUBDIR | MDB_NOTLS)
260
#ifndef __OpenBSD__
261
#define DNS_LMDB_FLAGS (DNS_LMDB_COMMON_FLAGS)
262 263 264 265 266
#else /* __OpenBSD__ */
/*
 * OpenBSD does not have a unified buffer cache, which requires both reads and
 * writes to be performed using mmap().
 */
267
#define DNS_LMDB_FLAGS (DNS_LMDB_COMMON_FLAGS | MDB_WRITEMAP)
268 269 270
#endif /* __OpenBSD__ */
#endif /* HAVE_LMDB */

Bob Halley's avatar
add  
Bob Halley committed
271
isc_result_t
272 273
dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, const char *name,
		dns_view_t **viewp);
274
/*%<
Bob Halley's avatar
Bob Halley committed
275 276 277 278
 * Create a view.
 *
 * Notes:
 *
279
 *\li	The newly created view has no cache, no resolver, and an empty
Bob Halley's avatar
Bob Halley committed
280 281 282 283
 *	zone table.  The view is not frozen.
 *
 * Requires:
 *
284
 *\li	'mctx' is a valid memory context.
Bob Halley's avatar
Bob Halley committed
285
 *
286
 *\li	'rdclass' is a valid class.
Bob Halley's avatar
Bob Halley committed
287
 *
288
 *\li	'name' is a valid C string.
Bob Halley's avatar
Bob Halley committed
289
 *
290
 *\li	viewp != NULL && *viewp == NULL
Bob Halley's avatar
Bob Halley committed
291 292 293
 *
 * Returns:
 *
294 295
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
296
 *
297
 *\li	Other errors are possible.
Bob Halley's avatar
Bob Halley committed
298
 */
Bob Halley's avatar
add  
Bob Halley committed
299 300 301

void
dns_view_attach(dns_view_t *source, dns_view_t **targetp);
302
/*%<
Bob Halley's avatar
Bob Halley committed
303 304 305 306
 * Attach '*targetp' to 'source'.
 *
 * Requires:
 *
307
 *\li	'source' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
308
 *
309
 *\li	'targetp' points to a NULL dns_view_t *.
Bob Halley's avatar
Bob Halley committed
310 311 312
 *
 * Ensures:
 *
313
 *\li	*targetp is attached to source.
314
 *
315
 *\li	While *targetp is attached, the view will not shut down.
Bob Halley's avatar
Bob Halley committed
316
 */
Bob Halley's avatar
add  
Bob Halley committed
317 318 319

void
dns_view_detach(dns_view_t **viewp);
320
/*%<
Bob Halley's avatar
Bob Halley committed
321 322 323 324
 * Detach '*viewp' from its view.
 *
 * Requires:
 *
325
 *\li	'viewp' points to a valid dns_view_t *
Bob Halley's avatar
Bob Halley committed
326 327 328
 *
 * Ensures:
 *
329
 *\li	*viewp is NULL.
330 331
 */

332 333
void
dns_view_flushanddetach(dns_view_t **viewp);
334
/*%<
335
 * Detach '*viewp' from its view.  If this was the last reference
Francis Dupont's avatar
Francis Dupont committed
336
 * uncommitted changed in zones will be flushed to disk.
337 338 339
 *
 * Requires:
 *
340
 *\li	'viewp' points to a valid dns_view_t *
341 342 343
 *
 * Ensures:
 *
344
 *\li	*viewp is NULL.
345 346
 */

347 348
void
dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
349
/*%<
350 351 352 353
 * Weakly attach '*targetp' to 'source'.
 *
 * Requires:
 *
354
 *\li	'source' is a valid, frozen view.
355
 *
356
 *\li	'targetp' points to a NULL dns_view_t *.
357 358
 *
 * Ensures:
Bob Halley's avatar
Bob Halley committed
359
 *
360
 *\li	*targetp is attached to source.
361
 *
362
 * \li	While *targetp is attached, the view will not be freed.
363 364 365 366
 */

void
dns_view_weakdetach(dns_view_t **targetp);
367
/*%<
368
 * Detach '*viewp' from its view.
Bob Halley's avatar
Bob Halley committed
369
 *
370 371
 * Requires:
 *
372
 *\li	'viewp' points to a valid dns_view_t *.
373 374 375
 *
 * Ensures:
 *
376
 *\li	*viewp is NULL.
Bob Halley's avatar
Bob Halley committed
377
 */
Bob Halley's avatar
add  
Bob Halley committed
378

379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
isc_result_t
dns_view_createzonetable(dns_view_t *view);
/*%<
 * Create a zonetable for the view.
 *
 * Requires:
 *
 *\li	'view' is a valid, unfrozen view.
 *
 *\li	'view' does not have a zonetable already.
 *
 * Returns:
 *
 *\li   	#ISC_R_SUCCESS
 *
 *\li	Any error that dns_zt_create() can return.
 */

Bob Halley's avatar
Bob Halley committed
397
isc_result_t
398
dns_view_createresolver(dns_view_t *view, isc_taskmgr_t *taskmgr,
399
			unsigned int ntasks, unsigned int ndisp,
400 401 402
			isc_socketmgr_t *socketmgr, isc_timermgr_t *timermgr,
			unsigned int options, dns_dispatchmgr_t *dispatchmgr,
			dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6);
403
/*%<
Bob Halley's avatar
add adb  
Bob Halley committed
404
 * Create a resolver and address database for the view.
Bob Halley's avatar
Bob Halley committed
405 406 407
 *
 * Requires:
 *
408
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
409
 *
410
 *\li	'view' does not have a resolver already.
Bob Halley's avatar
Bob Halley committed
411
 *
412
 *\li	The requirements of dns_resolver_create() apply to 'taskmgr',
413 414
 *	'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
 *	'dispatchv6'.
Bob Halley's avatar
Bob Halley committed
415 416
 *
 * Returns:
Bob Halley's avatar
Bob Halley committed
417
 *
418
 *\li   	#ISC_R_SUCCESS
Bob Halley's avatar
Bob Halley committed
419
 *
420
 *\li	Any error that dns_resolver_create() can return.
Bob Halley's avatar
Bob Halley committed
421
 */
422 423

void
424
dns_view_setcache(dns_view_t *view, dns_cache_t *cache, bool shared);
425
/*%<
426 427
 * 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()
428
 * is a backward compatible version equivalent to setcache2(..., false).
Bob Halley's avatar
Bob Halley committed
429 430 431
 *
 * Requires:
 *
432
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
433
 *
434
 *\li	'cache' is a valid cache.
Bob Halley's avatar
Bob Halley committed
435 436 437
 *
 * Ensures:
 *
438
 * \li    	The cache of 'view' is 'cached.
Bob Halley's avatar
add adb  
Bob Halley committed
439
 *
440
 *\li	If this is not the first call to dns_view_setcache() for this
441
 *	view, then previously set cache is detached.
Bob Halley's avatar
Bob Halley committed
442
 */
443

Bob Halley's avatar
Bob Halley committed
444 445
void
dns_view_sethints(dns_view_t *view, dns_db_t *hints);
446
/*%<
Bob Halley's avatar
Bob Halley committed
447 448 449 450
 * Set the view's hints database.
 *
 * Requires:
 *
451
 *\li	'view' is a valid, unfrozen view, whose hints database has not been
Bob Halley's avatar
Bob Halley committed
452 453
 *	set.
 *
454
 *\li	'hints' is a valid zone database.
Bob Halley's avatar
Bob Halley committed
455 456 457
 *
 * Ensures:
 *
458
 * \li    	The hints database of 'view' is 'hints'.
Bob Halley's avatar
Bob Halley committed
459 460
 */

Brian Wellington's avatar
Brian Wellington committed
461 462
void
dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
463 464
void
dns_view_setdynamickeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
465
/*%<
Brian Wellington's avatar
Brian Wellington committed
466 467 468 469
 * Set the view's static TSIG keys
 *
 * Requires:
 *
470
 *   \li   'view' is a valid, unfrozen view, whose static TSIG keyring has not
Brian Wellington's avatar
Brian Wellington committed
471 472
 *	been set.
 *
473
 *\li      'ring' is a valid TSIG keyring
Brian Wellington's avatar
Brian Wellington committed
474 475 476
 *
 * Ensures:
 *
477
 *\li      The static TSIG keyring of 'view' is 'ring'.
Brian Wellington's avatar
Brian Wellington committed
478 479
 */

480 481 482 483 484 485 486 487 488
void
dns_view_getdynamickeyring(dns_view_t *view, dns_tsig_keyring_t **ringp);
/*%<
 * Return the views dynamic keys.
 *
 *   \li  'view' is a valid, unfrozen view.
 *   \li  'ringp' != NULL && ringp == NULL.
 */

489 490
void
dns_view_setdstport(dns_view_t *view, in_port_t dstport);
491
/*%<
492 493 494 495 496 497
 * 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:
 *
498
 *\li      'view' is a valid view.
499
 *
500
 *\li      'dstport' is a valid TCP/UDP port number.
501 502
 *
 * Ensures:
Francis Dupont's avatar
Francis Dupont committed
503
 *\li	External name servers will be assumed to be listening
504 505 506 507 508
 *	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
509

510
isc_result_t
511
dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
512
/*%<
513
 * Add zone 'zone' to 'view'.
Bob Halley's avatar
Bob Halley committed
514 515 516
 *
 * Requires:
 *
517
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
518
 *
519
 *\li	'zone' is a valid zone.
520
 */
521 522 523

void
dns_view_freeze(dns_view_t *view);
524
/*%<
525
 * Freeze view.  No changes can be made to view configuration while frozen.
Bob Halley's avatar
Bob Halley committed
526 527 528
 *
 * Requires:
 *
529
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
530 531 532
 *
 * Ensures:
 *
533
 *\li	'view' is frozen.
Bob Halley's avatar
Bob Halley committed
534 535
 */

536 537 538 539 540 541 542 543 544 545 546 547 548 549 550
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.
 */
551

Bob Halley's avatar
Bob Halley committed
552
isc_result_t
553
dns_view_find(dns_view_t *view, const dns_name_t *name, dns_rdatatype_t type,
554 555 556 557
	      isc_stdtime_t now, unsigned int options, bool use_hints,
	      bool use_static_stub, dns_db_t **dbp, dns_dbnode_t **nodep,
	      dns_name_t *foundname, dns_rdataset_t *rdataset,
	      dns_rdataset_t *sigrdataset);
558
/*%<
559 560
 * Find an rdataset whose owner name is 'name', and whose type is
 * 'type'.
561 562
 * In general, this function first searches view's zone and cache DBs for the
 * best match data against 'name'.  If nothing found there, and if 'use_hints'
563
 * is true, the view's hint DB (if configured) is searched.
564 565
 * If the view is configured with a static-stub zone which gives the longest
 * match for 'name' among the zones, however, the cache DB is not consulted
566
 * unless 'use_static_stub' is false (see below about this argument).
567 568
 *
 * dns_view_find() is a backward compatible version equivalent to
569
 * dns_view_find2() with use_static_stub argument being false.
570 571 572
 *
 * Notes:
 *
573 574
 *\li	See the description of dns_db_find() for information about 'options'.
 *	If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name'
575 576
 *	and 'type' are appropriate for glue retrieval.
 *
577
 *\li	If 'now' is zero, then the current time will be used.
578
 *
579
 *\li	If 'use_hints' is true, and the view has a hints database, then
580
 *	it will be searched last.  If the answer is found in the hints
581 582
 *	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
583
 *	#DNS_R_HINTNXRRSET.
584
 *
585
 *\li	If 'use_static_stub' is false and the longest match zone for 'name'
586 587
 *	is a static-stub zone, it's ignored and the cache and/or hints will be
 *	searched.  In the majority of the cases this argument should be
588
 *	false.  The only known usage of this argument being true is
589 590 591 592 593 594 595 596 597 598 599 600 601
 *	if this search is for a "bailiwick" glue A or AAAA RRset that may
 *	best match a static-stub zone.  Consider the following example:
 *	this view is configured with a static-stub zone "example.com",
 *	and an attempt of recursive resolution needs to send a query for the
 *	zone.  In this case it's quite likely that the resolver is trying to
 *	find A/AAAA RRs for the apex name "example.com".  And, to honor the
 *	static-stub configuration it needs to return the glue RRs in the
 *	static-stub zone even if that exact RRs coming from the authoritative
 *	zone has been cached.
 *	In other general cases, the requested data is better to be
 *	authoritative, either locally configured or retrieved from an external
 *	server, and the data in the static-stub zone should better be ignored.
 *
602
 *\li	'foundname' must meet the requirements of dns_db_find().
603
 *
604
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
605 606 607 608
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
 * Requires:
 *
609
 *\li	'view' is a valid, frozen view.
610
 *
611
 *\li	'name' is valid name.
612
 *
613
 *\li	'type' is a valid dns_rdatatype_t, and is not a meta query type
614
 *	except dns_rdatatype_any.
615
 *
616
 *\li	dbp == NULL || *dbp == NULL
617
 *
618
 *\li	nodep == NULL || *nodep == NULL.  If nodep != NULL, dbp != NULL.
619
 *
620
 *\li	'foundname' is a valid name with a dedicated buffer or NULL.
621
 *
622
 *\li	'rdataset' is a valid, disassociated rdataset.
623
 *
624
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
625 626 627
 *
 * Ensures:
 *
628
 *\li	In successful cases, 'rdataset', and possibly 'sigrdataset', are
629 630
 *	bound to the found data.
 *
631
 *\li	If dbp != NULL, it points to the database containing the data.
632
 *
633
 *\li	If nodep != NULL, it points to the database node containing the data.
634
 *
635
 *\li	If foundname != NULL, it contains the full name of the found data.
636
 *
637 638
 * Returns:
 *
639 640
 *\li	Any result that dns_db_find() can return, with the exception of
 *	#DNS_R_DELEGATION.
641 642 643
 */

isc_result_t
644 645
dns_view_simplefind(dns_view_t *view, const dns_name_t *name,
		    dns_rdatatype_t type, isc_stdtime_t now,
646
		    unsigned int options, bool use_hints,
647
		    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
648
/*%<
Bob Halley's avatar
Bob Halley committed
649 650 651 652 653
 * Find an rdataset whose owner name is 'name', and whose type is
 * 'type'.
 *
 * Notes:
 *
654
 *\li	This routine is appropriate for simple, exact-match queries of the
Bob Halley's avatar
Bob Halley committed
655 656
 *	view.  'name' must be a canonical name; there is no DNAME or CNAME
 *	processing.
Bob Halley's avatar
Bob Halley committed
657
 *
658
 *\li	See the description of dns_db_find() for information about 'options'.
Bob Halley's avatar
Bob Halley committed
659 660 661
 *	If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
 *	and 'type' are appropriate for glue retrieval.
 *
662
 *\li	If 'now' is zero, then the current time will be used.
Bob Halley's avatar
Bob Halley committed
663
 *
664
 *\li	If 'use_hints' is true, and the view has a hints database, then
Bob Halley's avatar
Bob Halley committed
665
 *	it will be searched last.  If the answer is found in the hints
666 667 668
 *	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
669
 *
670
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
Bob Halley's avatar
Bob Halley committed
671 672 673 674
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
 * Requires:
 *
675
 *\li	'view' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
676
 *
677
 *\li	'name' is valid name.
Bob Halley's avatar
Bob Halley committed
678
 *
679
 *\li	'type' is a valid dns_rdatatype_t, and is not a meta query type
680
 *	(e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
Bob Halley's avatar
Bob Halley committed
681
 *
682
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
683
 *
684
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
685 686 687
 *
 * Ensures:
 *
688
 *\li	In successful cases, 'rdataset', and possibly 'sigrdataset', are
689
 *	bound to the found data.
Bob Halley's avatar
Bob Halley committed
690 691 692
 *
 * Returns:
 *
693 694 695 696 697 698 699 700
 *\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,
701
 *					or an error occurred.
Bob Halley's avatar
Bob Halley committed
702
 */
703

Bob Halley's avatar
Bob Halley committed
704
isc_result_t
705
dns_view_findzonecut(dns_view_t *view, const dns_name_t *name,
706
		     dns_name_t *fname, dns_name_t *dcname, isc_stdtime_t now,
707
		     unsigned int options, bool use_hints, bool use_cache,
Bob Halley's avatar
Bob Halley committed
708
		     dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
709
/*%<
Bob Halley's avatar
Bob Halley committed
710 711
 * Find the best known zonecut containing 'name'.
 *
Andreas Gustafsson's avatar
Andreas Gustafsson committed
712 713 714
 * This uses local authority, cache, and optionally hints data.
 * No external queries are performed.
 *
Bob Halley's avatar
Bob Halley committed
715 716
 * Notes:
 *
717
 *\li	If 'now' is zero, then the current time will be used.
Bob Halley's avatar
Bob Halley committed
718
 *
719
 *\li	If 'use_hints' is true, and the view has a hints database, then
Bob Halley's avatar
Bob Halley committed
720 721
 *	it will be searched last.
 *
722
 *\li	If 'use_cache' is true, and the view has a cache, then it will be
723 724
 *	searched.
 *
725
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
Bob Halley's avatar
Bob Halley committed
726 727
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
728
 *\li	If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
729
 *	(if any) will be the deepest known ancestor of 'name'.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
730
 *
731 732
 *\li	If dcname is not NULL the deepest cached name is copied to it.
 *
Bob Halley's avatar
Bob Halley committed
733 734
 * Requires:
 *
735
 *\li	'view' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
736
 *
737
 *\li	'name' is valid name.
Bob Halley's avatar
Bob Halley committed
738
 *
739
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
740
 *
741
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
742 743 744
 *
 * Returns:
 *
745
 *\li	#ISC_R_SUCCESS				Success.
Bob Halley's avatar
Bob Halley committed
746
 *
747
 *\li	Many other results are possible.
Bob Halley's avatar
Bob Halley committed
748 749
 */

750 751 752
isc_result_t
dns_viewlist_find(dns_viewlist_t *list, const char *name,
		  dns_rdataclass_t rdclass, dns_view_t **viewp);
753
/*%<
754 755 756 757 758
 * Search for a view with name 'name' and class 'rdclass' in 'list'.
 * If found, '*viewp' is (strongly) attached to it.
 *
 * Requires:
 *
759
 *\li	'viewp' points to a NULL dns_view_t *.
760 761 762
 *
 * Returns:
 *
763 764
 *\li	#ISC_R_SUCCESS		A matching view was found.
 *\li	#ISC_R_NOTFOUND		No matching view was found.
765 766
 */

767
isc_result_t
768
dns_viewlist_findzone(dns_viewlist_t *list, const dns_name_t *name,
769
		      bool allclasses, dns_rdataclass_t rdclass,
770
		      dns_zone_t **zonep);
771 772 773 774 775 776 777 778

/*%<
 * 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.
779
 *\li	#ISC_R_MULTIPLE         Multiple zones with the same name were found.
780 781
 */

782
isc_result_t
783
dns_view_findzone(dns_view_t *view, const dns_name_t *name, dns_zone_t **zonep);
784
/*%<
785 786 787 788 789 790
 * 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:
 *
791
 *\li	'zonep' points to a NULL dns_zone_t *.
792 793
 *
 * Returns:
794 795 796
 *\li	#ISC_R_SUCCESS		A matching zone was found.
 *\li	#ISC_R_NOTFOUND		No matching zone was found.
 *\li	others			An error occurred.
797 798
 */

799
isc_result_t
800
dns_view_load(dns_view_t *view, bool stop, bool newonly);
801 802

isc_result_t
803 804
dns_view_asyncload(dns_view_t *view, bool newonly, dns_zt_allloaded_t callback,
		   void *arg);
805
/*%<
806 807
 * Load zones attached to this view.  dns_view_load() loads
 * all zones whose master file has changed since the last
808
 * load
809
 *
810 811 812 813
 * dns_view_asyncload() loads zones asynchronously.  When all zones
 * in the view have finished loading, 'callback' is called with argument
 * 'arg' to inform the caller.
 *
814 815
 * If 'stop' is true, stop on the first error and return it.
 * If 'stop' is false (or we are loading asynchronously), ignore errors.
Mark Andrews's avatar
Mark Andrews committed
816
 *
817 818
 * If 'newonly' is true load only zones that were never loaded.
 *
Mark Andrews's avatar
Mark Andrews committed
819 820
 * Requires:
 *
821
 *\li	'view' is valid.
Mark Andrews's avatar
Mark Andrews committed
822
 */
823

824
isc_result_t
825
dns_view_gettsig(dns_view_t *view, const dns_name_t *keyname,
826
		 dns_tsigkey_t **keyp);
827
/*%<
828 829 830
 * Find the TSIG key configured in 'view' with name 'keyname',
 * if any.
 *
Francis Dupont's avatar
Francis Dupont committed
831
 * Requires:
832
 *\li	keyp points to a NULL dns_tsigkey_t *.
833 834
 *
 * Returns:
835 836 837
 *\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.
838 839 840
 */

isc_result_t
841
dns_view_getpeertsig(dns_view_t *view, const isc_netaddr_t *peeraddr,
842
		     dns_tsigkey_t **keyp);
843
/*%<
844 845 846
 * Find the TSIG key configured in 'view' for the server whose
 * address is 'peeraddr', if any.
 *
Francis Dupont's avatar
Francis Dupont committed
847
 * Requires:
848 849 850
 *	keyp points to a NULL dns_tsigkey_t *.
 *
 * Returns:
851