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

   1/*
   2 * Copyright (C) 2004-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
  18/* $Id$ */
  19
  20#ifndef DNS_ZONE_H
  21#define DNS_ZONE_H 1
  22
  23/*! \file dns/zone.h */
  24
  25/***
  26 ***	Imports
  27 ***/
  28
  29#include <stdio.h>
  30
  31#include <isc/formatcheck.h>
  32#include <isc/lang.h>
  33#include <isc/rwlock.h>
  34
  35#include <dns/masterdump.h>
  36#include <dns/rdatastruct.h>
  37#include <dns/types.h>
  38
  39typedef enum {
  40	dns_zone_none,
  41	dns_zone_master,
  42	dns_zone_slave,
  43	dns_zone_stub,
  44	dns_zone_staticstub,
  45	dns_zone_key,
  46	dns_zone_dlz
  47} dns_zonetype_t;
  48
  49#define DNS_ZONEOPT_SERVERS	  0x00000001U	/*%< perform server checks */
  50#define DNS_ZONEOPT_PARENTS	  0x00000002U	/*%< perform parent checks */
  51#define DNS_ZONEOPT_CHILDREN	  0x00000004U	/*%< perform child checks */
  52#define DNS_ZONEOPT_NOTIFY	  0x00000008U	/*%< perform NOTIFY */
  53#define DNS_ZONEOPT_MANYERRORS	  0x00000010U	/*%< return many errors on load */
  54#define DNS_ZONEOPT_IXFRFROMDIFFS 0x00000020U	/*%< calculate differences */
  55#define DNS_ZONEOPT_NOMERGE	  0x00000040U	/*%< don't merge journal */
  56#define DNS_ZONEOPT_CHECKNS	  0x00000080U	/*%< check if NS's are addresses */
  57#define DNS_ZONEOPT_FATALNS	  0x00000100U	/*%< DNS_ZONEOPT_CHECKNS is fatal */
  58#define DNS_ZONEOPT_MULTIMASTER	  0x00000200U	/*%< this zone has multiple masters */
  59#define DNS_ZONEOPT_USEALTXFRSRC  0x00000400U	/*%< use alternate transfer sources */
  60#define DNS_ZONEOPT_CHECKNAMES	  0x00000800U	/*%< check-names */
  61#define DNS_ZONEOPT_CHECKNAMESFAIL 0x00001000U	/*%< fatal check-name failures */
  62#define DNS_ZONEOPT_CHECKWILDCARD 0x00002000U	/*%< check for internal wildcards */
  63#define DNS_ZONEOPT_CHECKMX	  0x00004000U	/*%< check-mx */
  64#define DNS_ZONEOPT_CHECKMXFAIL   0x00008000U	/*%< fatal check-mx failures */
  65#define DNS_ZONEOPT_CHECKINTEGRITY 0x00010000U	/*%< perform integrity checks */
  66#define DNS_ZONEOPT_CHECKSIBLING  0x00020000U	/*%< perform sibling glue checks */
  67#define DNS_ZONEOPT_NOCHECKNS	  0x00040000U	/*%< disable IN NS address checks */
  68#define DNS_ZONEOPT_WARNMXCNAME	  0x00080000U	/*%< warn on MX CNAME check */
  69#define DNS_ZONEOPT_IGNOREMXCNAME 0x00100000U	/*%< ignore MX CNAME check */
  70#define DNS_ZONEOPT_WARNSRVCNAME  0x00200000U	/*%< warn on SRV CNAME check */
  71#define DNS_ZONEOPT_IGNORESRVCNAME 0x00400000U	/*%< ignore SRV CNAME check */
  72#define DNS_ZONEOPT_UPDATECHECKKSK 0x00800000U	/*%< check dnskey KSK flag */
  73#define DNS_ZONEOPT_TRYTCPREFRESH 0x01000000U	/*%< try tcp refresh on udp failure */
  74#define DNS_ZONEOPT_NOTIFYTOSOA	  0x02000000U	/*%< Notify the SOA MNAME */
  75#define DNS_ZONEOPT_NSEC3TESTZONE 0x04000000U	/*%< nsec3-test-zone */
  76#define DNS_ZONEOPT_SECURETOINSECURE 0x08000000U /*%< dnssec-secure-to-insecure */
  77#define DNS_ZONEOPT_DNSKEYKSKONLY 0x10000000U	/*%< dnssec-dnskey-kskonly */
  78#define DNS_ZONEOPT_CHECKDUPRR	  0x20000000U   /*%< check-dup-records */
  79#define DNS_ZONEOPT_CHECKDUPRRFAIL 0x40000000U	/*%< fatal check-dup-records failures */
  80
  81#ifndef NOMINUM_PUBLIC
  82/*
  83 * Nominum specific options build down.
  84 */
  85#define DNS_ZONEOPT_NOTIFYFORWARD 0x80000000U	/* forward notify to master */
  86#endif /* NOMINUM_PUBLIC */
  87
  88/*
  89 * Zone key maintenance options
  90 */
  91#define DNS_ZONEKEY_ALLOW	0x00000001U	/*%< fetch keys on command */
  92#define DNS_ZONEKEY_MAINTAIN	0x00000002U	/*%< publish/sign on schedule */
  93#define DNS_ZONEKEY_CREATE	0x00000004U	/*%< make keys when needed */
  94#define DNS_ZONEKEY_FULLSIGN    0x00000008U     /*%< roll to new keys immediately */
  95
  96#ifndef DNS_ZONE_MINREFRESH
  97#define DNS_ZONE_MINREFRESH		    300	/*%< 5 minutes */
  98#endif
  99#ifndef DNS_ZONE_MAXREFRESH
 100#define DNS_ZONE_MAXREFRESH		2419200	/*%< 4 weeks */
 101#endif
 102#ifndef DNS_ZONE_DEFAULTREFRESH
 103#define DNS_ZONE_DEFAULTREFRESH		   3600	/*%< 1 hour */
 104#endif
 105#ifndef DNS_ZONE_MINRETRY
 106#define DNS_ZONE_MINRETRY		    300	/*%< 5 minutes */
 107#endif
 108#ifndef DNS_ZONE_MAXRETRY
 109#define DNS_ZONE_MAXRETRY		1209600	/*%< 2 weeks */
 110#endif
 111#ifndef DNS_ZONE_DEFAULTRETRY
 112#define DNS_ZONE_DEFAULTRETRY		     60	/*%< 1 minute, subject to
 113						   exponential backoff */
 114#endif
 115
 116#define DNS_ZONESTATE_XFERRUNNING	1
 117#define DNS_ZONESTATE_XFERDEFERRED	2
 118#define DNS_ZONESTATE_SOAQUERY		3
 119#define DNS_ZONESTATE_ANY		4
 120
 121ISC_LANG_BEGINDECLS
 122
 123/***
 124 ***	Functions
 125 ***/
 126
 127isc_result_t
 128dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx);
 129/*%<
 130 *	Creates a new empty zone and attach '*zonep' to it.
 131 *
 132 * Requires:
 133 *\li	'zonep' to point to a NULL pointer.
 134 *\li	'mctx' to be a valid memory context.
 135 *
 136 * Ensures:
 137 *\li	'*zonep' refers to a valid zone.
 138 *
 139 * Returns:
 140 *\li	#ISC_R_SUCCESS
 141 *\li	#ISC_R_NOMEMORY
 142 *\li	#ISC_R_UNEXPECTED
 143 */
 144
 145void
 146dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass);
 147/*%<
 148 *	Sets the class of a zone.  This operation can only be performed
 149 *	once on a zone.
 150 *
 151 * Require:
 152 *\li	'zone' to be a valid zone.
 153 *\li	dns_zone_setclass() not to have been called since the zone was
 154 *	created.
 155 *\li	'rdclass' != dns_rdataclass_none.
 156 */
 157
 158dns_rdataclass_t
 159dns_zone_getclass(dns_zone_t *zone);
 160/*%<
 161 *	Returns the current zone class.
 162 *
 163 * Requires:
 164 *\li	'zone' to be a valid zone.
 165 */
 166
 167isc_result_t
 168dns_zone_getserial2(dns_zone_t *zone, isc_uint32_t *serialp);
 169
 170isc_uint32_t
 171dns_zone_getserial(dns_zone_t *zone);
 172/*%<
 173 *	Returns the current serial number of the zone.  On success, the SOA
 174 *	serial of the zone will be copied into '*serialp'.
 175 *	dns_zone_getserial() cannot catch failure cases and is deprecated by
 176 *	dns_zone_getserial2().
 177 *
 178 * Requires:
 179 *\li	'zone' to be a valid zone.
 180 *\li	'serialp' to be non NULL
 181 *
 182 * Returns:
 183 *\li	#ISC_R_SUCCESS
 184 *\li	#DNS_R_NOTLOADED	zone DB is not loaded
 185 */
 186
 187void
 188dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type);
 189/*%<
 190 *	Sets the zone type. This operation can only be performed once on
 191 *	a zone.
 192 *
 193 * Requires:
 194 *\li	'zone' to be a valid zone.
 195 *\li	dns_zone_settype() not to have been called since the zone was
 196 *	created.
 197 *\li	'type' != dns_zone_none
 198 */
 199
 200void
 201dns_zone_setview(dns_zone_t *zone, dns_view_t *view);
 202/*%<
 203 *	Associate the zone with a view.
 204 *
 205 * Require:
 206 *\li	'zone' to be a valid zone.
 207 */
 208
 209dns_view_t *
 210dns_zone_getview(dns_zone_t *zone);
 211/*%<
 212 *	Returns the zone's associated view.
 213 *
 214 * Requires:
 215 *\li	'zone' to be a valid zone.
 216 */
 217
 218isc_result_t
 219dns_zone_setorigin(dns_zone_t *zone, const dns_name_t *origin);
 220/*%<
 221 *	Sets the zones origin to 'origin'.
 222 *
 223 * Require:
 224 *\li	'zone' to be a valid zone.
 225 *\li	'origin' to be non NULL.
 226 *
 227 * Returns:
 228 *\li	#ISC_R_SUCCESS
 229 *\li 	#ISC_R_NOMEMORY
 230 */
 231
 232dns_name_t *
 233dns_zone_getorigin(dns_zone_t *zone);
 234/*%<
 235 *	Returns the value of the origin.
 236 *
 237 * Require:
 238 *\li	'zone' to be a valid zone.
 239 */
 240
 241isc_result_t
 242dns_zone_setfile(dns_zone_t *zone, const char *file);
 243
 244isc_result_t
 245dns_zone_setfile2(dns_zone_t *zone, const char *file,
 246		  dns_masterformat_t format);
 247/*%<
 248 *    Sets the name of the master file in the format of 'format' from which
 249 *    the zone loads its database to 'file'.
 250 *
 251 *    For zones that have no associated master file, 'file' will be NULL.
 252 *
 253 *	For zones with persistent databases, the file name
 254 *	setting is ignored.
 255 *
 256 *    dns_zone_setfile() is a backward-compatible form of
 257 *    dns_zone_setfile2(), which always specifies the
 258 *    dns_masterformat_text (RFC1035) format.
 259 *
 260 * Require:
 261 *\li	'zone' to be a valid zone.
 262 *
 263 * Returns:
 264 *\li	#ISC_R_NOMEMORY
 265 *\li	#ISC_R_SUCCESS
 266 */
 267
 268const char *
 269dns_zone_getfile(dns_zone_t *zone);
 270/*%<
 271 * 	Gets the name of the zone's master file, if any.
 272 *
 273 * Requires:
 274 *\li	'zone' to be valid initialised zone.
 275 *
 276 * Returns:
 277 *\li	Pointer to null-terminated file name, or NULL.
 278 */
 279
 280isc_result_t
 281dns_zone_load(dns_zone_t *zone);
 282
 283isc_result_t
 284dns_zone_loadnew(dns_zone_t *zone);
 285
 286isc_result_t
 287dns_zone_loadandthaw(dns_zone_t *zone);
 288/*%<
 289 *	Cause the database to be loaded from its backing store.
 290 *	Confirm that the minimum requirements for the zone type are
 291 *	met, otherwise DNS_R_BADZONE is returned.
 292 *
 293 *	dns_zone_loadnew() only loads zones that are not yet loaded.
 294 *	dns_zone_load() also loads zones that are already loaded and
 295 *	and whose master file has changed since the last load.
 296 *	dns_zone_loadandthaw() is similar to dns_zone_load() but will
 297 *	also re-enable DNS UPDATEs when the load completes.
 298 *
 299 * Require:
 300 *\li	'zone' to be a valid zone.
 301 *
 302 * Returns:
 303 *\li	#ISC_R_UNEXPECTED
 304 *\li	#ISC_R_SUCCESS
 305 *\li	DNS_R_CONTINUE	  Incremental load has been queued.
 306 *\li	DNS_R_UPTODATE	  The zone has already been loaded based on
 307 *			  file system timestamps.
 308 *\li	DNS_R_BADZONE
 309 *\li	Any result value from dns_db_load().
 310 */
 311
 312void
 313dns_zone_attach(dns_zone_t *source, dns_zone_t **target);
 314/*%<
 315 *	Attach '*target' to 'source' incrementing its external
 316 * 	reference count.
 317 *
 318 * Require:
 319 *\li	'zone' to be a valid zone.
 320 *\li	'target' to be non NULL and '*target' to be NULL.
 321 */
 322
 323void
 324dns_zone_detach(dns_zone_t **zonep);
 325/*%<
 326 *	Detach from a zone decrementing its external reference count.
 327 *	If this was the last external reference to the zone it will be
 328 * 	shut down and eventually freed.
 329 *
 330 * Require:
 331 *\li	'zonep' to point to a valid zone.
 332 */
 333
 334void
 335dns_zone_iattach(dns_zone_t *source, dns_zone_t **target);
 336/*%<
 337 *	Attach '*target' to 'source' incrementing its internal
 338 * 	reference count.  This is intended for use by operations
 339 * 	such as zone transfers that need to prevent the zone
 340 * 	object from being freed but not from shutting down.
 341 *
 342 * Require:
 343 *\li	The caller is running in the context of the zone's task.
 344 *\li	'zone' to be a valid zone.
 345 *\li	'target' to be non NULL and '*target' to be NULL.
 346 */
 347
 348void
 349dns_zone_idetach(dns_zone_t **zonep);
 350/*%<
 351 *	Detach from a zone decrementing its internal reference count.
 352 *	If there are no more internal or external references to the
 353 * 	zone, it will be freed.
 354 *
 355 * Require:
 356 *\li	The caller is running in the context of the zone's task.
 357 *\li	'zonep' to point to a valid zone.
 358 */
 359
 360void
 361dns_zone_setflag(dns_zone_t *zone, unsigned int flags, isc_boolean_t value);
 362/*%<
 363 *	Sets ('value' == 'ISC_TRUE') / clears ('value' == 'IS_FALSE')
 364 *	zone flags.  Valid flag bits are DNS_ZONE_F_*.
 365 *
 366 * Requires
 367 *\li	'zone' to be a valid zone.
 368 */
 369
 370isc_result_t
 371dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp);
 372/*%<
 373 * 	Attach '*dbp' to the database to if it exists otherwise
 374 *	return DNS_R_NOTLOADED.
 375 *
 376 * Require:
 377 *\li	'zone' to be a valid zone.
 378 *\li	'dbp' to be != NULL && '*dbp' == NULL.
 379 *
 380 * Returns:
 381 *\li	#ISC_R_SUCCESS
 382 *\li	DNS_R_NOTLOADED
 383 */
 384
 385void
 386dns_zone_setdb(dns_zone_t *zone, dns_db_t *db);
 387/*%<
 388 *	Sets the zone database to 'db'.
 389 *
 390 *	This function is expected to be used to configure a zone with a
 391 *	database which is not loaded from a file or zone transfer.
 392 *	It can be used for a general purpose zone, but right now its use
 393 *	is limited to static-stub zones to avoid possible undiscovered
 394 *	problems in the general cases.
 395 *
 396 * Require:
 397 *\li	'zone' to be a valid zone of static-stub.
 398 *\li	zone doesn't have a database.
 399 */
 400
 401isc_result_t
 402dns_zone_setdbtype(dns_zone_t *zone,
 403		   unsigned int dbargc, const char * const *dbargv);
 404/*%<
 405 *	Sets the database type to dbargv[0] and database arguments
 406 *	to subsequent dbargv elements.
 407 *	'db_type' is not checked to see if it is a valid database type.
 408 *
 409 * Require:
 410 *\li	'zone' to be a valid zone.
 411 *\li	'database' to be non NULL.
 412 *\li	'dbargc' to be >= 1
 413 *\li	'dbargv' to point to dbargc NULL-terminated strings
 414 *
 415 * Returns:
 416 *\li	#ISC_R_NOMEMORY
 417 *\li	#ISC_R_SUCCESS
 418 */
 419
 420isc_result_t
 421dns_zone_getdbtype(dns_zone_t *zone, char ***argv, isc_mem_t *mctx);
 422/*%<
 423 *	Returns the current dbtype.  isc_mem_free() should be used
 424 * 	to free 'argv' after use.
 425 *
 426 * Require:
 427 *\li	'zone' to be a valid zone.
 428 *\li	'argv' to be non NULL and *argv to be NULL.
 429 *\li	'mctx' to be valid.
 430 *
 431 * Returns:
 432 *\li	#ISC_R_NOMEMORY
 433 *\li	#ISC_R_SUCCESS
 434 */
 435
 436void
 437dns_zone_markdirty(dns_zone_t *zone);
 438/*%<
 439 *	Mark a zone as 'dirty'.
 440 *
 441 * Require:
 442 *\li	'zone' to be a valid zone.
 443 */
 444
 445void
 446dns_zone_expire(dns_zone_t *zone);
 447/*%<
 448 *	Mark the zone as expired.  If the zone requires dumping cause it to
 449 *	be initiated.  Set the refresh and retry intervals to there default
 450 *	values and unload the zone.
 451 *
 452 * Require
 453 *\li	'zone' to be a valid zone.
 454 */
 455
 456void
 457dns_zone_refresh(dns_zone_t *zone);
 458/*%<
 459 *	Initiate zone up to date checks.  The zone must already be being
 460 *	managed.
 461 *
 462 * Require
 463 *\li	'zone' to be a valid zone.
 464 */
 465
 466isc_result_t
 467dns_zone_flush(dns_zone_t *zone);
 468/*%<
 469 *	Write the zone to database if there are uncommitted changes.
 470 *
 471 * Require:
 472 *\li	'zone' to be a valid zone.
 473 */
 474
 475isc_result_t
 476dns_zone_dump(dns_zone_t *zone);
 477/*%<
 478 *	Write the zone to database.
 479 *
 480 * Require:
 481 *\li	'zone' to be a valid zone.
 482 */
 483
 484isc_result_t
 485dns_zone_dumptostream(dns_zone_t *zone, FILE *fd);
 486
 487isc_result_t
 488dns_zone_dumptostream2(dns_zone_t *zone, FILE *fd, dns_masterformat_t format,
 489		       const dns_master_style_t *style);
 490/*%<
 491 *    Write the zone to stream 'fd' in the specified 'format'.
 492 *    If the 'format' is dns_masterformat_text (RFC1035), 'style' also
 493 *    specifies the file style (e.g., &dns_master_style_default).
 494 *
 495 *    dns_zone_dumptostream() is a backward-compatible form of
 496 *    dns_zone_dumptostream2(), which always uses the dns_masterformat_text
 497 *    format and the dns_master_style_default style.
 498 *
 499 *    Note that dns_zone_dumptostream2() is the most flexible form.  It
 500 *    can also provide the functionality of dns_zone_fulldumptostream().
 501 *
 502 * Require:
 503 *\li	'zone' to be a valid zone.
 504 *\li	'fd' to be a stream open for writing.
 505 */
 506
 507isc_result_t
 508dns_zone_fulldumptostream(dns_zone_t *zone, FILE *fd);
 509/*%<
 510 *	The same as dns_zone_dumptostream, but dumps the zone with
 511 *	different dump settings (dns_master_style_full).
 512 *
 513 * Require:
 514 *\li	'zone' to be a valid zone.
 515 *\li	'fd' to be a stream open for writing.
 516 */
 517
 518void
 519dns_zone_maintenance(dns_zone_t *zone);
 520/*%<
 521 *	Perform regular maintenance on the zone.  This is called as a
 522 *	result of a zone being managed.
 523 *
 524 * Require
 525 *\li	'zone' to be a valid zone.
 526 */
 527
 528isc_result_t
 529dns_zone_setmasters(dns_zone_t *zone, const isc_sockaddr_t *masters,
 530		    isc_uint32_t count);
 531isc_result_t
 532dns_zone_setmasterswithkeys(dns_zone_t *zone,
 533			    const isc_sockaddr_t *masters,
 534			    dns_name_t **keynames,
 535			    isc_uint32_t count);
 536/*%<
 537 *	Set the list of master servers for the zone.
 538 *
 539 * Require:
 540 *\li	'zone' to be a valid zone.
 541 *\li	'masters' array of isc_sockaddr_t with port set or NULL.
 542 *\li	'count' the number of masters.
 543 *\li      'keynames' array of dns_name_t's for tsig keys or NULL.
 544 *
 545 *  \li    dns_zone_setmasters() is just a wrapper to setmasterswithkeys(),
 546 *      passing NULL in the keynames field.
 547 *
 548 * \li	If 'masters' is NULL then 'count' must be zero.
 549 *
 550 * Returns:
 551 *\li	#ISC_R_SUCCESS
 552 *\li	#ISC_R_NOMEMORY
 553 *\li      Any result dns_name_dup() can return, if keynames!=NULL
 554 */
 555
 556isc_result_t
 557dns_zone_setalsonotify(dns_zone_t *zone, const isc_sockaddr_t *notify,
 558		       isc_uint32_t count);
 559/*%<
 560 *	Set the list of additional servers to be notified when
 561 *	a zone changes.	 To clear the list use 'count = 0'.
 562 *
 563 * Require:
 564 *\li	'zone' to be a valid zone.
 565 *\li	'notify' to be non-NULL if count != 0.
 566 *\li	'count' to be the number of notifiees.
 567 *
 568 * Returns:
 569 *\li	#ISC_R_SUCCESS
 570 *\li	#ISC_R_NOMEMORY
 571 */
 572
 573void
 574dns_zone_unload(dns_zone_t *zone);
 575/*%<
 576 *	detach the database from the zone structure.
 577 *
 578 * Require:
 579 *\li	'zone' to be a valid zone.
 580 */
 581
 582void
 583dns_zone_setoption(dns_zone_t *zone, unsigned int option, isc_boolean_t value);
 584/*%<
 585 *	Set given options on ('value' == ISC_TRUE) or off ('value' ==
 586 *	#ISC_FALSE).
 587 *
 588 * Require:
 589 *\li	'zone' to be a valid zone.
 590 */
 591
 592unsigned int
 593dns_zone_getoptions(dns_zone_t *zone);
 594/*%<
 595 *	Returns the current zone options.
 596 *
 597 * Require:
 598 *\li	'zone' to be a valid zone.
 599 */
 600
 601void
 602dns_zone_setkeyopt(dns_zone_t *zone, unsigned int option, isc_boolean_t value);
 603/*%<
 604 *	Set key options on ('value' == ISC_TRUE) or off ('value' ==
 605 *	#ISC_FALSE).
 606 *
 607 * Require:
 608 *\li	'zone' to be a valid zone.
 609 */
 610
 611unsigned int
 612dns_zone_getkeyopts(dns_zone_t *zone);
 613/*%<
 614 *	Returns the current zone key options.
 615 *
 616 * Require:
 617 *\li	'zone' to be a valid zone.
 618 */
 619
 620void
 621dns_zone_setminrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 622/*%<
 623 *	Set the minimum refresh time.
 624 *
 625 * Requires:
 626 *\li	'zone' is valid.
 627 *\li	val > 0.
 628 */
 629
 630void
 631dns_zone_setmaxrefreshtime(dns_zone_t *zone, isc_uint32_t val);
 632/*%<
 633 *	Set the maximum refresh time.
 634 *
 635 * Requires:
 636 *\li	'zone' is valid.
 637 *\li	val > 0.
 638 */
 639
 640void
 641dns_zone_setminretrytime(dns_zone_t *zone, isc_uint32_t val);
 642/*%<
 643 *	Set the minimum retry time.
 644 *
 645 * Requires:
 646 *\li	'zone' is valid.
 647 *\li	val > 0.
 648 */
 649
 650void
 651dns_zone_setmaxretrytime(dns_zone_t *zone, isc_uint32_t val);
 652/*%<
 653 *	Set the maximum retry time.
 654 *
 655 * Requires:
 656 *\li	'zone' is valid.
 657 *	val > 0.
 658 */
 659
 660isc_result_t
 661dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 662isc_result_t
 663dns_zone_setaltxfrsource4(dns_zone_t *zone,
 664			  const isc_sockaddr_t *xfrsource);
 665/*%<
 666 * 	Set the source address to be used in IPv4 zone transfers.
 667 *
 668 * Require:
 669 *\li	'zone' to be a valid zone.
 670 *\li	'xfrsource' to contain the address.
 671 *
 672 * Returns:
 673 *\li	#ISC_R_SUCCESS
 674 */
 675
 676isc_sockaddr_t *
 677dns_zone_getxfrsource4(dns_zone_t *zone);
 678isc_sockaddr_t *
 679dns_zone_getaltxfrsource4(dns_zone_t *zone);
 680/*%<
 681 *	Returns the source address set by a previous dns_zone_setxfrsource4
 682 *	call, or the default of inaddr_any, port 0.
 683 *
 684 * Require:
 685 *\li	'zone' to be a valid zone.
 686 */
 687
 688isc_result_t
 689dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 690isc_result_t
 691dns_zone_setaltxfrsource6(dns_zone_t *zone,
 692			  const isc_sockaddr_t *xfrsource);
 693/*%<
 694 * 	Set the source address to be used in IPv6 zone transfers.
 695 *
 696 * Require:
 697 *\li	'zone' to be a valid zone.
 698 *\li	'xfrsource' to contain the address.
 699 *
 700 * Returns:
 701 *\li	#ISC_R_SUCCESS
 702 */
 703
 704isc_sockaddr_t *
 705dns_zone_getxfrsource6(dns_zone_t *zone);
 706isc_sockaddr_t *
 707dns_zone_getaltxfrsource6(dns_zone_t *zone);
 708/*%<
 709 *	Returns the source address set by a previous dns_zone_setxfrsource6
 710 *	call, or the default of in6addr_any, port 0.
 711 *
 712 * Require:
 713 *\li	'zone' to be a valid zone.
 714 */
 715
 716isc_result_t
 717dns_zone_setnotifysrc4(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 718/*%<
 719 * 	Set the source address to be used with IPv4 NOTIFY messages.
 720 *
 721 * Require:
 722 *\li	'zone' to be a valid zone.
 723 *\li	'notifysrc' to contain the address.
 724 *
 725 * Returns:
 726 *\li	#ISC_R_SUCCESS
 727 */
 728
 729isc_sockaddr_t *
 730dns_zone_getnotifysrc4(dns_zone_t *zone);
 731/*%<
 732 *	Returns the source address set by a previous dns_zone_setnotifysrc4
 733 *	call, or the default of inaddr_any, port 0.
 734 *
 735 * Require:
 736 *\li	'zone' to be a valid zone.
 737 */
 738
 739isc_result_t
 740dns_zone_setnotifysrc6(dns_zone_t *zone, const isc_sockaddr_t *notifysrc);
 741/*%<
 742 * 	Set the source address to be used with IPv6 NOTIFY messages.
 743 *
 744 * Require:
 745 *\li	'zone' to be a valid zone.
 746 *\li	'notifysrc' to contain the address.
 747 *
 748 * Returns:
 749 *\li	#ISC_R_SUCCESS
 750 */
 751
 752isc_sockaddr_t *
 753dns_zone_getnotifysrc6(dns_zone_t *zone);
 754/*%<
 755 *	Returns the source address set by a previous dns_zone_setnotifysrc6
 756 *	call, or the default of in6addr_any, port 0.
 757 *
 758 * Require:
 759 *\li	'zone' to be a valid zone.
 760 */
 761
 762void
 763dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl);
 764/*%<
 765 *	Sets the notify acl list for the zone.
 766 *
 767 * Require:
 768 *\li	'zone' to be a valid zone.
 769 *\li	'acl' to be a valid acl.
 770 */
 771
 772void
 773dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl);
 774/*%<
 775 *	Sets the query acl list for the zone.
 776 *
 777 * Require:
 778 *\li	'zone' to be a valid zone.
 779 *\li	'acl' to be a valid acl.
 780 */
 781
 782void
 783dns_zone_setqueryonacl(dns_zone_t *zone, dns_acl_t *acl);
 784/*%<
 785 *	Sets the query-on acl list for the zone.
 786 *
 787 * Require:
 788 *\li	'zone' to be a valid zone.
 789 *\li	'acl' to be a valid acl.
 790 */
 791
 792void
 793dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl);
 794/*%<
 795 *	Sets the update acl list for the zone.
 796 *
 797 * Require:
 798 *\li	'zone' to be a valid zone.
 799 *\li	'acl' to be valid acl.
 800 */
 801
 802void
 803dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl);
 804/*%<
 805 *	Sets the forward unsigned updates acl list for the zone.
 806 *
 807 * Require:
 808 *\li	'zone' to be a valid zone.
 809 *\li	'acl' to be valid acl.
 810 */
 811
 812void
 813dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl);
 814/*%<
 815 *	Sets the transfer acl list for the zone.
 816 *
 817 * Require:
 818 *\li	'zone' to be a valid zone.
 819 *\li	'acl' to be valid acl.
 820 */
 821
 822dns_acl_t *
 823dns_zone_getnotifyacl(dns_zone_t *zone);
 824/*%<
 825 * 	Returns the current notify acl or NULL.
 826 *
 827 * Require:
 828 *\li	'zone' to be a valid zone.
 829 *
 830 * Returns:
 831 *\li	acl a pointer to the acl.
 832 *\li	NULL
 833 */
 834
 835dns_acl_t *
 836dns_zone_getqueryacl(dns_zone_t *zone);
 837/*%<
 838 * 	Returns the current query acl or NULL.
 839 *
 840 * Require:
 841 *\li	'zone' to be a valid zone.
 842 *
 843 * Returns:
 844 *\li	acl a pointer to the acl.
 845 *\li	NULL
 846 */
 847
 848dns_acl_t *
 849dns_zone_getqueryonacl(dns_zone_t *zone);
 850/*%<
 851 * 	Returns the current query-on acl or NULL.
 852 *
 853 * Require:
 854 *\li	'zone' to be a valid zone.
 855 *
 856 * Returns:
 857 *\li	acl a pointer to the acl.
 858 *\li	NULL
 859 */
 860
 861dns_acl_t *
 862dns_zone_getupdateacl(dns_zone_t *zone);
 863/*%<
 864 * 	Returns the current update acl or NULL.
 865 *
 866 * Require:
 867 *\li	'zone' to be a valid zone.
 868 *
 869 * Returns:
 870 *\li	acl a pointer to the acl.
 871 *\li	NULL
 872 */
 873
 874dns_acl_t *
 875dns_zone_getforwardacl(dns_zone_t *zone);
 876/*%<
 877 * 	Returns the current forward unsigned updates acl or NULL.
 878 *
 879 * Require:
 880 *\li	'zone' to be a valid zone.
 881 *
 882 * Returns:
 883 *\li	acl a pointer to the acl.
 884 *\li	NULL
 885 */
 886
 887dns_acl_t *
 888dns_zone_getxfracl(dns_zone_t *zone);
 889/*%<
 890 * 	Returns the current transfer acl or NULL.
 891 *
 892 * Require:
 893 *\li	'zone' to be a valid zone.
 894 *
 895 * Returns:
 896 *\li	acl a pointer to the acl.
 897 *\li	NULL
 898 */
 899
 900void
 901dns_zone_clearupdateacl(dns_zone_t *zone);
 902/*%<
 903 *	Clear the current update acl.
 904 *
 905 * Require:
 906 *\li	'zone' to be a valid zone.
 907 */
 908
 909void
 910dns_zone_clearforwardacl(dns_zone_t *zone);
 911/*%<
 912 *	Clear the current forward unsigned updates acl.
 913 *
 914 * Require:
 915 *\li	'zone' to be a valid zone.
 916 */
 917
 918void
 919dns_zone_clearnotifyacl(dns_zone_t *zone);
 920/*%<
 921 *	Clear the current notify acl.
 922 *
 923 * Require:
 924 *\li	'zone' to be a valid zone.
 925 */
 926
 927void
 928dns_zone_clearqueryacl(dns_zone_t *zone);
 929/*%<
 930 *	Clear the current query acl.
 931 *
 932 * Require:
 933 *\li	'zone' to be a valid zone.
 934 */
 935
 936void
 937dns_zone_clearqueryonacl(dns_zone_t *zone);
 938/*%<
 939 *	Clear the current query-on acl.
 940 *
 941 * Require:
 942 *\li	'zone' to be a valid zone.
 943 */
 944
 945void
 946dns_zone_clearxfracl(dns_zone_t *zone);
 947/*%<
 948 *	Clear the current transfer acl.
 949 *
 950 * Require:
 951 *\li	'zone' to be a valid zone.
 952 */
 953
 954isc_boolean_t
 955dns_zone_getupdatedisabled(dns_zone_t *zone);
 956/*%<
 957 * Return update disabled.
 958 * Transient unless called when running in isc_task_exclusive() mode.
 959 */
 960
 961void
 962dns_zone_setupdatedisabled(dns_zone_t *zone, isc_boolean_t state);
 963/*%<
 964 * Set update disabled.
 965 * Should only be called only when running in isc_task_exclusive() mode.
 966 * Failure to do so may result in updates being committed after the
 967 * call has been made.
 968 */
 969
 970isc_boolean_t
 971dns_zone_getzeronosoattl(dns_zone_t *zone);
 972/*%<
 973 * Return zero-no-soa-ttl status.
 974 */
 975
 976void
 977dns_zone_setzeronosoattl(dns_zone_t *zone, isc_boolean_t state);
 978/*%<
 979 * Set zero-no-soa-ttl status.
 980 */
 981
 982void
 983dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity);
 984/*%<
 985 * 	Set the severity of name checking when loading a zone.
 986 *
 987 * Require:
 988 * \li     'zone' to be a valid zone.
 989 */
 990
 991dns_severity_t
 992dns_zone_getchecknames(dns_zone_t *zone);
 993/*%<
 994 *	Return the current severity of name checking.
 995 *
 996 * Require:
 997 *\li	'zone' to be a valid zone.
 998 */
 999
1000void
1001dns_zone_setjournalsize(dns_zone_t *zone, isc_int32_t size);
1002/*%<
1003 *	Sets the journal size for the zone.
1004 *
1005 * Requires:
1006 *\li	'zone' to be a valid zone.
1007 */
1008
1009isc_int32_t
1010dns_zone_getjournalsize(dns_zone_t *zone);
1011/*%<
1012 *	Return the journal size as set with a previous call to
1013 *	dns_zone_setjournalsize().
1014 *
1015 * Requires:
1016 *\li	'zone' to be a valid zone.
1017 */
1018
1019isc_result_t
1020dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from,
1021		       dns_message_t *msg);
1022/*%<
1023 *	Tell the zone that it has received a NOTIFY message from another
1024 *	server.  This may cause some zone maintenance activity to occur.
1025 *
1026 * Requires:
1027 *\li	'zone' to be a valid zone.
1028 *\li	'*from' to contain the address of the server from which 'msg'
1029 *		was received.
1030 *\li	'msg' a message with opcode NOTIFY and qr clear.
1031 *
1032 * Returns:
1033 *\li	DNS_R_REFUSED
1034 *\li	DNS_R_NOTIMP
1035 *\li	DNS_R_FORMERR
1036 *\li	DNS_R_SUCCESS
1037 */
1038
1039void
1040dns_zone_setmaxxfrin(dns_zone_t *zone, isc_uint32_t maxxfrin);
1041/*%<
1042 * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR)
1043 * of this zone will use before being aborted.
1044 *
1045 * Requires:
1046 * \li	'zone' to be valid initialised zone.
1047 */
1048
1049isc_uint32_t
1050dns_zone_getmaxxfrin(dns_zone_t *zone);
1051/*%<
1052 * Returns the maximum transfer time for this zone.  This will be
1053 * either the value set by the last call to dns_zone_setmaxxfrin() or
1054 * the default value of 1 hour.
1055 *
1056 * Requires:
1057 *\li	'zone' to be valid initialised zone.
1058 */
1059
1060void
1061dns_zone_setmaxxfrout(dns_zone_t *zone, isc_uint32_t maxxfrout);
1062/*%<
1063 * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR)
1064 * of this zone will use before being aborted.
1065 *
1066 * Requires:
1067 * \li	'zone' to be valid initialised zone.
1068 */
1069
1070isc_uint32_t
1071dns_zone_getmaxxfrout(dns_zone_t *zone);
1072/*%<
1073 * Returns the maximum transfer time for this zone.  This will be
1074 * either the value set by the last call to dns_zone_setmaxxfrout() or
1075 * the default value of 1 hour.
1076 *
1077 * Requires:
1078 *\li	'zone' to be valid initialised zone.
1079 */
1080
1081isc_result_t
1082dns_zone_setjournal(dns_zone_t *zone, const char *journal);
1083/*%<
1084 * Sets the filename used for journaling updates / IXFR transfers.
1085 * The default journal name is set by dns_zone_setfile() to be
1086 * "file.jnl".  If 'journal' is NULL, the zone will have no
1087 * journal name.
1088 *
1089 * Requires:
1090 *\li	'zone' to be a valid zone.
1091 *
1092 * Returns:
1093 *\li	#ISC_R_SUCCESS
1094 *\li	#ISC_R_NOMEMORY
1095 */
1096
1097char *
1098dns_zone_getjournal(dns_zone_t *zone);
1099/*%<
1100 * Returns the journal name associated with this zone.
1101 * If no journal has been set this will be NULL.
1102 *
1103 * Requires:
1104 *\li	'zone' to be valid initialised zone.
1105 */
1106
1107dns_zonetype_t
1108dns_zone_gettype(dns_zone_t *zone);
1109/*%<
1110 * Returns the type of the zone (master/slave/etc.)
1111 *
1112 * Requires:
1113 *\li	'zone' to be valid initialised zone.
1114 */
1115
1116void
1117dns_zone_settask(dns_zone_t *zone, isc_task_t *task);
1118/*%<
1119 * Give a zone a task to work with.  Any current task will be detached.
1120 *
1121 * Requires:
1122 *\li	'zone' to be valid.
1123 *\li	'task' to be valid.
1124 */
1125
1126void
1127dns_zone_gettask(dns_zone_t *zone, isc_task_t **target);
1128/*%<
1129 * Attach '*target' to the zone's task.
1130 *
1131 * Requires:
1132 *\li	'zone' to be valid initialised zone.
1133 *\li	'zone' to have a task.
1134 *\li	'target' to be != NULL && '*target' == NULL.
1135 */
1136
1137void
1138dns_zone_notify(dns_zone_t *zone);
1139/*%<
1140 * Generate notify events for this zone.
1141 *
1142 * Requires:
1143 *\li	'zone' to be a valid zone.
1144 */
1145
1146isc_result_t
1147dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump);
1148/*%<
1149 * Replace the database of "zone" with a new database "db".
1150 *
1151 * If "dump" is ISC_TRUE, then the new zone contents are dumped
1152 * into to the zone's master file for persistence.  When replacing
1153 * a zone database by one just loaded from a master file, set
1154 * "dump" to ISC_FALSE to avoid a redundant redump of the data just
1155 * loaded.  Otherwise, it should be set to ISC_TRUE.
1156 *
1157 * If the "diff-on-reload" option is enabled in the configuration file,
1158 * the differences between the old and the new database are added to the
1159 * journal file, and the master file dump is postponed.
1160 *
1161 * Requires:
1162 * \li	'zone' to be a valid zone.
1163 *
1164 * Returns:
1165 * \li	DNS_R_SUCCESS
1166 * \li	DNS_R_BADZONE	zone failed basic consistency checks:
1167 *			* a single SOA must exist
1168 *			* some NS records must exist.
1169 *	Others
1170 */
1171
1172isc_uint32_t
1173dns_zone_getidlein(dns_zone_t *zone);
1174/*%<
1175 * Requires:
1176 * \li	'zone' to be a valid zone.
1177 *
1178 * Returns:
1179 * \li	number of seconds of idle time before we abort the transfer in.
1180 */
1181
1182void
1183dns_zone_setidlein(dns_zone_t *zone, isc_uint32_t idlein);
1184/*%<
1185 * \li	Set the idle timeout for transfer the.
1186 * \li	Zero set the default value, 1 hour.
1187 *
1188 * Requires:
1189 * \li	'zone' to be a valid zone.
1190 */
1191
1192isc_uint32_t
1193dns_zone_getidleout(dns_zone_t *zone);
1194/*%<
1195 *
1196 * Requires:
1197 * \li	'zone' to be a valid zone.
1198 *
1199 * Returns:
1200 * \li	number of seconds of idle time before we abort a transfer out.
1201 */
1202
1203void
1204dns_zone_setidleout(dns_zone_t *zone, isc_uint32_t idleout);
1205/*%<
1206 * \li	Set the idle timeout for transfers out.
1207 * \li	Zero set the default value, 1 hour.
1208 *
1209 * Requires:
1210 * \li	'zone' to be a valid zone.
1211 */
1212
1213void
1214dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table);
1215/*%<
1216 * Get the simple-secure-update policy table.
1217 *
1218 * Requires:
1219 * \li	'zone' to be a valid zone.
1220 */
1221
1222void
1223dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table);
1224/*%<
1225 * Set / clear the simple-secure-update policy table.
1226 *
1227 * Requires:
1228 * \li	'zone' to be a valid zone.
1229 */
1230
1231isc_mem_t *
1232dns_zone_getmctx(dns_zone_t *zone);
1233/*%<
1234 * Get the memory context of a zone.
1235 *
1236 * Requires:
1237 * \li	'zone' to be a valid zone.
1238 */
1239
1240dns_zonemgr_t *
1241dns_zone_getmgr(dns_zone_t *zone);
1242/*%<
1243 *	If 'zone' is managed return the zone manager otherwise NULL.
1244 *
1245 * Requires:
1246 * \li	'zone' to be a valid zone.
1247 */
1248
1249void
1250dns_zone_setsigvalidityinterval(dns_zone_t *zone, isc_uint32_t interval);
1251/*%<
1252 * Set the zone's RRSIG validity interval.  This is the length of time
1253 * for which DNSSEC signatures created as a result of dynamic updates
1254 * to secure zones will remain valid, in seconds.
1255 *
1256 * Requires:
1257 * \li	'zone' to be a valid zone.
1258 */
1259
1260isc_uint32_t
1261dns_zone_getsigvalidityinterval(dns_zone_t *zone);
1262/*%<
1263 * Get the zone's RRSIG validity interval.
1264 *
1265 * Requires:
1266 * \li	'zone' to be a valid zone.
1267 */
1268
1269void
1270dns_zone_setsigresigninginterval(dns_zone_t *zone, isc_uint32_t interval);
1271/*%<
1272 * Set the zone's RRSIG re-signing interval.  A dynamic zone's RRSIG's
1273 * will be re-signed 'interval' amount of time before they expire.
1274 *
1275 * Requires:
1276 * \li	'zone' to be a valid zone.
1277 */
1278
1279isc_uint32_t
1280dns_zone_getsigresigninginterval(dns_zone_t *zone);
1281/*%<
1282 * Get the zone's RRSIG re-signing interval.
1283 *
1284 * Requires:
1285 * \li	'zone' to be a valid zone.
1286 */
1287
1288void
1289dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype);
1290/*%<
1291 * Sets zone notify method to "notifytype"
1292 */
1293
1294isc_result_t
1295dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg,
1296		       dns_updatecallback_t callback, void *callback_arg);
1297/*%<
1298 * Forward 'msg' to each master in turn until we get an answer or we
1299 * have exhausted the list of masters. 'callback' will be called with
1300 * ISC_R_SUCCESS if we get an answer and the returned message will be
1301 * passed as 'answer_message', otherwise a non ISC_R_SUCCESS result code
1302 * will be passed and answer_message will be NULL.  The callback function
1303 * is responsible for destroying 'answer_message'.
1304 *		(callback)(callback_arg, result, answer_message);
1305 *
1306 * Require:
1307 *\li	'zone' to be valid
1308 *\li	'msg' to be valid.
1309 *\li	'callback' to be non NULL.
1310 * Returns:
1311 *\li	#ISC_R_SUCCESS if the message has been forwarded,
1312 *\li	#ISC_R_NOMEMORY
1313 *\li	Others
1314 */
1315
1316isc_result_t
1317dns_zone_next(dns_zone_t *zone, dns_zone_t **next);
1318/*%<
1319 * Find the next zone in the list of managed zones.
1320 *
1321 * Requires:
1322 *\li	'zone' to be valid
1323 *\li	The zone manager for the indicated zone MUST be locked
1324 *	by the caller.  This is not checked.
1325 *\li	'next' be non-NULL, and '*next' be NULL.
1326 *
1327 * Ensures:
1328 *\li	'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1329 *	(result ISC_R_NOMORE).
1330 */
1331
1332
1333
1334isc_result_t
1335dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first);
1336/*%<
1337 * Find the first zone in the list of managed zones.
1338 *
1339 * Requires:
1340 *\li	'zonemgr' to be valid
1341 *\li	The zone manager for the indicated zone MUST be locked
1342 *	by the caller.  This is not checked.
1343 *\li	'first' be non-NULL, and '*first' be NULL
1344 *
1345 * Ensures:
1346 *\li	'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL
1347 *	(result ISC_R_NOMORE).
1348 */
1349
1350isc_result_t
1351dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory);
1352/*%<
1353 *	Sets the name of the directory where private keys used for
1354 *	online signing of dynamic zones are found.
1355 *
1356 * Require:
1357 *\li	'zone' to be a valid zone.
1358 *
1359 * Returns:
1360 *\li	#ISC_R_NOMEMORY
1361 *\li	#ISC_R_SUCCESS
1362 */
1363
1364const char *
1365dns_zone_getkeydirectory(dns_zone_t *zone);
1366/*%<
1367 * 	Gets the name of the directory where private keys used for
1368 *	online signing of dynamic zones are found.
1369 *
1370 * Requires:
1371 *\li	'zone' to be valid initialised zone.
1372 *
1373 * Returns:
1374 *	Pointer to null-terminated file name, or NULL.
1375 */
1376
1377
1378isc_result_t
1379dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
1380		   isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr,
1381		   dns_zonemgr_t **zmgrp);
1382/*%<
1383 * Create a zone manager.  Note: the zone manager will not be able to
1384 * manage any zones until dns_zonemgr_setsize() has been run.
1385 *
1386 * Requires:
1387 *\li	'mctx' to be a valid memory context.
1388 *\li	'taskmgr' to be a valid task manager.
1389 *\li	'timermgr' to be a valid timer manager.
1390 *\li	'zmgrp'	to point to a NULL pointer.
1391 */
1392
1393isc_result_t
1394dns_zonemgr_setsize(dns_zonemgr_t *zmgr, int num_zones);
1395/*%<
1396 *	Set the size of the zone manager task pool.  This must be run
1397 *	before zmgr can be used for managing zones.  Currently, it can only
1398 *	be run once; the task pool cannot be resized.
1399 *
1400 * Requires:
1401 *\li	zmgr is a valid zone manager.
1402 *\li	zmgr->zonetasks has been initialized.
1403 */
1404
1405isc_result_t
1406dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1407/*%<
1408 *	Bring the zone under control of a zone manager.
1409 *
1410 * Require:
1411 *\li	'zmgr' to be a valid zone manager.
1412 *\li	'zone' to be a valid zone.
1413 */
1414
1415isc_result_t
1416dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr);
1417/*%<
1418 * Force zone maintenance of all zones managed by 'zmgr' at its
1419 * earliest convenience.
1420 */
1421
1422void
1423dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr);
1424/*%<
1425 * Attempt to start any stalled zone transfers.
1426 */
1427
1428void
1429dns_zonemgr_shutdown(dns_zonemgr_t *zmgr);
1430/*%<
1431 *	Shut down the zone manager.
1432 *
1433 * Requires:
1434 *\li	'zmgr' to be a valid zone manager.
1435 */
1436
1437void
1438dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target);
1439/*%<
1440 *	Attach '*target' to 'source' incrementing its external
1441 * 	reference count.
1442 *
1443 * Require:
1444 *\li	'zone' to be a valid zone.
1445 *\li	'target' to be non NULL and '*target' to be NULL.
1446 */
1447
1448void
1449dns_zonemgr_detach(dns_zonemgr_t **zmgrp);
1450/*%<
1451 *	 Detach from a zone manager.
1452 *
1453 * Requires:
1454 *\li	'*zmgrp' is a valid, non-NULL zone manager pointer.
1455 *
1456 * Ensures:
1457 *\li	'*zmgrp' is NULL.
1458 */
1459
1460void
1461dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone);
1462/*%<
1463 *	Release 'zone' from the managed by 'zmgr'.  'zmgr' is implicitly
1464 *	detached from 'zone'.
1465 *
1466 * Requires:
1467 *\li	'zmgr' to be a valid zone manager.
1468 *\li	'zone' to be a valid zone.
1469 *\li	'zmgr' == 'zone->zmgr'
1470 *
1471 * Ensures:
1472 *\li	'zone->zmgr' == NULL;
1473 */
1474
1475void
1476dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, isc_uint32_t value);
1477/*%<
1478 *	Set the maximum number of simultaneous transfers in allowed by
1479 *	the zone manager.
1480 *
1481 * Requires:
1482 *\li	'zmgr' to be a valid zone manager.
1483 */
1484
1485isc_uint32_t
1486dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr);
1487/*%<
1488 *	Return the maximum number of simultaneous transfers in allowed.
1489 *
1490 * Requires:
1491 *\li	'zmgr' to be a valid zone manager.
1492 */
1493
1494void
1495dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, isc_uint32_t value);
1496/*%<
1497 *	Set the number of zone transfers allowed per nameserver.
1498 *
1499 * Requires:
1500 *\li	'zmgr' to be a valid zone manager
1501 */
1502
1503isc_uint32_t
1504dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr);
1505/*%<
1506 *	Return the number of transfers allowed per nameserver.
1507 *
1508 * Requires:
1509 *\li	'zmgr' to be a valid zone manager.
1510 */
1511
1512void
1513dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, isc_uint32_t iolimit);
1514/*%<
1515 *	Set the number of simultaneous file descriptors available for
1516 *	reading and writing masterfiles.
1517 *
1518 * Requires:
1519 *\li	'zmgr' to be a valid zone manager.
1520 *\li	'iolimit' to be positive.
1521 */
1522
1523isc_uint32_t
1524dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr);
1525/*%<
1526 *	Get the number of simultaneous file descriptors available for
1527 *	reading and writing masterfiles.
1528 *
1529 * Requires:
1530 *\li	'zmgr' to be a valid zone manager.
1531 */
1532
1533void
1534dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value);
1535/*%<
1536 *	Set the number of SOA queries sent per second.
1537 *
1538 * Requires:
1539 *\li	'zmgr' to be a valid zone manager
1540 */
1541
1542unsigned int
1543dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr);
1544/*%<
1545 *	Return the number of SOA queries sent per second.
1546 *
1547 * Requires:
1548 *\li	'zmgr' to be a valid zone manager.
1549 */
1550
1551unsigned int
1552dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state);
1553/*%<
1554 *	Returns the number of zones in the specified state.
1555 *
1556 * Requires:
1557 *\li	'zmgr' to be a valid zone manager.
1558 *\li	'state' to be a valid DNS_ZONESTATE_ constant.
1559 */
1560
1561void
1562dns_zonemgr_unreachableadd(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote,
1563			   isc_sockaddr_t *local, isc_time_t *now);
1564/*%<
1565 *	Add the pair of addresses to the unreachable cache.
1566 *
1567 * Requires:
1568 *\li	'zmgr' to be a valid zone manager.
1569 *\li	'remote' to be a valid sockaddr.
1570 *\li	'local' to be a valid sockaddr.
1571 */
1572
1573isc_boolean_t
1574dns_zonemgr_unreachable(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote,
1575			isc_sockaddr_t *local, isc_time_t *now);
1576/*%<
1577 *	Returns ISC_TRUE if the given local/remote address pair
1578 *	is found in the zone maanger's unreachable cache.
1579 *
1580 * Requires:
1581 *\li	'zmgr' to be a valid zone manager.
1582 *\li	'remote' to be a valid sockaddr.
1583 *\li	'local' to be a valid sockaddr.
1584 *\li	'now' != NULL
1585 */
1586
1587void
1588dns_zonemgr_unreachabledel(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote,
1589			   isc_sockaddr_t *local);
1590/*%<
1591 *	Remove the pair of addresses from the unreachable cache.
1592 *
1593 * Requires:
1594 *\li	'zmgr' to be a valid zone manager.
1595 *\li	'remote' to be a valid sockaddr.
1596 *\li	'local' to be a valid sockaddr.
1597 */
1598
1599void
1600dns_zone_forcereload(dns_zone_t *zone);
1601/*%<
1602 *      Force a reload of specified zone.
1603 *
1604 * Requires:
1605 *\li      'zone' to be a valid zone.
1606 */
1607
1608isc_boolean_t
1609dns_zone_isforced(dns_zone_t *zone);
1610/*%<
1611 *      Check if the zone is waiting a forced reload.
1612 *
1613 * Requires:
1614 * \li     'zone' to be a valid zone.
1615 */
1616
1617isc_result_t
1618dns_zone_setstatistics(dns_zone_t *zone, isc_boolean_t on);
1619/*%<
1620 * This function is obsoleted by dns_zone_setrequeststats().
1621 */
1622
1623isc_uint64_t *
1624dns_zone_getstatscounters(dns_zone_t *zone);
1625/*%<
1626 * This function is obsoleted by dns_zone_getrequeststats().
1627 */
1628
1629void
1630dns_zone_setstats(dns_zone_t *zone, isc_stats_t *stats);
1631/*%<
1632 * Set a general zone-maintenance statistics set 'stats' for 'zone'.  This
1633 * function is expected to be called only on zone creation (when necessary).
1634 * Once installed, it cannot be removed or replaced.  Also, there is no
1635 * interface to get the installed stats from the zone; the caller must keep the
1636 * stats to reference (e.g. dump) it later.
1637 *
1638 * Requires:
1639 * \li	'zone' to be a valid zone and does not have a statistics set already
1640 *	installed.
1641 *
1642 *\li	stats is a valid statistics supporting zone statistics counters
1643 *	(see dns/stats.h).
1644 */
1645
1646void
1647dns_zone_setrequeststats(dns_zone_t *zone, isc_stats_t *stats);
1648/*%<
1649 * Set an additional statistics set to zone.  It is attached in the zone
1650 * but is not counted in the zone module; only the caller updates the counters.
1651 *
1652 * Requires:
1653 * \li	'zone' to be a valid zone.
1654 *
1655 *\li	stats is a valid statistics.
1656 */
1657
1658isc_stats_t *
1659dns_zone_getrequeststats(dns_zone_t *zone);
1660/*%<
1661 * Get the additional statistics for zone, if one is installed.
1662 *
1663 * Requires:
1664 * \li	'zone' to be a valid zone.
1665 *
1666 * Returns:
1667 * \li	when available, a pointer to the statistics set installed in zone;
1668 *	otherwise NULL.
1669 */
1670
1671void
1672dns_zone_dialup(dns_zone_t *zone);
1673/*%<
1674 * Perform dialup-time maintenance on 'zone'.
1675 */
1676
1677void
1678dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup);
1679/*%<
1680 * Set the dialup type of 'zone' to 'dialup'.
1681 *
1682 * Requires:
1683 * \li	'zone' to be valid initialised zone.
1684 *\li	'dialup' to be a valid dialup type.
1685 */
1686
1687void
1688dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...)
1689	ISC_FORMAT_PRINTF(3, 4);
1690/*%<
1691 * Log the message 'msg...' at 'level', including text that identifies
1692 * the message as applying to 'zone'.
1693 */
1694
1695void
1696dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level,
1697	      const char *msg, ...) ISC_FORMAT_PRINTF(4, 5);
1698/*%<
1699 * Log the message 'msg...' at 'level', including text that identifies
1700 * the message as applying to 'zone'.
1701 */
1702
1703void
1704dns_zone_name(dns_zone_t *zone, char *buf, size_t len);
1705/*%<
1706 * Return the name of the zone with class and view.
1707 *
1708 * Requires:
1709 *\li	'zone' to be valid.
1710 *\li	'buf' to be non NULL.
1711 */
1712
1713isc_result_t
1714dns_zone_checknames(dns_zone_t *zone, dns_name_t *name, dns_rdata_t *rdata);
1715/*%<
1716 * Check if this record meets the check-names policy.
1717 *
1718 * Requires:
1719 *	'zone' to be valid.
1720 *	'name' to be valid.
1721 *	'rdata' to be valid.
1722 *
1723 * Returns:
1724 *	DNS_R_SUCCESS		passed checks.
1725 *	DNS_R_BADOWNERNAME	failed ownername checks.
1726 *	DNS_R_BADNAME		failed rdata checks.
1727 */
1728
1729void
1730dns_zone_setacache(dns_zone_t *zone, dns_acache_t *acache);
1731/*%<
1732 *	Associate the zone with an additional cache.
1733 *
1734 * Require:
1735 *	'zone' to be a valid zone.
1736 *	'acache' to be a non NULL pointer.
1737 *
1738 * Ensures:
1739 *	'zone' will have a reference to 'acache'
1740 */
1741
1742void
1743dns_zone_setcheckmx(dns_zone_t *zone, dns_checkmxfunc_t checkmx);
1744/*%<
1745 *	Set the post load integrity callback function 'checkmx'.
1746 *	'checkmx' will be called if the MX TARGET is not within the zone.
1747 *
1748 * Require:
1749 *	'zone' to be a valid zone.
1750 */
1751
1752void
1753dns_zone_setchecksrv(dns_zone_t *zone, dns_checkmxfunc_t checksrv);
1754/*%<
1755 *	Set the post load integrity callback function 'checksrv'.
1756 *	'checksrv' will be called if the SRV TARGET is not within the zone.
1757 *
1758 * Require:
1759 *	'zone' to be a valid zone.
1760 */
1761
1762void
1763dns_zone_setcheckns(dns_zone_t *zone, dns_checknsfunc_t checkns);
1764/*%<
1765 *	Set the post load integrity callback function 'checkns'.
1766 *	'checkns' will be called if the NS TARGET is not within the zone.
1767 *
1768 * Require:
1769 *	'zone' to be a valid zone.
1770 */
1771
1772void
1773dns_zone_setnotifydelay(dns_zone_t *zone, isc_uint32_t delay);
1774/*%<
1775 * Set the minimum delay between sets of notify messages.
1776 *
1777 * Requires:
1778 *	'zone' to be valid.
1779 */
1780
1781isc_uint32_t
1782dns_zone_getnotifydelay(dns_zone_t *zone);
1783/*%<
1784 * Get the minimum delay between sets of notify messages.
1785 *
1786 * Requires:
1787 *	'zone' to be valid.
1788 */
1789
1790void
1791dns_zone_setisself(dns_zone_t *zone, dns_isselffunc_t isself, void *arg);
1792/*%<
1793 * Set the isself callback function and argument.
1794 *
1795 * isc_boolean_t
1796 * isself(dns_view_t *myview, dns_tsigkey_t *mykey, isc_netaddr_t *srcaddr,
1797 *	  isc_netaddr_t *destaddr, dns_rdataclass_t rdclass, void *arg);
1798 *
1799 * 'isself' returns ISC_TRUE if a non-recursive query from 'srcaddr' to
1800 * 'destaddr' with optional key 'mykey' for class 'rdclass' would be
1801 * delivered to 'myview'.
1802 */
1803
1804void
1805dns_zone_setnodes(dns_zone_t *zone, isc_uint32_t nodes);
1806/*%<
1807 * Set the number of nodes that will be checked per quantum.
1808 */
1809
1810void
1811dns_zone_setsignatures(dns_zone_t *zone, isc_uint32_t signatures);
1812/*%<
1813 * Set the number of signatures that will be generated per quantum.
1814 */
1815
1816isc_result_t
1817dns_zone_signwithkey(dns_zone_t *zone, dns_secalg_t algorithm,
1818		     isc_uint16_t keyid, isc_boolean_t delete);
1819/*%<
1820 * Initiate/resume signing of the entire zone with the zone DNSKEY(s)
1821 * that match the given algorithm and keyid.
1822 */
1823
1824isc_result_t
1825dns_zone_addnsec3chain(dns_zone_t *zone, dns_rdata_nsec3param_t *nsec3param);
1826/*%<
1827 * Incrementally add a NSEC3 chain that corresponds to 'nsec3param'.
1828 */
1829
1830void
1831dns_zone_setprivatetype(dns_zone_t *zone, dns_rdatatype_t type);
1832dns_rdatatype_t
1833dns_zone_getprivatetype(dns_zone_t *zone);
1834/*
1835 * Get/Set the private record type.  It is expected that these interfaces
1836 * will not be permanent.
1837 */
1838
1839void
1840dns_zone_rekey(dns_zone_t *zone, isc_boolean_t fullsign);
1841/*%<
1842 * Update the zone's DNSKEY set from the key repository.
1843 *
1844 * If 'fullsign' is true, trigger an immediate full signing of
1845 * the zone with the new key.  Otherwise, if there are no keys or
1846 * if the new keys are for algorithms that have already signed the
1847 * zone, then the zone can be re-signed incrementally.
1848 */
1849
1850isc_result_t
1851dns_zone_nscheck(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version,
1852		 unsigned int *errors);
1853/*%
1854 * Check if the name servers for the zone are sane (have address, don't
1855 * refer to CNAMEs/DNAMEs.  The number of constiancy errors detected in
1856 * returned in '*errors'
1857 *
1858 * Requires:
1859 * \li	'zone' to be valid.
1860 * \li	'db' to be valid.
1861 * \li	'version' to be valid or NULL.
1862 * \li	'errors' to be non NULL.
1863 *
1864 * Returns:
1865 * 	ISC_R_SUCCESS if there were no errors examining the zone contents.
1866 */
1867
1868void
1869dns_zone_setadded(dns_zone_t *zone, isc_boolean_t added);
1870/*%
1871 * Sets the value of zone->added, which should be ISC_TRUE for
1872 * zones that were originally added by "rndc addzone".
1873 *
1874 * Requires:
1875 * \li	'zone' to be valid.
1876 */
1877
1878isc_boolean_t
1879dns_zone_getadded(dns_zone_t *zone);
1880/*%
1881 * Returns ISC_TRUE if the zone was originally added at runtime
1882 * using "rndc addzone".
1883 *
1884 * Requires:
1885 * \li	'zone' to be valid.
1886 */
1887
1888isc_result_t
1889dns_zone_dlzpostload(dns_zone_t *zone, dns_db_t *db);
1890/*%
1891 * Load the origin names for a writeable DLZ database.
1892 */
1893
1894isc_result_t
1895dns_zone_synckeyzone(dns_zone_t *zone);
1896/*%
1897 * Force the managed key zone to synchronize, and start the key
1898 * maintenance timer.
1899 */
1900
1901ISC_LANG_ENDDECLS
1902
1903#endif /* DNS_ZONE_H */