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

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