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
  39 typedef 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
 121 ISC_LANG_BEGINDECLS
 122
 123 /***
 124  ***    Functions
 125  ***/
 126
 127 isc_result_t
 128 dns_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
 145 void
 146 dns_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
 158 dns_rdataclass_t
 159 dns_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
 167 isc_result_t
 168 dns_zone_getserial2(dns_zone_t *zone, isc_uint32_t *serialp);
 169
 170 isc_uint32_t
 171 dns_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
 187 void
 188 dns_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
 200 void
 201 dns_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
 209 dns_view_t *
 210 dns_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
 218 isc_result_t
 219 dns_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
 232 dns_name_t *
 233 dns_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
 241 isc_result_t
 242 dns_zone_setfile(dns_zone_t *zone, const char *file);
 243
 244 isc_result_t
 245 dns_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
 268 const char *
 269 dns_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
 280 isc_result_t
 281 dns_zone_load(dns_zone_t *zone);
 282
 283 isc_result_t
 284 dns_zone_loadnew(dns_zone_t *zone);
 285
 286 isc_result_t
 287 dns_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
 312 void
 313 dns_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
 323 void
 324 dns_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
 334 void
 335 dns_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
 348 void
 349 dns_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
 360 void
 361 dns_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
 370 isc_result_t
 371 dns_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
 385 void
 386 dns_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
 401 isc_result_t
 402 dns_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
 420 isc_result_t
 421 dns_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
 436 void
 437 dns_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
 445 void
 446 dns_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
 456 void
 457 dns_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
 466 isc_result_t
 467 dns_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
 475 isc_result_t
 476 dns_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
 484 isc_result_t
 485 dns_zone_dumptostream(dns_zone_t *zone, FILE *fd);
 486
 487 isc_result_t
 488 dns_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
 507 isc_result_t
 508 dns_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
 518 void
 519 dns_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
 528 isc_result_t
 529 dns_zone_setmasters(dns_zone_t *zone, const isc_sockaddr_t *masters,
 530                     isc_uint32_t count);
 531 isc_result_t
 532 dns_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
 556 isc_result_t
 557 dns_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
 573 void
 574 dns_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
 582 void
 583 dns_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
 592 unsigned int
 593 dns_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
 601 void
 602 dns_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
 611 unsigned int
 612 dns_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
 620 void
 621 dns_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
 630 void
 631 dns_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
 640 void
 641 dns_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
 650 void
 651 dns_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
 660 isc_result_t
 661 dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 662 isc_result_t
 663 dns_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
 676 isc_sockaddr_t *
 677 dns_zone_getxfrsource4(dns_zone_t *zone);
 678 isc_sockaddr_t *
 679 dns_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
 688 isc_result_t
 689 dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource);
 690 isc_result_t
 691 dns_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
 704 isc_sockaddr_t *
 705 dns_zone_getxfrsource6(dns_zone_t *zone);
 706 isc_sockaddr_t *
 707 dns_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
 716 isc_result_t
 717 dns_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
 729 isc_sockaddr_t *
 730 dns_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
 739 isc_result_t
 740 dns_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
 752 isc_sockaddr_t *
 753 dns_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
 762 void
 763 dns_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
 772 void
 773 dns_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
 782 void
 783 dns_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
 792 void
 793 dns_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
 802 void
 803 dns_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
 812 void
 813 dns_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
 822 dns_acl_t *
 823 dns_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
 835 dns_acl_t *
 836 dns_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
 848 dns_acl_t *
 849 dns_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
 861 dns_acl_t *
 862 dns_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
 874 dns_acl_t *
 875 dns_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
 887 dns_acl_t *
 888 dns_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
 900 void
 901 dns_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
 909 void
 910 dns_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
 918 void
 919 dns_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
 927 void
 928 dns_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
 936 void
 937 dns_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
 945 void
 946 dns_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
 954 isc_boolean_t
 955 dns_zone_getupdatedisabled(dns_zone_t *zone);
 956 /*%<
 957  * Return update disabled.
 958  * Transient unless called when running in isc_task_exclusive() mode.
 959  */
 960
 961 void
 962 dns_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
 970 isc_boolean_t
 971 dns_zone_getzeronosoattl(dns_zone_t *zone);
 972 /*%<
 973  * Return zero-no-soa-ttl status.
 974  */
 975
 976 void
 977 dns_zone_setzeronosoattl(dns_zone_t *zone, isc_boolean_t state);
 978 /*%<
 979  * Set zero-no-soa-ttl status.
 980  */
 981
 982 void
 983 dns_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
 991 dns_severity_t
 992 dns_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
1000 void
1001 dns_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
1009 isc_int32_t
1010 dns_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
1019 isc_result_t
1020 dns_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
1039 void
1040 dns_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
1049 isc_uint32_t
1050 dns_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
1060 void
1061 dns_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
1070 isc_uint32_t
1071 dns_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
1081 isc_result_t
1082 dns_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
1097 char *
1098 dns_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
1107 dns_zonetype_t
1108 dns_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
1116 void
1117 dns_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
1126 void
1127 dns_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
1137 void
1138 dns_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
1146 isc_result_t
1147 dns_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
1172 isc_uint32_t
1173 dns_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
1182 void
1183 dns_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
1192 isc_uint32_t
1193 dns_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
1203 void
1204 dns_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
1213 void
1214 dns_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
1222 void
1223 dns_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
1231 isc_mem_t *
1232 dns_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
1240 dns_zonemgr_t *
1241 dns_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
1249 void
1250 dns_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
1260 isc_uint32_t
1261 dns_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
1269 void
1270 dns_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
1279 isc_uint32_t
1280 dns_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
1288 void
1289 dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype);
1290 /*%<
1291  * Sets zone notify method to "notifytype"
1292  */
1293
1294 isc_result_t
1295 dns_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
1316 isc_result_t
1317 dns_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
1334 isc_result_t
1335 dns_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
1350 isc_result_t
1351 dns_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
1364 const char *
1365 dns_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
1378 isc_result_t
1379 dns_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
1393 isc_result_t
1394 dns_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
1405 isc_result_t
1406 dns_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
1415 isc_result_t
1416 dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr);
1417 /*%<
1418  * Force zone maintenance of all zones managed by 'zmgr' at its
1419  * earliest convenience.
1420  */
1421
1422 void
1423 dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr);
1424 /*%<
1425  * Attempt to start any stalled zone transfers.
1426  */
1427
1428 void
1429 dns_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
1437 void
1438 dns_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
1448 void
1449 dns_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
1460 void
1461 dns_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
1475 void
1476 dns_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
1485 isc_uint32_t
1486 dns_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
1494 void
1495 dns_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
1503 isc_uint32_t
1504 dns_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
1512 void
1513 dns_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
1523 isc_uint32_t
1524 dns_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
1533 void
1534 dns_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
1542 unsigned int
1543 dns_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
1551 unsigned int
1552 dns_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
1561 void
1562 dns_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
1573 isc_boolean_t
1574 dns_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
1587 void
1588 dns_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
1599 void
1600 dns_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
1608 isc_boolean_t
1609 dns_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
1617 isc_result_t
1618 dns_zone_setstatistics(dns_zone_t *zone, isc_boolean_t on);
1619 /*%<
1620  * This function is obsoleted by dns_zone_setrequeststats().
1621  */
1622
1623 isc_uint64_t *
1624 dns_zone_getstatscounters(dns_zone_t *zone);
1625 /*%<
1626  * This function is obsoleted by dns_zone_getrequeststats().
1627  */
1628
1629 void
1630 dns_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
1646 void
1647 dns_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
1658 isc_stats_t *
1659 dns_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
1671 void
1672 dns_zone_dialup(dns_zone_t *zone);
1673 /*%<
1674  * Perform dialup-time maintenance on 'zone'.
1675  */
1676
1677 void
1678 dns_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
1687 void
1688 dns_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
1695 void
1696 dns_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
1703 void
1704 dns_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
1713 isc_result_t
1714 dns_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
1729 void
1730 dns_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
1742 void
1743 dns_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
1752 void
1753 dns_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
1762 void
1763 dns_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
1772 void
1773 dns_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
1781 isc_uint32_t
1782 dns_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
1790 void
1791 dns_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
1804 void
1805 dns_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
1810 void
1811 dns_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
1816 isc_result_t
1817 dns_zone_signwithkey(dns_zone_t *zone, dns_secalg_t algorithm,
1818                      isc_uint16_t keyid, isc_boolean_t deleteit);
1819 /*%<
1820  * Initiate/resume signing of the entire zone with the zone DNSKEY(s)
1821  * that match the given algorithm and keyid.
1822  */
1823
1824 isc_result_t
1825 dns_zone_addnsec3chain(dns_zone_t *zone, dns_rdata_nsec3param_t *nsec3param);
1826 /*%<
1827  * Incrementally add a NSEC3 chain that corresponds to 'nsec3param'.
1828  */
1829
1830 void
1831 dns_zone_setprivatetype(dns_zone_t *zone, dns_rdatatype_t type);
1832 dns_rdatatype_t
1833 dns_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
1839 void
1840 dns_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
1850 isc_result_t
1851 dns_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
1868 void
1869 dns_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
1878 isc_boolean_t
1879 dns_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
1888 isc_result_t
1889 dns_zone_dlzpostload(dns_zone_t *zone, dns_db_t *db);
1890 /*%
1891  * Load the origin names for a writeable DLZ database.
1892  */
1893
1894 isc_result_t
1895 dns_zone_synckeyzone(dns_zone_t *zone);
1896 /*%
1897  * Force the managed key zone to synchronize, and start the key
1898  * maintenance timer.
1899  */
1900
1901 ISC_LANG_ENDDECLS
1902
1903 #endif /* DNS_ZONE_H */