lib/dns/include/dns/zone.h

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