1 /* $NetBSD: zone.h,v 1.10 2023/01/25 21:43:30 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 #ifndef DNS_ZONE_H 17 #define DNS_ZONE_H 1 18 19 /*! \file dns/zone.h */ 20 21 /*** 22 *** Imports 23 ***/ 24 25 #include <inttypes.h> 26 #include <stdbool.h> 27 #include <stdio.h> 28 29 #include <isc/formatcheck.h> 30 #include <isc/lang.h> 31 #include <isc/rwlock.h> 32 33 #include <dns/catz.h> 34 #include <dns/master.h> 35 #include <dns/masterdump.h> 36 #include <dns/rdatastruct.h> 37 #include <dns/rpz.h> 38 #include <dns/types.h> 39 #include <dns/zt.h> 40 41 typedef enum { 42 dns_zone_none, 43 dns_zone_primary, 44 dns_zone_secondary, 45 dns_zone_mirror, 46 dns_zone_stub, 47 dns_zone_staticstub, 48 dns_zone_key, 49 dns_zone_dlz, 50 dns_zone_redirect 51 } dns_zonetype_t; 52 53 #ifndef dns_zone_master 54 #define dns_zone_master dns_zone_primary 55 #endif /* dns_zone_master */ 56 57 #ifndef dns_zone_slave 58 #define dns_zone_slave dns_zone_secondary 59 #endif /* dns_zone_slave */ 60 61 typedef enum { 62 dns_zonestat_none = 0, 63 dns_zonestat_terse, 64 dns_zonestat_full 65 } dns_zonestat_level_t; 66 67 typedef enum { 68 DNS_ZONEOPT_MANYERRORS = 1 << 0, /*%< return many errors on load */ 69 DNS_ZONEOPT_IXFRFROMDIFFS = 1 << 1, /*%< calculate differences */ 70 DNS_ZONEOPT_NOMERGE = 1 << 2, /*%< don't merge journal */ 71 DNS_ZONEOPT_CHECKNS = 1 << 3, /*%< check if NS's are addresses */ 72 DNS_ZONEOPT_FATALNS = 1 << 4, /*%< DNS_ZONEOPT_CHECKNS is fatal */ 73 DNS_ZONEOPT_MULTIMASTER = 1 << 5, /*%< this zone has multiple 74 primaries */ 75 DNS_ZONEOPT_USEALTXFRSRC = 1 << 6, /*%< use alternate transfer sources 76 */ 77 DNS_ZONEOPT_CHECKNAMES = 1 << 7, /*%< check-names */ 78 DNS_ZONEOPT_CHECKNAMESFAIL = 1 << 8, /*%< fatal check-name failures */ 79 DNS_ZONEOPT_CHECKWILDCARD = 1 << 9, /*%< check for internal wildcards */ 80 DNS_ZONEOPT_CHECKMX = 1 << 10, /*%< check-mx */ 81 DNS_ZONEOPT_CHECKMXFAIL = 1 << 11, /*%< fatal check-mx failures */ 82 DNS_ZONEOPT_CHECKINTEGRITY = 1 << 12, /*%< perform integrity checks */ 83 DNS_ZONEOPT_CHECKSIBLING = 1 << 13, /*%< perform sibling glue checks */ 84 DNS_ZONEOPT_NOCHECKNS = 1 << 14, /*%< disable IN NS address checks */ 85 DNS_ZONEOPT_WARNMXCNAME = 1 << 15, /*%< warn on MX CNAME check */ 86 DNS_ZONEOPT_IGNOREMXCNAME = 1 << 16, /*%< ignore MX CNAME check */ 87 DNS_ZONEOPT_WARNSRVCNAME = 1 << 17, /*%< warn on SRV CNAME check */ 88 DNS_ZONEOPT_IGNORESRVCNAME = 1 << 18, /*%< ignore SRV CNAME check */ 89 DNS_ZONEOPT_UPDATECHECKKSK = 1 << 19, /*%< check dnskey KSK flag */ 90 DNS_ZONEOPT_TRYTCPREFRESH = 1 << 20, /*%< try tcp refresh on udp failure 91 */ 92 DNS_ZONEOPT_NOTIFYTOSOA = 1 << 21, /*%< Notify the SOA MNAME */ 93 DNS_ZONEOPT_NSEC3TESTZONE = 1 << 22, /*%< nsec3-test-zone */ 94 DNS_ZONEOPT_SECURETOINSECURE = 1 << 23, /*%< dnssec-secure-to-insecure 95 */ 96 DNS_ZONEOPT_DNSKEYKSKONLY = 1 << 24, /*%< dnssec-dnskey-kskonly */ 97 DNS_ZONEOPT_CHECKDUPRR = 1 << 25, /*%< check-dup-records */ 98 DNS_ZONEOPT_CHECKDUPRRFAIL = 1 << 26, /*%< fatal check-dup-records 99 * failures */ 100 DNS_ZONEOPT_CHECKSPF = 1 << 27, /*%< check SPF records */ 101 DNS_ZONEOPT_CHECKTTL = 1 << 28, /*%< check max-zone-ttl */ 102 DNS_ZONEOPT_AUTOEMPTY = 1 << 29, /*%< automatic empty zone */ 103 #ifndef __NetBSD__ 104 DNS_ZONEOPT___MAX = UINT64_MAX, /* trick to make the ENUM 64-bit wide */ 105 #endif 106 } dns_zoneopt_t; 107 108 /* 109 * Zone key maintenance options 110 */ 111 typedef enum { 112 DNS_ZONEKEY_ALLOW = 0x00000001U, /*%< fetch keys on command */ 113 DNS_ZONEKEY_MAINTAIN = 0x00000002U, /*%< publish/sign on schedule */ 114 DNS_ZONEKEY_CREATE = 0x00000004U, /*%< make keys when needed */ 115 DNS_ZONEKEY_FULLSIGN = 0x00000008U, /*%< roll to new keys immediately */ 116 DNS_ZONEKEY_NORESIGN = 0x00000010U, /*%< no automatic resigning */ 117 #ifndef __NetBSD__ 118 DNS_ZONEKEY___MAX = UINT64_MAX, /* trick to make the ENUM 64-bit wide */ 119 #endif 120 } dns_zonekey_t; 121 122 #ifndef DNS_ZONE_MINREFRESH 123 #define DNS_ZONE_MINREFRESH 300 /*%< 5 minutes */ 124 #endif /* ifndef DNS_ZONE_MINREFRESH */ 125 #ifndef DNS_ZONE_MAXREFRESH 126 #define DNS_ZONE_MAXREFRESH 2419200 /*%< 4 weeks */ 127 #endif /* ifndef DNS_ZONE_MAXREFRESH */ 128 #ifndef DNS_ZONE_DEFAULTREFRESH 129 #define DNS_ZONE_DEFAULTREFRESH 3600 /*%< 1 hour */ 130 #endif /* ifndef DNS_ZONE_DEFAULTREFRESH */ 131 #ifndef DNS_ZONE_MINRETRY 132 #define DNS_ZONE_MINRETRY 300 /*%< 5 minutes */ 133 #endif /* ifndef DNS_ZONE_MINRETRY */ 134 #ifndef DNS_ZONE_MAXRETRY 135 #define DNS_ZONE_MAXRETRY 1209600 /*%< 2 weeks */ 136 #endif /* ifndef DNS_ZONE_MAXRETRY */ 137 #ifndef DNS_ZONE_DEFAULTRETRY 138 #define DNS_ZONE_DEFAULTRETRY \ 139 60 /*%< 1 minute, subject to \ 140 * exponential backoff */ 141 #endif /* ifndef DNS_ZONE_DEFAULTRETRY */ 142 143 #define DNS_ZONESTATE_XFERRUNNING 1 144 #define DNS_ZONESTATE_XFERDEFERRED 2 145 #define DNS_ZONESTATE_SOAQUERY 3 146 #define DNS_ZONESTATE_ANY 4 147 #define DNS_ZONESTATE_AUTOMATIC 5 148 149 ISC_LANG_BEGINDECLS 150 151 /*** 152 *** Functions 153 ***/ 154 155 isc_result_t 156 dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx); 157 /*%< 158 * Creates a new empty zone and attach '*zonep' to it. 159 * 160 * Requires: 161 *\li 'zonep' to point to a NULL pointer. 162 *\li 'mctx' to be a valid memory context. 163 * 164 * Ensures: 165 *\li '*zonep' refers to a valid zone. 166 * 167 * Returns: 168 *\li #ISC_R_SUCCESS 169 *\li #ISC_R_NOMEMORY 170 *\li #ISC_R_UNEXPECTED 171 */ 172 173 void 174 dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass); 175 /*%< 176 * Sets the class of a zone. This operation can only be performed 177 * once on a zone. 178 * 179 * Require: 180 *\li 'zone' to be a valid zone. 181 *\li dns_zone_setclass() not to have been called since the zone was 182 * created. 183 *\li 'rdclass' != dns_rdataclass_none. 184 */ 185 186 dns_rdataclass_t 187 dns_zone_getclass(dns_zone_t *zone); 188 /*%< 189 * Returns the current zone class. 190 * 191 * Requires: 192 *\li 'zone' to be a valid zone. 193 */ 194 195 isc_result_t 196 dns_zone_getserial(dns_zone_t *zone, uint32_t *serialp); 197 /*%< 198 * Returns the current serial number of the zone. On success, the SOA 199 * serial of the zone will be copied into '*serialp'. 200 * 201 * Requires: 202 *\li 'zone' to be a valid zone. 203 *\li 'serialp' to be non NULL 204 * 205 * Returns: 206 *\li #ISC_R_SUCCESS 207 *\li #DNS_R_NOTLOADED zone DB is not loaded 208 */ 209 210 void 211 dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type); 212 /*%< 213 * Sets the zone type. This operation can only be performed once on 214 * a zone. 215 * 216 * Requires: 217 *\li 'zone' to be a valid zone. 218 *\li dns_zone_settype() not to have been called since the zone was 219 * created. 220 *\li 'type' != dns_zone_none 221 */ 222 223 void 224 dns_zone_setview(dns_zone_t *zone, dns_view_t *view); 225 /*%< 226 * Associate the zone with a view. 227 * 228 * Require: 229 *\li 'zone' to be a valid zone. 230 */ 231 232 dns_view_t * 233 dns_zone_getview(dns_zone_t *zone); 234 /*%< 235 * Returns the zone's associated view. 236 * 237 * Requires: 238 *\li 'zone' to be a valid zone. 239 */ 240 241 void 242 dns_zone_setviewcommit(dns_zone_t *zone); 243 /*%< 244 * Commit the previous view saved internally via dns_zone_setview(). 245 * 246 * Require: 247 *\li 'zone' to be a valid zone. 248 */ 249 250 void 251 dns_zone_setviewrevert(dns_zone_t *zone); 252 /*%< 253 * Revert the most recent dns_zone_setview() on this zone, 254 * restoring the previous view. 255 * 256 * Require: 257 *\li 'zone' to be a valid zone. 258 */ 259 260 isc_result_t 261 dns_zone_setorigin(dns_zone_t *zone, const dns_name_t *origin); 262 /*%< 263 * Sets the zones origin to 'origin'. 264 * 265 * Require: 266 *\li 'zone' to be a valid zone. 267 *\li 'origin' to be non NULL. 268 * 269 * Returns: 270 *\li #ISC_R_SUCCESS 271 *\li #ISC_R_NOMEMORY 272 */ 273 274 dns_name_t * 275 dns_zone_getorigin(dns_zone_t *zone); 276 /*%< 277 * Returns the value of the origin. 278 * 279 * Require: 280 *\li 'zone' to be a valid zone. 281 */ 282 283 isc_result_t 284 dns_zone_setfile(dns_zone_t *zone, const char *file, dns_masterformat_t format, 285 const dns_master_style_t *style); 286 /*%< 287 * Sets the name of the master file in the format of 'format' from which 288 * the zone loads its database to 'file'. 289 * 290 * For zones that have no associated master file, 'file' will be NULL. 291 * 292 * For zones with persistent databases, the file name 293 * setting is ignored. 294 * 295 * Require: 296 *\li 'zone' to be a valid zone. 297 * 298 * Returns: 299 *\li #ISC_R_NOMEMORY 300 *\li #ISC_R_SUCCESS 301 */ 302 303 const char * 304 dns_zone_getfile(dns_zone_t *zone); 305 /*%< 306 * Gets the name of the zone's master file, if any. 307 * 308 * Requires: 309 *\li 'zone' to be valid initialised zone. 310 * 311 * Returns: 312 *\li Pointer to null-terminated file name, or NULL. 313 */ 314 315 void 316 dns_zone_setmaxrecords(dns_zone_t *zone, uint32_t records); 317 /*%< 318 * Sets the maximum number of records permitted in a zone. 319 * 0 implies unlimited. 320 * 321 * Requires: 322 *\li 'zone' to be valid initialised zone. 323 * 324 * Returns: 325 *\li void 326 */ 327 328 uint32_t 329 dns_zone_getmaxrecords(dns_zone_t *zone); 330 /*%< 331 * Gets the maximum number of records permitted in a zone. 332 * 0 implies unlimited. 333 * 334 * Requires: 335 *\li 'zone' to be valid initialised zone. 336 * 337 * Returns: 338 *\li uint32_t maxrecords. 339 */ 340 341 void 342 dns_zone_setmaxttl(dns_zone_t *zone, uint32_t maxttl); 343 /*%< 344 * Sets the max ttl of the zone. 345 * 346 * Requires: 347 *\li 'zone' to be valid initialised zone. 348 * 349 * Returns: 350 *\li void 351 */ 352 353 dns_ttl_t 354 dns_zone_getmaxttl(dns_zone_t *zone); 355 /*%< 356 * Gets the max ttl of the zone. 357 * 358 * Requires: 359 *\li 'zone' to be valid initialised zone. 360 * 361 * Returns: 362 *\li dns_ttl_t maxttl. 363 */ 364 365 void 366 dns_zone_lock_keyfiles(dns_zone_t *zone); 367 /*%< 368 * Lock associated keyfiles for this zone. 369 * 370 * Require: 371 *\li 'zone' to be a valid zone. 372 */ 373 374 void 375 dns_zone_unlock_keyfiles(dns_zone_t *zone); 376 /*%< 377 * Unlock associated keyfiles for this zone. 378 * 379 * Require: 380 *\li 'zone' to be a valid zone. 381 */ 382 383 isc_result_t 384 dns_zone_load(dns_zone_t *zone, bool newonly); 385 386 isc_result_t 387 dns_zone_loadandthaw(dns_zone_t *zone); 388 389 /*%< 390 * Cause the database to be loaded from its backing store. 391 * Confirm that the minimum requirements for the zone type are 392 * met, otherwise DNS_R_BADZONE is returned. 393 * 394 * If newonly is set dns_zone_load() only loads new zones. 395 * dns_zone_loadandthaw() is similar to dns_zone_load() but will 396 * also re-enable DNS UPDATEs when the load completes. 397 * 398 * Require: 399 *\li 'zone' to be a valid zone. 400 * 401 * Returns: 402 *\li #ISC_R_UNEXPECTED 403 *\li #ISC_R_SUCCESS 404 *\li DNS_R_CONTINUE Incremental load has been queued. 405 *\li DNS_R_UPTODATE The zone has already been loaded based on 406 * file system timestamps. 407 *\li DNS_R_BADZONE 408 *\li Any result value from dns_db_load(). 409 */ 410 411 isc_result_t 412 dns_zone_asyncload(dns_zone_t *zone, bool newonly, dns_zt_zoneloaded_t done, 413 void *arg); 414 /*%< 415 * Cause the database to be loaded from its backing store asynchronously. 416 * Other zone maintenance functions are suspended until this is complete. 417 * When finished, 'done' is called to inform the caller, with 'arg' as 418 * its first argument and 'zone' as its second. (Normally, 'arg' is 419 * expected to point to the zone table but is left undefined for testing 420 * purposes.) 421 * 422 * Require: 423 *\li 'zone' to be a valid zone. 424 * 425 * Returns: 426 *\li #ISC_R_ALREADYRUNNING 427 *\li #ISC_R_SUCCESS 428 *\li #ISC_R_FAILURE 429 *\li #ISC_R_NOMEMORY 430 */ 431 432 bool 433 dns__zone_loadpending(dns_zone_t *zone); 434 /*%< 435 * Indicates whether the zone is waiting to be loaded asynchronously. 436 * (Not currently intended for use outside of this module and associated 437 * tests.) 438 */ 439 440 void 441 dns_zone_attach(dns_zone_t *source, dns_zone_t **target); 442 /*%< 443 * Attach '*target' to 'source' incrementing its external 444 * reference count. 445 * 446 * Require: 447 *\li 'zone' to be a valid zone. 448 *\li 'target' to be non NULL and '*target' to be NULL. 449 */ 450 451 void 452 dns_zone_detach(dns_zone_t **zonep); 453 /*%< 454 * Detach from a zone decrementing its external reference count. 455 * If this was the last external reference to the zone it will be 456 * shut down and eventually freed. 457 * 458 * Require: 459 *\li 'zonep' to point to a valid zone. 460 */ 461 462 void 463 dns_zone_iattach(dns_zone_t *source, dns_zone_t **target); 464 /*%< 465 * Attach '*target' to 'source' incrementing its internal 466 * reference count. This is intended for use by operations 467 * such as zone transfers that need to prevent the zone 468 * object from being freed but not from shutting down. 469 * 470 * Require: 471 *\li The caller is running in the context of the zone's task. 472 *\li 'zone' to be a valid zone. 473 *\li 'target' to be non NULL and '*target' to be NULL. 474 */ 475 476 void 477 dns_zone_idetach(dns_zone_t **zonep); 478 /*%< 479 * Detach from a zone decrementing its internal reference count. 480 * If there are no more internal or external references to the 481 * zone, it will be freed. 482 * 483 * Require: 484 *\li The caller is running in the context of the zone's task. 485 *\li 'zonep' to point to a valid zone. 486 */ 487 488 isc_result_t 489 dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp); 490 /*%< 491 * Attach '*dbp' to the database to if it exists otherwise 492 * return DNS_R_NOTLOADED. 493 * 494 * Require: 495 *\li 'zone' to be a valid zone. 496 *\li 'dbp' to be != NULL && '*dbp' == NULL. 497 * 498 * Returns: 499 *\li #ISC_R_SUCCESS 500 *\li DNS_R_NOTLOADED 501 */ 502 503 void 504 dns_zone_setdb(dns_zone_t *zone, dns_db_t *db); 505 /*%< 506 * Sets the zone database to 'db'. 507 * 508 * This function is expected to be used to configure a zone with a 509 * database which is not loaded from a file or zone transfer. 510 * It can be used for a general purpose zone, but right now its use 511 * is limited to static-stub zones to avoid possible undiscovered 512 * problems in the general cases. 513 * 514 * Require: 515 *\li 'zone' to be a valid zone of static-stub. 516 *\li zone doesn't have a database. 517 */ 518 519 void 520 dns_zone_setdbtype(dns_zone_t *zone, unsigned int dbargc, 521 const char *const *dbargv); 522 /*%< 523 * Sets the database type to dbargv[0] and database arguments 524 * to subsequent dbargv elements. 525 * 'db_type' is not checked to see if it is a valid database type. 526 * 527 * Require: 528 *\li 'zone' to be a valid zone. 529 *\li 'database' to be non NULL. 530 *\li 'dbargc' to be >= 1 531 *\li 'dbargv' to point to dbargc NULL-terminated strings 532 */ 533 534 isc_result_t 535 dns_zone_getdbtype(dns_zone_t *zone, char ***argv, isc_mem_t *mctx); 536 /*%< 537 * Returns the current dbtype. isc_mem_free() should be used 538 * to free 'argv' after use. 539 * 540 * Require: 541 *\li 'zone' to be a valid zone. 542 *\li 'argv' to be non NULL and *argv to be NULL. 543 *\li 'mctx' to be valid. 544 * 545 * Returns: 546 *\li #ISC_R_NOMEMORY 547 *\li #ISC_R_SUCCESS 548 */ 549 550 void 551 dns_zone_markdirty(dns_zone_t *zone); 552 /*%< 553 * Mark a zone as 'dirty'. 554 * 555 * Require: 556 *\li 'zone' to be a valid zone. 557 */ 558 559 void 560 dns_zone_expire(dns_zone_t *zone); 561 /*%< 562 * Mark the zone as expired. If the zone requires dumping cause it to 563 * be initiated. Set the refresh and retry intervals to there default 564 * values and unload the zone. 565 * 566 * Require 567 *\li 'zone' to be a valid zone. 568 */ 569 570 void 571 dns_zone_refresh(dns_zone_t *zone); 572 /*%< 573 * Initiate zone up to date checks. The zone must already be being 574 * managed. 575 * 576 * Require 577 *\li 'zone' to be a valid zone. 578 */ 579 580 isc_result_t 581 dns_zone_flush(dns_zone_t *zone); 582 /*%< 583 * Write the zone to database if there are uncommitted changes. 584 * 585 * Require: 586 *\li 'zone' to be a valid zone. 587 */ 588 589 isc_result_t 590 dns_zone_dump(dns_zone_t *zone); 591 /*%< 592 * Write the zone to database. 593 * 594 * Require: 595 *\li 'zone' to be a valid zone. 596 */ 597 598 isc_result_t 599 dns_zone_dumptostream(dns_zone_t *zone, FILE *fd, dns_masterformat_t format, 600 const dns_master_style_t *style, 601 const uint32_t rawversion); 602 /*%< 603 * Write the zone to stream 'fd' in the specified 'format'. 604 * If the 'format' is dns_masterformat_text (RFC1035), 'style' also 605 * specifies the file style (e.g., &dns_master_style_default). 606 * 607 * dns_zone_dumptostream() is a backward-compatible form of 608 * dns_zone_dumptostream2(), which always uses the dns_masterformat_text 609 * format and the dns_master_style_default style. 610 * 611 * dns_zone_dumptostream2() is a backward-compatible form of 612 * dns_zone_dumptostream3(), which always uses the current 613 * default raw file format version. 614 * 615 * Note that dns_zone_dumptostream3() is the most flexible form. It 616 * can also provide the functionality of dns_zone_fulldumptostream(). 617 * 618 * Require: 619 *\li 'zone' to be a valid zone. 620 *\li 'fd' to be a stream open for writing. 621 */ 622 623 void 624 dns_zone_maintenance(dns_zone_t *zone); 625 /*%< 626 * Perform regular maintenance on the zone. This is called as a 627 * result of a zone being managed. 628 * 629 * Require 630 *\li 'zone' to be a valid zone. 631 */ 632 633 isc_result_t 634 dns_zone_setprimaries(dns_zone_t *zone, const isc_sockaddr_t *primaries, 635 uint32_t count); 636 isc_result_t 637 dns_zone_setprimarieswithkeys(dns_zone_t *zone, const isc_sockaddr_t *primaries, 638 dns_name_t **keynames, uint32_t count); 639 /*%< 640 * Set the list of master servers for the zone. 641 * 642 * Require: 643 *\li 'zone' to be a valid zone. 644 *\li 'primaries' array of isc_sockaddr_t with port set or NULL. 645 *\li 'count' the number of primaries. 646 *\li 'keynames' array of dns_name_t's for tsig keys or NULL. 647 * 648 *\li If 'primaries' is NULL then 'count' must be zero. 649 * 650 * Returns: 651 *\li #ISC_R_SUCCESS 652 *\li #ISC_R_NOMEMORY 653 *\li Any result dns_name_dup() can return, if keynames!=NULL 654 */ 655 656 isc_result_t 657 dns_zone_setparentals(dns_zone_t *zone, const isc_sockaddr_t *parentals, 658 dns_name_t **keynames, uint32_t count); 659 /*%< 660 * Set the list of parental agents for the zone. 661 * 662 * Require: 663 *\li 'zone' to be a valid zone. 664 *\li 'parentals' array of isc_sockaddr_t with port set or NULL. 665 *\li 'count' the number of primaries. 666 *\li 'keynames' array of dns_name_t's for tsig keys or NULL. 667 * 668 *\li If 'parentals' is NULL then 'count' must be zero. 669 * 670 * Returns: 671 *\li #ISC_R_SUCCESS 672 *\li #ISC_R_NOMEMORY 673 *\li Any result dns_name_dup() can return, if keynames!=NULL 674 */ 675 676 isc_result_t 677 dns_zone_setalsonotify(dns_zone_t *zone, const isc_sockaddr_t *notify, 678 uint32_t count); 679 isc_result_t 680 dns_zone_setalsonotifywithkeys(dns_zone_t *zone, const isc_sockaddr_t *notify, 681 dns_name_t **keynames, uint32_t count); 682 isc_result_t 683 dns_zone_setalsonotifydscpkeys(dns_zone_t *zone, const isc_sockaddr_t *notify, 684 const isc_dscp_t *dscps, dns_name_t **keynames, 685 uint32_t count); 686 /*%< 687 * Set the list of additional servers to be notified when 688 * a zone changes. To clear the list use 'count = 0'. 689 * 690 * dns_zone_alsonotifywithkeys() allows each notify address to 691 * be associated with a TSIG key. 692 * 693 * Require: 694 *\li 'zone' to be a valid zone. 695 *\li 'notify' to be non-NULL if count != 0. 696 *\li 'count' to be the number of notifiees. 697 * 698 * Returns: 699 *\li #ISC_R_SUCCESS 700 *\li #ISC_R_NOMEMORY 701 */ 702 703 void 704 dns_zone_unload(dns_zone_t *zone); 705 /*%< 706 * detach the database from the zone structure. 707 * 708 * Require: 709 *\li 'zone' to be a valid zone. 710 */ 711 712 dns_kasp_t * 713 dns_zone_getkasp(dns_zone_t *zone); 714 /*%< 715 * Returns the current kasp. 716 * 717 * Require: 718 *\li 'zone' to be a valid zone. 719 */ 720 721 void 722 dns_zone_setkasp(dns_zone_t *zone, dns_kasp_t *kasp); 723 /*%< 724 * Set kasp for zone. If a kasp is already set, it will be detached. 725 * 726 * Requires: 727 *\li 'zone' to be a valid zone. 728 */ 729 730 void 731 dns_zone_setoption(dns_zone_t *zone, dns_zoneopt_t option, bool value); 732 /*%< 733 * Set the given options on ('value' == true) or off 734 * ('value' == #false). 735 * 736 * Require: 737 *\li 'zone' to be a valid zone. 738 */ 739 740 dns_zoneopt_t 741 dns_zone_getoptions(dns_zone_t *zone); 742 /*%< 743 * Returns the current zone options. 744 * 745 * Require: 746 *\li 'zone' to be a valid zone. 747 */ 748 749 void 750 dns_zone_setkeyopt(dns_zone_t *zone, unsigned int option, bool value); 751 /*%< 752 * Set key options on ('value' == true) or off ('value' == 753 * #false). 754 * 755 * Require: 756 *\li 'zone' to be a valid zone. 757 */ 758 759 unsigned int 760 dns_zone_getkeyopts(dns_zone_t *zone); 761 /*%< 762 * Returns the current zone key options. 763 * 764 * Require: 765 *\li 'zone' to be a valid zone. 766 */ 767 768 void 769 dns_zone_setminrefreshtime(dns_zone_t *zone, uint32_t val); 770 /*%< 771 * Set the minimum refresh time. 772 * 773 * Requires: 774 *\li 'zone' is valid. 775 *\li val > 0. 776 */ 777 778 void 779 dns_zone_setmaxrefreshtime(dns_zone_t *zone, uint32_t val); 780 /*%< 781 * Set the maximum refresh time. 782 * 783 * Requires: 784 *\li 'zone' is valid. 785 *\li val > 0. 786 */ 787 788 void 789 dns_zone_setminretrytime(dns_zone_t *zone, uint32_t val); 790 /*%< 791 * Set the minimum retry time. 792 * 793 * Requires: 794 *\li 'zone' is valid. 795 *\li val > 0. 796 */ 797 798 void 799 dns_zone_setmaxretrytime(dns_zone_t *zone, uint32_t val); 800 /*%< 801 * Set the maximum retry time. 802 * 803 * Requires: 804 *\li 'zone' is valid. 805 * val > 0. 806 */ 807 808 isc_result_t 809 dns_zone_setxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 810 isc_result_t 811 dns_zone_setaltxfrsource4(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 812 /*%< 813 * Set the source address to be used in IPv4 zone transfers. 814 * 815 * Require: 816 *\li 'zone' to be a valid zone. 817 *\li 'xfrsource' to contain the address. 818 * 819 * Returns: 820 *\li #ISC_R_SUCCESS 821 */ 822 823 isc_sockaddr_t * 824 dns_zone_getxfrsource4(dns_zone_t *zone); 825 isc_sockaddr_t * 826 dns_zone_getaltxfrsource4(dns_zone_t *zone); 827 /*%< 828 * Returns the source address set by a previous dns_zone_setxfrsource4 829 * call, or the default of inaddr_any, port 0. 830 * 831 * Require: 832 *\li 'zone' to be a valid zone. 833 */ 834 835 isc_result_t 836 dns_zone_setxfrsource4dscp(dns_zone_t *zone, isc_dscp_t dscp); 837 isc_result_t 838 dns_zone_setaltxfrsource4dscp(dns_zone_t *zone, isc_dscp_t dscp); 839 /*%< 840 * Set the DSCP value associated with the transfer/alt-transfer source. 841 * 842 * Require: 843 *\li 'zone' to be a valid zone. 844 * 845 * Returns: 846 *\li #ISC_R_SUCCESS 847 */ 848 849 isc_dscp_t 850 dns_zone_getxfrsource4dscp(dns_zone_t *zone); 851 isc_dscp_t 852 dns_zone_getaltxfrsource4dscp(dns_zone_t *zone); 853 /*%/ 854 * Get the DSCP value associated with the transfer/alt-transfer source. 855 * 856 * Require: 857 *\li 'zone' to be a valid zone. 858 */ 859 860 isc_result_t 861 dns_zone_setxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 862 isc_result_t 863 dns_zone_setaltxfrsource6(dns_zone_t *zone, const isc_sockaddr_t *xfrsource); 864 /*%< 865 * Set the source address to be used in IPv6 zone transfers. 866 * 867 * Require: 868 *\li 'zone' to be a valid zone. 869 *\li 'xfrsource' to contain the address. 870 * 871 * Returns: 872 *\li #ISC_R_SUCCESS 873 */ 874 875 isc_sockaddr_t * 876 dns_zone_getxfrsource6(dns_zone_t *zone); 877 isc_sockaddr_t * 878 dns_zone_getaltxfrsource6(dns_zone_t *zone); 879 /*%< 880 * Returns the source address set by a previous dns_zone_setxfrsource6 881 * call, or the default of in6addr_any, port 0. 882 * 883 * Require: 884 *\li 'zone' to be a valid zone. 885 */ 886 887 isc_dscp_t 888 dns_zone_getxfrsource6dscp(dns_zone_t *zone); 889 isc_dscp_t 890 dns_zone_getaltxfrsource6dscp(dns_zone_t *zone); 891 /*%/ 892 * Get the DSCP value associated with the transfer/alt-transfer source. 893 * 894 * Require: 895 *\li 'zone' to be a valid zone. 896 */ 897 898 isc_result_t 899 dns_zone_setxfrsource6dscp(dns_zone_t *zone, isc_dscp_t dscp); 900 isc_result_t 901 dns_zone_setaltxfrsource6dscp(dns_zone_t *zone, isc_dscp_t dscp); 902 /*%< 903 * Set the DSCP value associated with the transfer/alt-transfer source. 904 * 905 * Require: 906 *\li 'zone' to be a valid zone. 907 * 908 * Returns: 909 *\li #ISC_R_SUCCESS 910 */ 911 912 isc_result_t 913 dns_zone_setparentalsrc4(dns_zone_t *zone, const isc_sockaddr_t *parentalsrc); 914 /*%< 915 * Set the source address to be used with IPv4 parental DS queries. 916 * 917 * Require: 918 *\li 'zone' to be a valid zone. 919 *\li 'parentalsrc' to contain the address. 920 * 921 * Returns: 922 *\li #ISC_R_SUCCESS 923 */ 924 925 isc_sockaddr_t * 926 dns_zone_getparentalsrc4(dns_zone_t *zone); 927 /*%< 928 * Returns the source address set by a previous dns_zone_setparentalsrc4 929 * call, or the default of inaddr_any, port 0. 930 * 931 * Require: 932 *\li 'zone' to be a valid zone. 933 */ 934 935 isc_dscp_t 936 dns_zone_getparentalsrc4dscp(dns_zone_t *zone); 937 /*%/ 938 * Get the DSCP value associated with the IPv4 parental source. 939 * 940 * Require: 941 *\li 'zone' to be a valid zone. 942 */ 943 944 isc_result_t 945 dns_zone_setparentalsrc4dscp(dns_zone_t *zone, isc_dscp_t dscp); 946 /*%< 947 * Set the DSCP value associated with the IPv4 parental source. 948 * 949 * Require: 950 *\li 'zone' to be a valid zone. 951 * 952 * Returns: 953 *\li #ISC_R_SUCCESS 954 */ 955 956 isc_result_t 957 dns_zone_setparentalsrc6(dns_zone_t *zone, const isc_sockaddr_t *parentalsrc); 958 /*%< 959 * Set the source address to be used with IPv6 parental DS queries. 960 * 961 * Require: 962 *\li 'zone' to be a valid zone. 963 *\li 'parentalsrc' to contain the address. 964 * 965 * Returns: 966 *\li #ISC_R_SUCCESS 967 */ 968 969 isc_sockaddr_t * 970 dns_zone_getparentalsrc6(dns_zone_t *zone); 971 /*%< 972 * Returns the source address set by a previous dns_zone_setparentalsrc6 973 * call, or the default of in6addr_any, port 0. 974 * 975 * Require: 976 *\li 'zone' to be a valid zone. 977 */ 978 979 isc_dscp_t 980 dns_zone_getparentalsrc6dscp(dns_zone_t *zone); 981 /*%/ 982 * Get the DSCP value associated with the IPv6 parental source. 983 * 984 * Require: 985 *\li 'zone' to be a valid zone. 986 */ 987 988 isc_result_t 989 dns_zone_setparentalsrc6dscp(dns_zone_t *zone, isc_dscp_t dscp); 990 /*%< 991 * Set the DSCP value associated with the IPv6 parental source. 992 * 993 * Require: 994 *\li 'zone' to be a valid zone. 995 * 996 * Returns: 997 *\li #ISC_R_SUCCESS 998 */ 999 1000 isc_result_t 1001 dns_zone_setnotifysrc4(dns_zone_t *zone, const isc_sockaddr_t *notifysrc); 1002 /*%< 1003 * Set the source address to be used with IPv4 NOTIFY messages. 1004 * 1005 * Require: 1006 *\li 'zone' to be a valid zone. 1007 *\li 'notifysrc' to contain the address. 1008 * 1009 * Returns: 1010 *\li #ISC_R_SUCCESS 1011 */ 1012 1013 isc_sockaddr_t * 1014 dns_zone_getnotifysrc4(dns_zone_t *zone); 1015 /*%< 1016 * Returns the source address set by a previous dns_zone_setnotifysrc4 1017 * call, or the default of inaddr_any, port 0. 1018 * 1019 * Require: 1020 *\li 'zone' to be a valid zone. 1021 */ 1022 1023 isc_dscp_t 1024 dns_zone_getnotifysrc4dscp(dns_zone_t *zone); 1025 /*%/ 1026 * Get the DSCP value associated with the IPv4 notify source. 1027 * 1028 * Require: 1029 *\li 'zone' to be a valid zone. 1030 */ 1031 1032 isc_result_t 1033 dns_zone_setnotifysrc4dscp(dns_zone_t *zone, isc_dscp_t dscp); 1034 /*%< 1035 * Set the DSCP value associated with the IPv4 notify source. 1036 * 1037 * Require: 1038 *\li 'zone' to be a valid zone. 1039 * 1040 * Returns: 1041 *\li #ISC_R_SUCCESS 1042 */ 1043 1044 isc_result_t 1045 dns_zone_setnotifysrc6(dns_zone_t *zone, const isc_sockaddr_t *notifysrc); 1046 /*%< 1047 * Set the source address to be used with IPv6 NOTIFY messages. 1048 * 1049 * Require: 1050 *\li 'zone' to be a valid zone. 1051 *\li 'notifysrc' to contain the address. 1052 * 1053 * Returns: 1054 *\li #ISC_R_SUCCESS 1055 */ 1056 1057 isc_sockaddr_t * 1058 dns_zone_getnotifysrc6(dns_zone_t *zone); 1059 /*%< 1060 * Returns the source address set by a previous dns_zone_setnotifysrc6 1061 * call, or the default of in6addr_any, port 0. 1062 * 1063 * Require: 1064 *\li 'zone' to be a valid zone. 1065 */ 1066 1067 isc_dscp_t 1068 dns_zone_getnotifysrc6dscp(dns_zone_t *zone); 1069 /*%/ 1070 * Get the DSCP value associated with the IPv6 notify source. 1071 * 1072 * Require: 1073 *\li 'zone' to be a valid zone. 1074 */ 1075 1076 isc_result_t 1077 dns_zone_setnotifysrc6dscp(dns_zone_t *zone, isc_dscp_t dscp); 1078 /*%< 1079 * Set the DSCP value associated with the IPv6 notify source. 1080 * 1081 * Require: 1082 *\li 'zone' to be a valid zone. 1083 * 1084 * Returns: 1085 *\li #ISC_R_SUCCESS 1086 */ 1087 1088 void 1089 dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl); 1090 /*%< 1091 * Sets the notify acl list for the zone. 1092 * 1093 * Require: 1094 *\li 'zone' to be a valid zone. 1095 *\li 'acl' to be a valid acl. 1096 */ 1097 1098 void 1099 dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl); 1100 /*%< 1101 * Sets the query acl list for the zone. 1102 * 1103 * Require: 1104 *\li 'zone' to be a valid zone. 1105 *\li 'acl' to be a valid acl. 1106 */ 1107 1108 void 1109 dns_zone_setqueryonacl(dns_zone_t *zone, dns_acl_t *acl); 1110 /*%< 1111 * Sets the query-on acl list for the zone. 1112 * 1113 * Require: 1114 *\li 'zone' to be a valid zone. 1115 *\li 'acl' to be a valid acl. 1116 */ 1117 1118 void 1119 dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl); 1120 /*%< 1121 * Sets the update acl list for the zone. 1122 * 1123 * Require: 1124 *\li 'zone' to be a valid zone. 1125 *\li 'acl' to be valid acl. 1126 */ 1127 1128 void 1129 dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl); 1130 /*%< 1131 * Sets the forward unsigned updates acl list for the zone. 1132 * 1133 * Require: 1134 *\li 'zone' to be a valid zone. 1135 *\li 'acl' to be valid acl. 1136 */ 1137 1138 void 1139 dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl); 1140 /*%< 1141 * Sets the transfer acl list for the zone. 1142 * 1143 * Require: 1144 *\li 'zone' to be a valid zone. 1145 *\li 'acl' to be valid acl. 1146 */ 1147 1148 dns_acl_t * 1149 dns_zone_getnotifyacl(dns_zone_t *zone); 1150 /*%< 1151 * Returns the current notify acl or NULL. 1152 * 1153 * Require: 1154 *\li 'zone' to be a valid zone. 1155 * 1156 * Returns: 1157 *\li acl a pointer to the acl. 1158 *\li NULL 1159 */ 1160 1161 dns_acl_t * 1162 dns_zone_getqueryacl(dns_zone_t *zone); 1163 /*%< 1164 * Returns the current query acl or NULL. 1165 * 1166 * Require: 1167 *\li 'zone' to be a valid zone. 1168 * 1169 * Returns: 1170 *\li acl a pointer to the acl. 1171 *\li NULL 1172 */ 1173 1174 dns_acl_t * 1175 dns_zone_getqueryonacl(dns_zone_t *zone); 1176 /*%< 1177 * Returns the current query-on acl or NULL. 1178 * 1179 * Require: 1180 *\li 'zone' to be a valid zone. 1181 * 1182 * Returns: 1183 *\li acl a pointer to the acl. 1184 *\li NULL 1185 */ 1186 1187 dns_acl_t * 1188 dns_zone_getupdateacl(dns_zone_t *zone); 1189 /*%< 1190 * Returns the current update acl or NULL. 1191 * 1192 * Require: 1193 *\li 'zone' to be a valid zone. 1194 * 1195 * Returns: 1196 *\li acl a pointer to the acl. 1197 *\li NULL 1198 */ 1199 1200 dns_acl_t * 1201 dns_zone_getforwardacl(dns_zone_t *zone); 1202 /*%< 1203 * Returns the current forward unsigned updates acl or NULL. 1204 * 1205 * Require: 1206 *\li 'zone' to be a valid zone. 1207 * 1208 * Returns: 1209 *\li acl a pointer to the acl. 1210 *\li NULL 1211 */ 1212 1213 dns_acl_t * 1214 dns_zone_getxfracl(dns_zone_t *zone); 1215 /*%< 1216 * Returns the current transfer acl or NULL. 1217 * 1218 * Require: 1219 *\li 'zone' to be a valid zone. 1220 * 1221 * Returns: 1222 *\li acl a pointer to the acl. 1223 *\li NULL 1224 */ 1225 1226 void 1227 dns_zone_clearupdateacl(dns_zone_t *zone); 1228 /*%< 1229 * Clear the current update acl. 1230 * 1231 * Require: 1232 *\li 'zone' to be a valid zone. 1233 */ 1234 1235 void 1236 dns_zone_clearforwardacl(dns_zone_t *zone); 1237 /*%< 1238 * Clear the current forward unsigned updates acl. 1239 * 1240 * Require: 1241 *\li 'zone' to be a valid zone. 1242 */ 1243 1244 void 1245 dns_zone_clearnotifyacl(dns_zone_t *zone); 1246 /*%< 1247 * Clear the current notify acl. 1248 * 1249 * Require: 1250 *\li 'zone' to be a valid zone. 1251 */ 1252 1253 void 1254 dns_zone_clearqueryacl(dns_zone_t *zone); 1255 /*%< 1256 * Clear the current query acl. 1257 * 1258 * Require: 1259 *\li 'zone' to be a valid zone. 1260 */ 1261 1262 void 1263 dns_zone_clearqueryonacl(dns_zone_t *zone); 1264 /*%< 1265 * Clear the current query-on acl. 1266 * 1267 * Require: 1268 *\li 'zone' to be a valid zone. 1269 */ 1270 1271 void 1272 dns_zone_clearxfracl(dns_zone_t *zone); 1273 /*%< 1274 * Clear the current transfer acl. 1275 * 1276 * Require: 1277 *\li 'zone' to be a valid zone. 1278 */ 1279 1280 bool 1281 dns_zone_getupdatedisabled(dns_zone_t *zone); 1282 /*%< 1283 * Return update disabled. 1284 * Transient unless called when running in isc_task_exclusive() mode. 1285 */ 1286 1287 void 1288 dns_zone_setupdatedisabled(dns_zone_t *zone, bool state); 1289 /*%< 1290 * Set update disabled. 1291 * Should only be called only when running in isc_task_exclusive() mode. 1292 * Failure to do so may result in updates being committed after the 1293 * call has been made. 1294 */ 1295 1296 bool 1297 dns_zone_getzeronosoattl(dns_zone_t *zone); 1298 /*%< 1299 * Return zero-no-soa-ttl status. 1300 */ 1301 1302 void 1303 dns_zone_setzeronosoattl(dns_zone_t *zone, bool state); 1304 /*%< 1305 * Set zero-no-soa-ttl status. 1306 */ 1307 1308 void 1309 dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity); 1310 /*%< 1311 * Set the severity of name checking when loading a zone. 1312 * 1313 * Require: 1314 * \li 'zone' to be a valid zone. 1315 */ 1316 1317 dns_severity_t 1318 dns_zone_getchecknames(dns_zone_t *zone); 1319 /*%< 1320 * Return the current severity of name checking. 1321 * 1322 * Require: 1323 *\li 'zone' to be a valid zone. 1324 */ 1325 1326 void 1327 dns_zone_setjournalsize(dns_zone_t *zone, int32_t size); 1328 /*%< 1329 * Sets the journal size for the zone. 1330 * 1331 * Requires: 1332 *\li 'zone' to be a valid zone. 1333 */ 1334 1335 int32_t 1336 dns_zone_getjournalsize(dns_zone_t *zone); 1337 /*%< 1338 * Return the journal size as set with a previous call to 1339 * dns_zone_setjournalsize(). 1340 * 1341 * Requires: 1342 *\li 'zone' to be a valid zone. 1343 */ 1344 1345 isc_result_t 1346 dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from, 1347 isc_sockaddr_t *to, dns_message_t *msg); 1348 /*%< 1349 * Tell the zone that it has received a NOTIFY message from another 1350 * server. This may cause some zone maintenance activity to occur. 1351 * 1352 * Requires: 1353 *\li 'zone' to be a valid zone. 1354 *\li '*from' to contain the address of the server from which 'msg' 1355 * was received. 1356 *\li 'msg' a message with opcode NOTIFY and qr clear. 1357 * 1358 * Returns: 1359 *\li DNS_R_REFUSED 1360 *\li DNS_R_NOTIMP 1361 *\li DNS_R_FORMERR 1362 *\li DNS_R_SUCCESS 1363 */ 1364 1365 void 1366 dns_zone_setmaxxfrin(dns_zone_t *zone, uint32_t maxxfrin); 1367 /*%< 1368 * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR) 1369 * of this zone will use before being aborted. 1370 * 1371 * Requires: 1372 * \li 'zone' to be valid initialised zone. 1373 */ 1374 1375 uint32_t 1376 dns_zone_getmaxxfrin(dns_zone_t *zone); 1377 /*%< 1378 * Returns the maximum transfer time for this zone. This will be 1379 * either the value set by the last call to dns_zone_setmaxxfrin() or 1380 * the default value of 1 hour. 1381 * 1382 * Requires: 1383 *\li 'zone' to be valid initialised zone. 1384 */ 1385 1386 void 1387 dns_zone_setmaxxfrout(dns_zone_t *zone, uint32_t maxxfrout); 1388 /*%< 1389 * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR) 1390 * of this zone will use before being aborted. 1391 * 1392 * Requires: 1393 * \li 'zone' to be valid initialised zone. 1394 */ 1395 1396 uint32_t 1397 dns_zone_getmaxxfrout(dns_zone_t *zone); 1398 /*%< 1399 * Returns the maximum transfer time for this zone. This will be 1400 * either the value set by the last call to dns_zone_setmaxxfrout() or 1401 * the default value of 1 hour. 1402 * 1403 * Requires: 1404 *\li 'zone' to be valid initialised zone. 1405 */ 1406 1407 isc_result_t 1408 dns_zone_setjournal(dns_zone_t *zone, const char *myjournal); 1409 /*%< 1410 * Sets the filename used for journaling updates / IXFR transfers. 1411 * The default journal name is set by dns_zone_setfile() to be 1412 * "file.jnl". If 'myjournal' is NULL, the zone will have no 1413 * journal name. 1414 * 1415 * Requires: 1416 *\li 'zone' to be a valid zone. 1417 * 1418 * Returns: 1419 *\li #ISC_R_SUCCESS 1420 *\li #ISC_R_NOMEMORY 1421 */ 1422 1423 char * 1424 dns_zone_getjournal(dns_zone_t *zone); 1425 /*%< 1426 * Returns the journal name associated with this zone. 1427 * If no journal has been set this will be NULL. 1428 * 1429 * Requires: 1430 *\li 'zone' to be valid initialised zone. 1431 */ 1432 1433 dns_zonetype_t 1434 dns_zone_gettype(dns_zone_t *zone); 1435 /*%< 1436 * Returns the type of the zone (master/slave/etc.) 1437 * 1438 * Requires: 1439 *\li 'zone' to be valid initialised zone. 1440 */ 1441 1442 dns_zonetype_t 1443 dns_zone_getredirecttype(dns_zone_t *zone); 1444 /*%< 1445 * Returns whether the redirect zone is configured as a master or a 1446 * slave zone. 1447 * 1448 * Requires: 1449 *\li 'zone' to be valid initialised zone. 1450 *\li 'zone' to be a redirect zone. 1451 * 1452 * Returns: 1453 *\li 'dns_zone_primary' 1454 *\li 'dns_zone_secondary' 1455 */ 1456 1457 void 1458 dns_zone_settask(dns_zone_t *zone, isc_task_t *task); 1459 /*%< 1460 * Give a zone a task to work with. Any current task will be detached. 1461 * 1462 * Requires: 1463 *\li 'zone' to be valid. 1464 *\li 'task' to be valid. 1465 */ 1466 1467 void 1468 dns_zone_gettask(dns_zone_t *zone, isc_task_t **target); 1469 /*%< 1470 * Attach '*target' to the zone's task. 1471 * 1472 * Requires: 1473 *\li 'zone' to be valid initialised zone. 1474 *\li 'zone' to have a task. 1475 *\li 'target' to be != NULL && '*target' == NULL. 1476 */ 1477 1478 void 1479 dns_zone_notify(dns_zone_t *zone); 1480 /*%< 1481 * Generate notify events for this zone. 1482 * 1483 * Requires: 1484 *\li 'zone' to be a valid zone. 1485 */ 1486 1487 isc_result_t 1488 dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, bool dump); 1489 /*%< 1490 * Replace the database of "zone" with a new database "db". 1491 * 1492 * If "dump" is true, then the new zone contents are dumped 1493 * into to the zone's master file for persistence. When replacing 1494 * a zone database by one just loaded from a master file, set 1495 * "dump" to false to avoid a redundant redump of the data just 1496 * loaded. Otherwise, it should be set to true. 1497 * 1498 * If the "diff-on-reload" option is enabled in the configuration file, 1499 * the differences between the old and the new database are added to the 1500 * journal file, and the master file dump is postponed. 1501 * 1502 * Requires: 1503 * \li 'zone' to be a valid zone. 1504 * 1505 * Returns: 1506 * \li DNS_R_SUCCESS 1507 * \li DNS_R_BADZONE zone failed basic consistency checks: 1508 * * a single SOA must exist 1509 * * some NS records must exist. 1510 * Others 1511 */ 1512 1513 uint32_t 1514 dns_zone_getidlein(dns_zone_t *zone); 1515 /*%< 1516 * Requires: 1517 * \li 'zone' to be a valid zone. 1518 * 1519 * Returns: 1520 * \li number of seconds of idle time before we abort the transfer in. 1521 */ 1522 1523 void 1524 dns_zone_setidlein(dns_zone_t *zone, uint32_t idlein); 1525 /*%< 1526 * \li Set the idle timeout for transfer the. 1527 * \li Zero set the default value, 1 hour. 1528 * 1529 * Requires: 1530 * \li 'zone' to be a valid zone. 1531 */ 1532 1533 uint32_t 1534 dns_zone_getidleout(dns_zone_t *zone); 1535 /*%< 1536 * 1537 * Requires: 1538 * \li 'zone' to be a valid zone. 1539 * 1540 * Returns: 1541 * \li number of seconds of idle time before we abort a transfer out. 1542 */ 1543 1544 void 1545 dns_zone_setidleout(dns_zone_t *zone, uint32_t idleout); 1546 /*%< 1547 * \li Set the idle timeout for transfers out. 1548 * \li Zero set the default value, 1 hour. 1549 * 1550 * Requires: 1551 * \li 'zone' to be a valid zone. 1552 */ 1553 1554 void 1555 dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table); 1556 /*%< 1557 * Get the simple-secure-update policy table. 1558 * 1559 * Requires: 1560 * \li 'zone' to be a valid zone. 1561 */ 1562 1563 void 1564 dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table); 1565 /*%< 1566 * Set / clear the simple-secure-update policy table. 1567 * 1568 * Requires: 1569 * \li 'zone' to be a valid zone. 1570 */ 1571 1572 isc_mem_t * 1573 dns_zone_getmctx(dns_zone_t *zone); 1574 /*%< 1575 * Get the memory context of a zone. 1576 * 1577 * Requires: 1578 * \li 'zone' to be a valid zone. 1579 */ 1580 1581 dns_zonemgr_t * 1582 dns_zone_getmgr(dns_zone_t *zone); 1583 /*%< 1584 * If 'zone' is managed return the zone manager otherwise NULL. 1585 * 1586 * Requires: 1587 * \li 'zone' to be a valid zone. 1588 */ 1589 1590 void 1591 dns_zone_setsigvalidityinterval(dns_zone_t *zone, uint32_t interval); 1592 /*%< 1593 * Set the zone's general signature validity interval. This is the length 1594 * of time for which DNSSEC signatures created as a result of dynamic 1595 * updates to secure zones will remain valid, in seconds. 1596 * 1597 * Requires: 1598 * \li 'zone' to be a valid zone. 1599 */ 1600 1601 uint32_t 1602 dns_zone_getsigvalidityinterval(dns_zone_t *zone); 1603 /*%< 1604 * Get the zone's general signature validity interval. 1605 * 1606 * Requires: 1607 * \li 'zone' to be a valid zone. 1608 */ 1609 1610 void 1611 dns_zone_setkeyvalidityinterval(dns_zone_t *zone, uint32_t interval); 1612 /*%< 1613 * Set the zone's DNSKEY signature validity interval. This is the length 1614 * of time for which DNSSEC signatures created for DNSKEY records 1615 * will remain valid, in seconds. 1616 * 1617 * If this value is set to zero, then the regular signature validity 1618 * interval (see dns_zone_setsigvalidityinterval(), above) is used 1619 * for all RRSIGs. However, if this value is nonzero, then it is used 1620 * as the validity interval for RRSIGs covering DNSKEY and CDNSKEY 1621 * RRsets. 1622 * 1623 * Requires: 1624 * \li 'zone' to be a valid zone. 1625 */ 1626 1627 uint32_t 1628 dns_zone_getkeyvalidityinterval(dns_zone_t *zone); 1629 /*%< 1630 * Get the zone's DNSKEY signature validity interval. 1631 * 1632 * Requires: 1633 * \li 'zone' to be a valid zone. 1634 */ 1635 1636 void 1637 dns_zone_setsigresigninginterval(dns_zone_t *zone, uint32_t interval); 1638 /*%< 1639 * Set the zone's RRSIG re-signing interval. A dynamic zone's RRSIG's 1640 * will be re-signed 'interval' amount of time before they expire. 1641 * 1642 * Requires: 1643 * \li 'zone' to be a valid zone. 1644 */ 1645 1646 uint32_t 1647 dns_zone_getsigresigninginterval(dns_zone_t *zone); 1648 /*%< 1649 * Get the zone's RRSIG re-signing interval. 1650 * 1651 * Requires: 1652 * \li 'zone' to be a valid zone. 1653 */ 1654 1655 void 1656 dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype); 1657 /*%< 1658 * Sets zone notify method to "notifytype" 1659 */ 1660 1661 isc_result_t 1662 dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg, 1663 dns_updatecallback_t callback, void *callback_arg); 1664 /*%< 1665 * Forward 'msg' to each master in turn until we get an answer or we 1666 * have exhausted the list of primaries. 'callback' will be called with 1667 * ISC_R_SUCCESS if we get an answer and the returned message will be 1668 * passed as 'answer_message', otherwise a non ISC_R_SUCCESS result code 1669 * will be passed and answer_message will be NULL. The callback function 1670 * is responsible for destroying 'answer_message'. 1671 * (callback)(callback_arg, result, answer_message); 1672 * 1673 * Require: 1674 *\li 'zone' to be valid 1675 *\li 'msg' to be valid. 1676 *\li 'callback' to be non NULL. 1677 * Returns: 1678 *\li #ISC_R_SUCCESS if the message has been forwarded, 1679 *\li #ISC_R_NOMEMORY 1680 *\li Others 1681 */ 1682 1683 isc_result_t 1684 dns_zone_next(dns_zone_t *zone, dns_zone_t **next); 1685 /*%< 1686 * Find the next zone in the list of managed zones. 1687 * 1688 * Requires: 1689 *\li 'zone' to be valid 1690 *\li The zone manager for the indicated zone MUST be locked 1691 * by the caller. This is not checked. 1692 *\li 'next' be non-NULL, and '*next' be NULL. 1693 * 1694 * Ensures: 1695 *\li 'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL 1696 * (result ISC_R_NOMORE). 1697 */ 1698 1699 isc_result_t 1700 dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first); 1701 /*%< 1702 * Find the first zone in the list of managed zones. 1703 * 1704 * Requires: 1705 *\li 'zonemgr' to be valid 1706 *\li The zone manager for the indicated zone MUST be locked 1707 * by the caller. This is not checked. 1708 *\li 'first' be non-NULL, and '*first' be NULL 1709 * 1710 * Ensures: 1711 *\li 'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL 1712 * (result ISC_R_NOMORE). 1713 */ 1714 1715 isc_result_t 1716 dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory); 1717 /*%< 1718 * Sets the name of the directory where private keys used for 1719 * online signing of dynamic zones are found. 1720 * 1721 * Require: 1722 *\li 'zone' to be a valid zone. 1723 * 1724 * Returns: 1725 *\li #ISC_R_NOMEMORY 1726 *\li #ISC_R_SUCCESS 1727 */ 1728 1729 const char * 1730 dns_zone_getkeydirectory(dns_zone_t *zone); 1731 /*%< 1732 * Gets the name of the directory where private keys used for 1733 * online signing of dynamic zones are found. 1734 * 1735 * Requires: 1736 *\li 'zone' to be valid initialised zone. 1737 * 1738 * Returns: 1739 * Pointer to null-terminated file name, or NULL. 1740 */ 1741 1742 isc_result_t 1743 dns_zone_getdnsseckeys(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *ver, 1744 isc_stdtime_t now, dns_dnsseckeylist_t *keys); 1745 /*% 1746 * Find DNSSEC keys used for signing with dnssec-policy. Load these keys 1747 * into 'keys'. 1748 * 1749 * Requires: 1750 *\li 'zone' to be valid initialised zone. 1751 *\li 'keys' to be an initialised DNSSEC keylist. 1752 * 1753 * Returns: 1754 *\li #ISC_R_SUCCESS 1755 *\li Error 1756 */ 1757 1758 isc_result_t 1759 dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr, 1760 isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr, 1761 dns_zonemgr_t **zmgrp); 1762 /*%< 1763 * Create a zone manager. Note: the zone manager will not be able to 1764 * manage any zones until dns_zonemgr_setsize() has been run. 1765 * 1766 * Requires: 1767 *\li 'mctx' to be a valid memory context. 1768 *\li 'taskmgr' to be a valid task manager. 1769 *\li 'timermgr' to be a valid timer manager. 1770 *\li 'zmgrp' to point to a NULL pointer. 1771 */ 1772 1773 isc_result_t 1774 dns_zonemgr_setsize(dns_zonemgr_t *zmgr, int num_zones); 1775 /*%< 1776 * Set the size of the zone manager task pool. This must be run 1777 * before zmgr can be used for managing zones. Currently, it can only 1778 * be run once; the task pool cannot be resized. 1779 * 1780 * Requires: 1781 *\li zmgr is a valid zone manager. 1782 *\li zmgr->zonetasks has been initialized. 1783 */ 1784 1785 isc_result_t 1786 dns_zonemgr_createzone(dns_zonemgr_t *zmgr, dns_zone_t **zonep); 1787 /*%< 1788 * Allocate a new zone using a memory context from the 1789 * zone manager's memory context pool. 1790 * 1791 * Require: 1792 *\li 'zmgr' to be a valid zone manager. 1793 *\li 'zonep' != NULL and '*zonep' == NULL. 1794 */ 1795 1796 isc_result_t 1797 dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone); 1798 /*%< 1799 * Bring the zone under control of a zone manager. 1800 * 1801 * Require: 1802 *\li 'zmgr' to be a valid zone manager. 1803 *\li 'zone' to be a valid zone. 1804 */ 1805 1806 isc_result_t 1807 dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr); 1808 /*%< 1809 * Force zone maintenance of all loaded zones managed by 'zmgr' 1810 * to take place at the system's earliest convenience. 1811 */ 1812 1813 void 1814 dns__zonemgr_run(isc_task_t *task, isc_event_t *event); 1815 /*%< 1816 * Event handler to call dns_zonemgr_forcemaint(); used to start 1817 * zone operations from a unit test. Not intended for use outside 1818 * libdns or related tests. 1819 */ 1820 1821 void 1822 dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr); 1823 /*%< 1824 * Attempt to start any stalled zone transfers. 1825 */ 1826 1827 void 1828 dns_zonemgr_shutdown(dns_zonemgr_t *zmgr); 1829 /*%< 1830 * Shut down the zone manager. 1831 * 1832 * Requires: 1833 *\li 'zmgr' to be a valid zone manager. 1834 */ 1835 1836 void 1837 dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target); 1838 /*%< 1839 * Attach '*target' to 'source' incrementing its external 1840 * reference count. 1841 * 1842 * Require: 1843 *\li 'zone' to be a valid zone. 1844 *\li 'target' to be non NULL and '*target' to be NULL. 1845 */ 1846 1847 void 1848 dns_zonemgr_detach(dns_zonemgr_t **zmgrp); 1849 /*%< 1850 * Detach from a zone manager. 1851 * 1852 * Requires: 1853 *\li '*zmgrp' is a valid, non-NULL zone manager pointer. 1854 * 1855 * Ensures: 1856 *\li '*zmgrp' is NULL. 1857 */ 1858 1859 void 1860 dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone); 1861 /*%< 1862 * Release 'zone' from the managed by 'zmgr'. 'zmgr' is implicitly 1863 * detached from 'zone'. 1864 * 1865 * Requires: 1866 *\li 'zmgr' to be a valid zone manager. 1867 *\li 'zone' to be a valid zone. 1868 *\li 'zmgr' == 'zone->zmgr' 1869 * 1870 * Ensures: 1871 *\li 'zone->zmgr' == NULL; 1872 */ 1873 1874 isc_taskmgr_t * 1875 dns_zonemgr_gettaskmgr(dns_zonemgr_t *zmgr); 1876 /*% 1877 * Get the tasmkgr object attached to 'zmgr'. 1878 */ 1879 1880 void 1881 dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, uint32_t value); 1882 /*%< 1883 * Set the maximum number of simultaneous transfers in allowed by 1884 * the zone manager. 1885 * 1886 * Requires: 1887 *\li 'zmgr' to be a valid zone manager. 1888 */ 1889 1890 uint32_t 1891 dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr); 1892 /*%< 1893 * Return the maximum number of simultaneous transfers in allowed. 1894 * 1895 * Requires: 1896 *\li 'zmgr' to be a valid zone manager. 1897 */ 1898 1899 void 1900 dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, uint32_t value); 1901 /*%< 1902 * Set the number of zone transfers allowed per nameserver. 1903 * 1904 * Requires: 1905 *\li 'zmgr' to be a valid zone manager 1906 */ 1907 1908 uint32_t 1909 dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr); 1910 /*%< 1911 * Return the number of transfers allowed per nameserver. 1912 * 1913 * Requires: 1914 *\li 'zmgr' to be a valid zone manager. 1915 */ 1916 1917 void 1918 dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, uint32_t iolimit); 1919 /*%< 1920 * Set the number of simultaneous file descriptors available for 1921 * reading and writing masterfiles. 1922 * 1923 * Requires: 1924 *\li 'zmgr' to be a valid zone manager. 1925 *\li 'iolimit' to be positive. 1926 */ 1927 1928 uint32_t 1929 dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr); 1930 /*%< 1931 * Get the number of simultaneous file descriptors available for 1932 * reading and writing masterfiles. 1933 * 1934 * Requires: 1935 *\li 'zmgr' to be a valid zone manager. 1936 */ 1937 1938 void 1939 dns_zonemgr_setcheckdsrate(dns_zonemgr_t *zmgr, unsigned int value); 1940 /*%< 1941 * Set the number of parental DS queries sent per second. 1942 * 1943 * Requires: 1944 *\li 'zmgr' to be a valid zone manager 1945 */ 1946 1947 void 1948 dns_zonemgr_setnotifyrate(dns_zonemgr_t *zmgr, unsigned int value); 1949 /*%< 1950 * Set the number of NOTIFY requests sent per second. 1951 * 1952 * Requires: 1953 *\li 'zmgr' to be a valid zone manager 1954 */ 1955 1956 void 1957 dns_zonemgr_setstartupnotifyrate(dns_zonemgr_t *zmgr, unsigned int value); 1958 /*%< 1959 * Set the number of startup NOTIFY requests sent per second. 1960 * 1961 * Requires: 1962 *\li 'zmgr' to be a valid zone manager 1963 */ 1964 1965 void 1966 dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value); 1967 /*%< 1968 * Set the number of SOA queries sent per second. 1969 * 1970 * Requires: 1971 *\li 'zmgr' to be a valid zone manager 1972 */ 1973 1974 unsigned int 1975 dns_zonemgr_getnotifyrate(dns_zonemgr_t *zmgr); 1976 /*%< 1977 * Return the number of NOTIFY requests sent per second. 1978 * 1979 * Requires: 1980 *\li 'zmgr' to be a valid zone manager. 1981 */ 1982 1983 unsigned int 1984 dns_zonemgr_getstartupnotifyrate(dns_zonemgr_t *zmgr); 1985 /*%< 1986 * Return the number of startup NOTIFY requests sent per second. 1987 * 1988 * Requires: 1989 *\li 'zmgr' to be a valid zone manager. 1990 */ 1991 1992 unsigned int 1993 dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr); 1994 /*%< 1995 * Return the number of SOA queries sent per second. 1996 * 1997 * Requires: 1998 *\li 'zmgr' to be a valid zone manager. 1999 */ 2000 2001 unsigned int 2002 dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state); 2003 /*%< 2004 * Returns the number of zones in the specified state. 2005 * 2006 * Requires: 2007 *\li 'zmgr' to be a valid zone manager. 2008 *\li 'state' to be a valid DNS_ZONESTATE_ constant. 2009 */ 2010 2011 void 2012 dns_zonemgr_unreachableadd(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote, 2013 isc_sockaddr_t *local, isc_time_t *now); 2014 /*%< 2015 * Add the pair of addresses to the unreachable cache. 2016 * 2017 * Requires: 2018 *\li 'zmgr' to be a valid zone manager. 2019 *\li 'remote' to be a valid sockaddr. 2020 *\li 'local' to be a valid sockaddr. 2021 */ 2022 2023 bool 2024 dns_zonemgr_unreachable(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote, 2025 isc_sockaddr_t *local, isc_time_t *now); 2026 /*%< 2027 * Returns true if the given local/remote address pair 2028 * is found in the zone maanger's unreachable cache. 2029 * 2030 * Requires: 2031 *\li 'zmgr' to be a valid zone manager. 2032 *\li 'remote' to be a valid sockaddr. 2033 *\li 'local' to be a valid sockaddr. 2034 *\li 'now' != NULL 2035 */ 2036 2037 void 2038 dns_zonemgr_unreachabledel(dns_zonemgr_t *zmgr, isc_sockaddr_t *remote, 2039 isc_sockaddr_t *local); 2040 /*%< 2041 * Remove the pair of addresses from the unreachable cache. 2042 * 2043 * Requires: 2044 *\li 'zmgr' to be a valid zone manager. 2045 *\li 'remote' to be a valid sockaddr. 2046 *\li 'local' to be a valid sockaddr. 2047 */ 2048 2049 void 2050 dns_zone_forcereload(dns_zone_t *zone); 2051 /*%< 2052 * Force a reload of specified zone. 2053 * 2054 * Requires: 2055 *\li 'zone' to be a valid zone. 2056 */ 2057 2058 bool 2059 dns_zone_isforced(dns_zone_t *zone); 2060 /*%< 2061 * Check if the zone is waiting a forced reload. 2062 * 2063 * Requires: 2064 * \li 'zone' to be a valid zone. 2065 */ 2066 2067 isc_result_t 2068 dns_zone_setstatistics(dns_zone_t *zone, bool on); 2069 /*%< 2070 * This function is obsoleted by dns_zone_setrequeststats(). 2071 */ 2072 2073 uint64_t * 2074 dns_zone_getstatscounters(dns_zone_t *zone); 2075 /*%< 2076 * This function is obsoleted by dns_zone_getrequeststats(). 2077 */ 2078 2079 void 2080 dns_zone_setstats(dns_zone_t *zone, isc_stats_t *stats); 2081 /*%< 2082 * Set a general zone-maintenance statistics set 'stats' for 'zone'. This 2083 * function is expected to be called only on zone creation (when necessary). 2084 * Once installed, it cannot be removed or replaced. Also, there is no 2085 * interface to get the installed stats from the zone; the caller must keep the 2086 * stats to reference (e.g. dump) it later. 2087 * 2088 * Requires: 2089 * \li 'zone' to be a valid zone and does not have a statistics set already 2090 * installed. 2091 * 2092 *\li stats is a valid statistics supporting zone statistics counters 2093 * (see dns/stats.h). 2094 */ 2095 2096 void 2097 dns_zone_setrequeststats(dns_zone_t *zone, isc_stats_t *stats); 2098 2099 void 2100 dns_zone_setrcvquerystats(dns_zone_t *zone, dns_stats_t *stats); 2101 2102 void 2103 dns_zone_setdnssecsignstats(dns_zone_t *zone, dns_stats_t *stats); 2104 /*%< 2105 * Set additional statistics sets to zone. These are attached to the zone 2106 * but are not counted in the zone module; only the caller updates the 2107 * counters. 2108 * 2109 * Requires: 2110 * \li 'zone' to be a valid zone. 2111 * 2112 *\li stats is a valid statistics. 2113 */ 2114 2115 isc_stats_t * 2116 dns_zone_getrequeststats(dns_zone_t *zone); 2117 2118 dns_stats_t * 2119 dns_zone_getrcvquerystats(dns_zone_t *zone); 2120 2121 dns_stats_t * 2122 dns_zone_getdnssecsignstats(dns_zone_t *zone); 2123 /*%< 2124 * Get the additional statistics for zone, if one is installed. 2125 * 2126 * Requires: 2127 * \li 'zone' to be a valid zone. 2128 * 2129 * Returns: 2130 * \li when available, a pointer to the statistics set installed in zone; 2131 * otherwise NULL. 2132 */ 2133 2134 void 2135 dns_zone_dialup(dns_zone_t *zone); 2136 /*%< 2137 * Perform dialup-time maintenance on 'zone'. 2138 */ 2139 2140 void 2141 dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup); 2142 /*%< 2143 * Set the dialup type of 'zone' to 'dialup'. 2144 * 2145 * Requires: 2146 * \li 'zone' to be valid initialised zone. 2147 *\li 'dialup' to be a valid dialup type. 2148 */ 2149 2150 void 2151 dns_zone_logv(dns_zone_t *zone, isc_logcategory_t *category, int level, 2152 const char *prefix, const char *msg, va_list ap); 2153 /*%< 2154 * Log the message 'msg...' at 'level' using log category 'category', including 2155 * text that identifies the message as applying to 'zone'. If the (optional) 2156 * 'prefix' is not NULL, it will be placed at the start of the entire log line. 2157 */ 2158 2159 void 2160 dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...) 2161 ISC_FORMAT_PRINTF(3, 4); 2162 /*%< 2163 * Log the message 'msg...' at 'level', including text that identifies 2164 * the message as applying to 'zone'. 2165 */ 2166 2167 void 2168 dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level, 2169 const char *msg, ...) ISC_FORMAT_PRINTF(4, 5); 2170 /*%< 2171 * Log the message 'msg...' at 'level', including text that identifies 2172 * the message as applying to 'zone'. 2173 */ 2174 2175 void 2176 dns_zone_name(dns_zone_t *zone, char *buf, size_t len); 2177 /*%< 2178 * Return the name of the zone with class and view. 2179 * 2180 * Requires: 2181 *\li 'zone' to be valid. 2182 *\li 'buf' to be non NULL. 2183 */ 2184 2185 void 2186 dns_zone_nameonly(dns_zone_t *zone, char *buf, size_t len); 2187 /*%< 2188 * Return the name of the zone only. 2189 * 2190 * Requires: 2191 *\li 'zone' to be valid. 2192 *\li 'buf' to be non NULL. 2193 */ 2194 2195 isc_result_t 2196 dns_zone_checknames(dns_zone_t *zone, const dns_name_t *name, 2197 dns_rdata_t *rdata); 2198 /*%< 2199 * Check if this record meets the check-names policy. 2200 * 2201 * Requires: 2202 * 'zone' to be valid. 2203 * 'name' to be valid. 2204 * 'rdata' to be valid. 2205 * 2206 * Returns: 2207 * DNS_R_SUCCESS passed checks. 2208 * DNS_R_BADOWNERNAME failed ownername checks. 2209 * DNS_R_BADNAME failed rdata checks. 2210 */ 2211 2212 void 2213 dns_zone_setcheckmx(dns_zone_t *zone, dns_checkmxfunc_t checkmx); 2214 /*%< 2215 * Set the post load integrity callback function 'checkmx'. 2216 * 'checkmx' will be called if the MX TARGET is not within the zone. 2217 * 2218 * Require: 2219 * 'zone' to be a valid zone. 2220 */ 2221 2222 void 2223 dns_zone_setchecksrv(dns_zone_t *zone, dns_checkmxfunc_t checksrv); 2224 /*%< 2225 * Set the post load integrity callback function 'checksrv'. 2226 * 'checksrv' will be called if the SRV TARGET is not within the zone. 2227 * 2228 * Require: 2229 * 'zone' to be a valid zone. 2230 */ 2231 2232 void 2233 dns_zone_setcheckns(dns_zone_t *zone, dns_checknsfunc_t checkns); 2234 /*%< 2235 * Set the post load integrity callback function 'checkns'. 2236 * 'checkns' will be called if the NS TARGET is not within the zone. 2237 * 2238 * Require: 2239 * 'zone' to be a valid zone. 2240 */ 2241 2242 void 2243 dns_zone_setnotifydelay(dns_zone_t *zone, uint32_t delay); 2244 /*%< 2245 * Set the minimum delay between sets of notify messages. 2246 * 2247 * Requires: 2248 * 'zone' to be valid. 2249 */ 2250 2251 uint32_t 2252 dns_zone_getnotifydelay(dns_zone_t *zone); 2253 /*%< 2254 * Get the minimum delay between sets of notify messages. 2255 * 2256 * Requires: 2257 * 'zone' to be valid. 2258 */ 2259 2260 void 2261 dns_zone_setisself(dns_zone_t *zone, dns_isselffunc_t isself, void *arg); 2262 /*%< 2263 * Set the isself callback function and argument. 2264 * 2265 * bool 2266 * isself(dns_view_t *myview, dns_tsigkey_t *mykey, 2267 * const isc_netaddr_t *srcaddr, const isc_netaddr_t *destaddr, 2268 * dns_rdataclass_t rdclass, void *arg); 2269 * 2270 * 'isself' returns true if a non-recursive query from 'srcaddr' to 2271 * 'destaddr' with optional key 'mykey' for class 'rdclass' would be 2272 * delivered to 'myview'. 2273 */ 2274 2275 void 2276 dns_zone_setnodes(dns_zone_t *zone, uint32_t nodes); 2277 /*%< 2278 * Set the number of nodes that will be checked per quantum. 2279 */ 2280 2281 void 2282 dns_zone_setsignatures(dns_zone_t *zone, uint32_t signatures); 2283 /*%< 2284 * Set the number of signatures that will be generated per quantum. 2285 */ 2286 2287 uint32_t 2288 dns_zone_getsignatures(dns_zone_t *zone); 2289 /*%< 2290 * Get the number of signatures that will be generated per quantum. 2291 */ 2292 2293 isc_result_t 2294 dns_zone_signwithkey(dns_zone_t *zone, dns_secalg_t algorithm, uint16_t keyid, 2295 bool deleteit); 2296 /*%< 2297 * Initiate/resume signing of the entire zone with the zone DNSKEY(s) 2298 * that match the given algorithm and keyid. 2299 */ 2300 2301 isc_result_t 2302 dns_zone_addnsec3chain(dns_zone_t *zone, dns_rdata_nsec3param_t *nsec3param); 2303 /*%< 2304 * Incrementally add a NSEC3 chain that corresponds to 'nsec3param'. 2305 */ 2306 2307 void 2308 dns_zone_setprivatetype(dns_zone_t *zone, dns_rdatatype_t type); 2309 dns_rdatatype_t 2310 dns_zone_getprivatetype(dns_zone_t *zone); 2311 /* 2312 * Get/Set the private record type. It is expected that these interfaces 2313 * will not be permanent. 2314 */ 2315 2316 void 2317 dns_zone_rekey(dns_zone_t *zone, bool fullsign); 2318 /*%< 2319 * Update the zone's DNSKEY set from the key repository. 2320 * 2321 * If 'fullsign' is true, trigger an immediate full signing of 2322 * the zone with the new key. Otherwise, if there are no keys or 2323 * if the new keys are for algorithms that have already signed the 2324 * zone, then the zone can be re-signed incrementally. 2325 */ 2326 2327 isc_result_t 2328 dns_zone_nscheck(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version, 2329 unsigned int *errors); 2330 /*% 2331 * Check if the name servers for the zone are sane (have address, don't 2332 * refer to CNAMEs/DNAMEs. The number of constiancy errors detected in 2333 * returned in '*errors' 2334 * 2335 * Requires: 2336 * \li 'zone' to be valid. 2337 * \li 'db' to be valid. 2338 * \li 'version' to be valid or NULL. 2339 * \li 'errors' to be non NULL. 2340 * 2341 * Returns: 2342 * ISC_R_SUCCESS if there were no errors examining the zone contents. 2343 */ 2344 2345 isc_result_t 2346 dns_zone_cdscheck(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version); 2347 /*% 2348 * Check if CSD, CDNSKEY and DNSKEY are consistent. 2349 * 2350 * Requires: 2351 * \li 'zone' to be valid. 2352 * \li 'db' to be valid. 2353 * \li 'version' to be valid or NULL. 2354 * 2355 * Returns: 2356 *\li #ISC_R_SUCCESS 2357 *\li #DNS_R_BADCDS 2358 *\li #DNS_R_BADCDNSKEY 2359 * Others 2360 */ 2361 2362 void 2363 dns_zone_setadded(dns_zone_t *zone, bool added); 2364 /*% 2365 * Sets the value of zone->added, which should be true for 2366 * zones that were originally added by "rndc addzone". 2367 * 2368 * Requires: 2369 * \li 'zone' to be valid. 2370 */ 2371 2372 bool 2373 dns_zone_getadded(dns_zone_t *zone); 2374 /*% 2375 * Returns true if the zone was originally added at runtime 2376 * using "rndc addzone". 2377 * 2378 * Requires: 2379 * \li 'zone' to be valid. 2380 */ 2381 2382 void 2383 dns_zone_setautomatic(dns_zone_t *zone, bool automatic); 2384 /*% 2385 * Sets the value of zone->automatic, which should be true for 2386 * zones that were automatically added by named. 2387 * 2388 * Requires: 2389 * \li 'zone' to be valid. 2390 */ 2391 2392 bool 2393 dns_zone_getautomatic(dns_zone_t *zone); 2394 /*% 2395 * Returns true if the zone was added automatically by named. 2396 * 2397 * Requires: 2398 * \li 'zone' to be valid. 2399 */ 2400 2401 isc_result_t 2402 dns_zone_dlzpostload(dns_zone_t *zone, dns_db_t *db); 2403 /*% 2404 * Load the origin names for a writeable DLZ database. 2405 */ 2406 2407 bool 2408 dns_zone_isdynamic(dns_zone_t *zone, bool ignore_freeze); 2409 /*% 2410 * Return true iff the zone is "dynamic", in the sense that the zone's 2411 * master file (if any) is written by the server, rather than being 2412 * updated manually and read by the server. 2413 * 2414 * This is true for slave zones, stub zones, key zones, and zones that 2415 * allow dynamic updates either by having an update policy ("ssutable") 2416 * or an "allow-update" ACL with a value other than exactly "{ none; }". 2417 * 2418 * If 'ignore_freeze' is true, then the zone which has had updates disabled 2419 * will still report itself to be dynamic. 2420 * 2421 * Requires: 2422 * \li 'zone' to be valid. 2423 */ 2424 2425 isc_result_t 2426 dns_zone_setrefreshkeyinterval(dns_zone_t *zone, uint32_t interval); 2427 /*% 2428 * Sets the frequency, in minutes, with which the key repository will be 2429 * checked to see if the keys for this zone have been updated. Any value 2430 * higher than 1440 minutes (24 hours) will be silently reduced. A 2431 * value of zero will return an out-of-range error. 2432 * 2433 * Requires: 2434 * \li 'zone' to be valid. 2435 */ 2436 2437 bool 2438 dns_zone_getrequestexpire(dns_zone_t *zone); 2439 /*% 2440 * Returns the true/false value of the request-expire option in the zone. 2441 * 2442 * Requires: 2443 * \li 'zone' to be valid. 2444 */ 2445 2446 void 2447 dns_zone_setrequestexpire(dns_zone_t *zone, bool flag); 2448 /*% 2449 * Sets the request-expire option for the zone. Either true or false. The 2450 * default value is determined by the setting of this option in the view. 2451 * 2452 * Requires: 2453 * \li 'zone' to be valid. 2454 */ 2455 2456 bool 2457 dns_zone_getrequestixfr(dns_zone_t *zone); 2458 /*% 2459 * Returns the true/false value of the request-ixfr option in the zone. 2460 * 2461 * Requires: 2462 * \li 'zone' to be valid. 2463 */ 2464 2465 void 2466 dns_zone_setrequestixfr(dns_zone_t *zone, bool flag); 2467 /*% 2468 * Sets the request-ixfr option for the zone. Either true or false. The 2469 * default value is determined by the setting of this option in the view. 2470 * 2471 * Requires: 2472 * \li 'zone' to be valid. 2473 */ 2474 2475 uint32_t 2476 dns_zone_getixfrratio(dns_zone_t *zone); 2477 /*% 2478 * Returns the zone's current IXFR ratio. 2479 * 2480 * Requires: 2481 * \li 'zone' to be valid. 2482 */ 2483 2484 void 2485 dns_zone_setixfrratio(dns_zone_t *zone, uint32_t ratio); 2486 /*% 2487 * Sets the ratio of IXFR size to zone size above which we use an AXFR 2488 * response, expressed as a percentage. Cannot exceed 100. 2489 * 2490 * Requires: 2491 * \li 'zone' to be valid. 2492 */ 2493 2494 void 2495 dns_zone_setserialupdatemethod(dns_zone_t *zone, dns_updatemethod_t method); 2496 /*% 2497 * Sets the update method to use when incrementing the zone serial number 2498 * due to a DDNS update. Valid options are dns_updatemethod_increment 2499 * and dns_updatemethod_unixtime. 2500 * 2501 * Requires: 2502 * \li 'zone' to be valid. 2503 */ 2504 2505 dns_updatemethod_t 2506 dns_zone_getserialupdatemethod(dns_zone_t *zone); 2507 /*% 2508 * Returns the update method to be used when incrementing the zone serial 2509 * number due to a DDNS update. 2510 * 2511 * Requires: 2512 * \li 'zone' to be valid. 2513 */ 2514 2515 isc_result_t 2516 dns_zone_link(dns_zone_t *zone, dns_zone_t *raw); 2517 2518 void 2519 dns_zone_getraw(dns_zone_t *zone, dns_zone_t **raw); 2520 2521 isc_result_t 2522 dns_zone_keydone(dns_zone_t *zone, const char *data); 2523 2524 isc_result_t 2525 dns_zone_setnsec3param(dns_zone_t *zone, uint8_t hash, uint8_t flags, 2526 uint16_t iter, uint8_t saltlen, unsigned char *salt, 2527 bool replace, bool resalt); 2528 /*% 2529 * Set the NSEC3 parameters for the zone. 2530 * 2531 * If 'replace' is true, then the existing NSEC3 chain, if any, will 2532 * be replaced with the new one. If 'hash' is zero, then the replacement 2533 * chain will be NSEC rather than NSEC3. If 'resalt' is true, or if 'salt' 2534 * is NULL, generate a new salt with the given salt length. 2535 * 2536 * Requires: 2537 * \li 'zone' to be valid. 2538 */ 2539 2540 void 2541 dns_zone_setrawdata(dns_zone_t *zone, dns_masterrawheader_t *header); 2542 /*% 2543 * Set the data to be included in the header when the zone is dumped in 2544 * binary format. 2545 */ 2546 2547 isc_result_t 2548 dns_zone_synckeyzone(dns_zone_t *zone); 2549 /*% 2550 * Force the managed key zone to synchronize, and start the key 2551 * maintenance timer. 2552 */ 2553 2554 isc_result_t 2555 dns_zone_getloadtime(dns_zone_t *zone, isc_time_t *loadtime); 2556 /*% 2557 * Return the time when the zone was last loaded. 2558 */ 2559 2560 isc_result_t 2561 dns_zone_getrefreshtime(dns_zone_t *zone, isc_time_t *refreshtime); 2562 /*% 2563 * Return the time when the (slave) zone will need to be refreshed. 2564 */ 2565 2566 isc_result_t 2567 dns_zone_getexpiretime(dns_zone_t *zone, isc_time_t *expiretime); 2568 /*% 2569 * Return the time when the (slave) zone will expire. 2570 */ 2571 2572 isc_result_t 2573 dns_zone_getrefreshkeytime(dns_zone_t *zone, isc_time_t *refreshkeytime); 2574 /*% 2575 * Return the time of the next scheduled DNSSEC key event. 2576 */ 2577 2578 unsigned int 2579 dns_zone_getincludes(dns_zone_t *zone, char ***includesp); 2580 /*% 2581 * Return the number include files that were encountered 2582 * during load. If the number is greater than zero, 'includesp' 2583 * will point to an array containing the filenames. 2584 * 2585 * The array and its contents need to be freed using isc_mem_free. 2586 */ 2587 2588 isc_result_t 2589 dns_zone_rpz_enable(dns_zone_t *zone, dns_rpz_zones_t *rpzs, 2590 dns_rpz_num_t rpz_num); 2591 /*% 2592 * Set the response policy associated with a zone. 2593 */ 2594 2595 void 2596 dns_zone_rpz_enable_db(dns_zone_t *zone, dns_db_t *db); 2597 /*% 2598 * If a zone is a response policy zone, mark its new database. 2599 */ 2600 2601 dns_rpz_num_t 2602 dns_zone_get_rpz_num(dns_zone_t *zone); 2603 2604 void 2605 dns_zone_catz_enable(dns_zone_t *zone, dns_catz_zones_t *catzs); 2606 /*%< 2607 * Enable zone as catalog zone. 2608 * 2609 * Requires: 2610 * 2611 * \li 'zone' is a valid zone object 2612 * \li 'catzs' is not NULL 2613 * \li prior to calling, zone->catzs is NULL or is equal to 'catzs' 2614 */ 2615 2616 void 2617 dns_zone_catz_disable(dns_zone_t *zone); 2618 /*%< 2619 * Disable zone as catalog zone, if it is one. Also disables any 2620 * registered callbacks for the catalog zone. 2621 * 2622 * Requires: 2623 * 2624 * \li 'zone' is a valid zone object 2625 */ 2626 2627 bool 2628 dns_zone_catz_is_enabled(dns_zone_t *zone); 2629 /*%< 2630 * Return a boolean indicating whether the zone is enabled as catalog zone. 2631 * 2632 * Requires: 2633 * 2634 * \li 'zone' is a valid zone object 2635 */ 2636 2637 void 2638 dns_zone_catz_enable_db(dns_zone_t *zone, dns_db_t *db); 2639 /*%< 2640 * If 'zone' is a catalog zone, then set up a notify-on-update trigger 2641 * in its database. (If not a catalog zone, this function has no effect.) 2642 * 2643 * Requires: 2644 * 2645 * \li 'zone' is a valid zone object 2646 * \li 'db' is not NULL 2647 */ 2648 void 2649 dns_zone_set_parentcatz(dns_zone_t *zone, dns_catz_zone_t *catz); 2650 /*%< 2651 * Set parent catalog zone for this zone 2652 * 2653 * Requires: 2654 * 2655 * \li 'zone' is a valid zone object 2656 * \li 'catz' is not NULL 2657 */ 2658 2659 dns_catz_zone_t * 2660 dns_zone_get_parentcatz(const dns_zone_t *zone); 2661 /*%< 2662 * Get parent catalog zone for this zone 2663 * 2664 * Requires: 2665 * 2666 * \li 'zone' is a valid zone object 2667 */ 2668 2669 void 2670 dns_zone_setstatlevel(dns_zone_t *zone, dns_zonestat_level_t level); 2671 2672 dns_zonestat_level_t 2673 dns_zone_getstatlevel(dns_zone_t *zone); 2674 /*% 2675 * Set and get the statistics reporting level for the zone; 2676 * full, terse, or none. 2677 */ 2678 2679 isc_result_t 2680 dns_zone_setserial(dns_zone_t *zone, uint32_t serial); 2681 /*% 2682 * Set the zone's serial to 'serial'. 2683 */ 2684 ISC_LANG_ENDDECLS 2685 2686 isc_stats_t * 2687 dns_zone_getgluecachestats(dns_zone_t *zone); 2688 /*%< 2689 * Get the glue cache statistics for zone. 2690 * 2691 * Requires: 2692 * \li 'zone' to be a valid zone. 2693 * 2694 * Returns: 2695 * \li if present, a pointer to the statistics set installed in zone; 2696 * otherwise NULL. 2697 */ 2698 2699 bool 2700 dns_zone_isloaded(dns_zone_t *zone); 2701 /*%< 2702 * Return true if 'zone' was loaded and has not expired yet, return 2703 * false otherwise. 2704 */ 2705 2706 isc_result_t 2707 dns_zone_verifydb(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *ver); 2708 /*%< 2709 * If 'zone' is a mirror zone, perform DNSSEC validation of version 'ver' of 2710 * its database, 'db'. Ensure that the DNSKEY RRset at zone apex is signed by 2711 * at least one trust anchor specified for the view that 'zone' is assigned to. 2712 * If 'ver' is NULL, use the current version of 'db'. 2713 * 2714 * If 'zone' is not a mirror zone, return ISC_R_SUCCESS immediately. 2715 * 2716 * Returns: 2717 * 2718 * \li #ISC_R_SUCCESS either 'zone' is not a mirror zone or 'zone' is 2719 * a mirror zone and all DNSSEC checks succeeded 2720 * and the DNSKEY RRset at zone apex is signed by 2721 * a trusted key 2722 * 2723 * \li #DNS_R_VERIFYFAILURE any other case 2724 */ 2725 2726 const char * 2727 dns_zonetype_name(dns_zonetype_t type); 2728 /*%< 2729 * Return the name of the zone type 'type'. 2730 */ 2731 2732 #endif /* DNS_ZONE_H */ 2733