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

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