JezK
Edit File: catz.h
/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, you can obtain one at https://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ #ifndef DNS_CATZ_H #define DNS_CATZ_H 1 #include <inttypes.h> #include <stdbool.h> #include <isc/ht.h> #include <isc/lang.h> #include <isc/refcount.h> #include <isc/rwlock.h> #include <isc/time.h> #include <isc/timer.h> #include <dns/db.h> #include <dns/fixedname.h> #include <dns/ipkeylist.h> #include <dns/rdata.h> #include <dns/types.h> ISC_LANG_BEGINDECLS #define DNS_CATZ_ERROR_LEVEL ISC_LOG_WARNING #define DNS_CATZ_INFO_LEVEL ISC_LOG_INFO #define DNS_CATZ_DEBUG_LEVEL1 ISC_LOG_DEBUG(1) #define DNS_CATZ_DEBUG_LEVEL2 ISC_LOG_DEBUG(2) #define DNS_CATZ_DEBUG_LEVEL3 ISC_LOG_DEBUG(3) #define DNS_CATZ_DEBUG_QUIET (DNS_CATZ_DEBUG_LEVEL3 + 1) /* * Catalog Zones functions and structures. */ /* * Options for a member zone in a catalog */ struct dns_catz_entry_options { /* * Options that can be overridden in catalog zone */ /* default-masters definition */ dns_ipkeylist_t masters; /* both as text in config format, NULL if none */ isc_buffer_t *allow_query; isc_buffer_t *allow_transfer; /* * Options that are only set in named.conf */ /* zone-directory definition */ char *zonedir; /* zone should not be stored on disk (no 'file' statement in def */ bool in_memory; /* * Minimal interval between catalog zone updates, if a new version * of catalog zone is received before this time the update will be * postponed. This is a global option for the whole catalog zone. */ uint32_t min_update_interval; }; void dns_catz_options_init(dns_catz_options_t *options); /*%< * Initialize 'options' to NULL values. * * Requires: * \li 'options' to be non NULL. */ void dns_catz_options_free(dns_catz_options_t *options, isc_mem_t *mctx); /*%< * Free 'options' contents into 'mctx'. ('options' itself is not freed.) * * Requires: * \li 'options' to be non NULL. * \li 'mctx' to be a valid memory context. */ isc_result_t dns_catz_options_copy(isc_mem_t *mctx, const dns_catz_options_t *opts, dns_catz_options_t *nopts); /*%< * Duplicate 'opts' into 'nopts', allocating space from 'mctx'. * * Requires: * \li 'mctx' to be a valid memory context. * \li 'options' to be non NULL and valid options. * \li 'nopts' to be non NULL. */ isc_result_t dns_catz_options_setdefault(isc_mem_t *mctx, const dns_catz_options_t *defaults, dns_catz_options_t *opts); /*%< * Replace empty values in 'opts' with values from 'defaults' * * Requires: * \li 'mctx' to be a valid memory context. * \li 'defaults' to be non NULL and valid options. * \li 'opts' to be non NULL. */ dns_name_t * dns_catz_entry_getname(dns_catz_entry_t *entry); /*%< * Get domain name for 'entry' * * Requires: * \li 'entry' to be non NULL. * * Returns: * \li domain name for entry. */ isc_result_t dns_catz_entry_new(isc_mem_t *mctx, const dns_name_t *domain, dns_catz_entry_t **nentryp); /*%< * Allocate a new catz_entry on 'mctx', with the name 'domain' * * Requires: * \li 'mctx' to be a valid memory context. * \li 'domain' to be valid dns_name or NULL. * \li 'nentryp' to be non NULL, *nentryp to be NULL. * * Returns: * \li ISC_R_SUCCESS on success * \li ISC_R_NOMEMORY on allocation failure */ isc_result_t dns_catz_entry_copy(dns_catz_zone_t *zone, const dns_catz_entry_t *entry, dns_catz_entry_t **nentryp); /*%< * Allocate a new catz_entry and deep copy 'entry' into 'nentryp'. * * Requires: * \li 'mctx' to be a valid memory context. * \li 'entry' to be non NULL. * \li 'nentryp' to be non NULL, *nentryp to be NULL. * * Returns: * \li ISC_R_SUCCESS on success * \li ISC_R_NOMEMORY on allocation failure */ void dns_catz_entry_attach(dns_catz_entry_t *entry, dns_catz_entry_t **entryp); /*%< * Attach an entry * * Requires: * \li 'entry' is a valid dns_catz_entry_t. * \li 'entryp' is not NULL and '*entryp' is NULL. */ void dns_catz_entry_detach(dns_catz_zone_t *zone, dns_catz_entry_t **entryp); /*%< * Detach an entry, free if no further references * * Requires: * \li 'zone' is a valid dns_catz_zone_t. * \li 'entryp' is not NULL and '*entryp' is not NULL. */ bool dns_catz_entry_validate(const dns_catz_entry_t *entry); /*%< * Validate whether entry is correct. * (NOT YET IMPLEMENTED: always returns true) * * Requires: *\li 'entry' is a valid dns_catz_entry_t. */ bool dns_catz_entry_cmp(const dns_catz_entry_t *ea, const dns_catz_entry_t *eb); /*%< * Deep compare two entries * * Requires: * \li 'ea' is a valid dns_catz_entry_t. * \li 'eb' is a valid dns_catz_entry_t. * * Returns: * \li 'true' if entries are the same. * \li 'false' if the entries differ. */ void dns_catz_zone_attach(dns_catz_zone_t *zone, dns_catz_zone_t **zonep); /*%< * Attach a catzone * * Requires: * \li 'zone' is a valid dns_catz_zone_t. * \li 'zonep' is not NULL and '*zonep' is NULL. */ void dns_catz_zone_detach(dns_catz_zone_t **zonep); /*%< * Detach a zone, free if no further references * * Requires: * \li 'zonep' is not NULL and '*zonep' is not NULL. */ isc_result_t dns_catz_new_zone(dns_catz_zones_t *catzs, dns_catz_zone_t **zonep, const dns_name_t *name); /*%< * Allocate a new catz zone on catzs mctx * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'zonep' is not NULL and '*zonep' is NULL. * \li 'name' is a valid dns_name_t. * */ dns_name_t * dns_catz_zone_getname(dns_catz_zone_t *zone); /*%< * Get catalog zone name * * Requires: * \li 'zone' is a valid dns_catz_zone_t. */ dns_catz_options_t * dns_catz_zone_getdefoptions(dns_catz_zone_t *zone); /*%< * Get default member zone options for catalog zone 'zone' * * Requires: * \li 'zone' is a valid dns_catz_zone_t. */ void dns_catz_zone_resetdefoptions(dns_catz_zone_t *zone); /*%< * Reset the default member zone options for catalog zone 'zone' to * the default values. * * Requires: * \li 'zone' is a valid dns_catz_zone_t. */ isc_result_t dns_catz_zones_merge(dns_catz_zone_t *target, dns_catz_zone_t *newzone); /*%< * Merge 'newzone' into 'target', calling addzone/delzone/modzone * (from zone->catzs->zmm) for appropriate member zones. * * Requires: * \li 'orig' is a valid dns_catz_zone_t. * \li 'newzone' is not NULL and '*newzone' is not NULL. * */ isc_result_t dns_catz_update_process(dns_catz_zones_t *catzs, dns_catz_zone_t *zone, const dns_name_t *src_name, dns_rdataset_t *rdataset); /*%< * Process a single rdataset from a catalog zone 'zone' update, src_name is the * record name. * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'zone' is a valid dns_catz_zone_t. * \li 'src_name' is a valid dns_name_t. * \li 'rdataset' is valid rdataset. */ isc_result_t dns_catz_generate_masterfilename(dns_catz_zone_t *zone, dns_catz_entry_t *entry, isc_buffer_t **buffer); /*%< * Generate master file name and put it into *buffer (might be reallocated). * The general format of the file name is: * __catz__catalog.zone.name__member_zone_name.db * But if it's too long it's shortened to: * __catz__unique_hash_generated_from_the_above.db * * Requires: * \li 'zone' is a valid dns_catz_zone_t. * \li 'entry' is a valid dns_catz_entry_t. * \li 'buffer' is not NULL and '*buffer' is not NULL. */ isc_result_t dns_catz_generate_zonecfg(dns_catz_zone_t *zone, dns_catz_entry_t *entry, isc_buffer_t **buf); /*%< * Generate a zone config entry (in text form) from dns_catz_entry and puts * it into *buf. buf might be reallocated. * * Requires: * \li 'zone' is a valid dns_catz_zone_t. * \li 'entry' is a valid dns_catz_entry_t. * \li 'buf' is not NULL and '*buf' is NULL. * */ /* Methods provided by named to dynamically modify the member zones */ /* xxxwpk TODO config! */ typedef isc_result_t (*dns_catz_zoneop_fn_t)(dns_catz_entry_t *entry, dns_catz_zone_t *origin, dns_view_t *view, isc_taskmgr_t *taskmgr, void *udata); struct dns_catz_zonemodmethods { dns_catz_zoneop_fn_t addzone; dns_catz_zoneop_fn_t modzone; dns_catz_zoneop_fn_t delzone; void *udata; }; isc_result_t dns_catz_new_zones(dns_catz_zones_t **catzsp, dns_catz_zonemodmethods_t *zmm, isc_mem_t *mctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr); /*%< * Allocate a new catz_zones object, a collection storing all catalog zones * for a view. * * Requires: * \li 'catzsp' is not NULL and '*catzsp' is NULL. * \li 'zmm' is not NULL. * */ isc_result_t dns_catz_add_zone(dns_catz_zones_t *catzs, const dns_name_t *name, dns_catz_zone_t **catzp); /*%< * Allocate a new catz named 'name' and put it in 'catzs' collection. * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'name' is a valid dns_name_t. * \li 'zonep' is not NULL and *zonep is NULL. * */ dns_catz_zone_t * dns_catz_get_zone(dns_catz_zones_t *catzs, const dns_name_t *name); /*%< * Returns a zone named 'name' from collection 'catzs' * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'name' is a valid dns_name_t. */ void dns_catz_catzs_attach(dns_catz_zones_t *catzs, dns_catz_zones_t **catzsp); /*%< * Attach 'catzs' to 'catzsp'. * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'catzsp' is not NULL and *catzsp is NULL. */ void dns_catz_catzs_detach(dns_catz_zones_t **catzsp); /*%< * Detach 'catzsp', free if no further references. * * Requires: * \li 'catzsp' is not NULL and *catzsp is not NULL. */ void dns_catz_catzs_set_view(dns_catz_zones_t *catzs, dns_view_t *view); /*%< * Set a view for 'catzs'. * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'catzs->view' is NULL or 'catzs->view' == 'view'. */ isc_result_t dns_catz_dbupdate_callback(dns_db_t *db, void *fn_arg); /*%< * Callback for update of catalog zone database. * If there was no catalog zone update recently it launches an * update_taskaction immediately. * If there was an update recently it schedules update_taskaction for some time * in the future. * If there is an update scheduled it replaces old db version with a new one. * * Requires: * \li 'db' is a valid database. * \li 'fn_arg' is not NULL (casted to dns_catz_zones_t*). */ void dns_catz_update_taskaction(isc_task_t *task, isc_event_t *event); /*%< * Task that launches dns_catz_update_from_db. * * Requires: * \li 'event' is not NULL. */ void dns_catz_update_from_db(dns_db_t *db, dns_catz_zones_t *catzs); /*%< * Process an updated database for a catalog zone. * It creates a new catz, iterates over database to fill it with content, and * then merges new catz into old catz. * * Requires: * \li 'db' is a valid DB. * \li 'catzs' is a valid dns_catz_zones_t. * */ void dns_catz_prereconfig(dns_catz_zones_t *catzs); /*%< * Called before reconfig, clears 'active' flag on all the zones in set * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * */ void dns_catz_postreconfig(dns_catz_zones_t *catzs); /*%< * Called after reconfig, walks through all zones in set, removes those * inactive and force reload of those with changed configuration. * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. */ isc_result_t dns_catz_get_iterator(dns_catz_zone_t *catz, isc_ht_iter_t **itp); /*%< * Get the hashtable iterator on catalog zone members, point '*itp' to it. * * Requires: * \li 'catzs' is a valid dns_catz_zones_t. * \li 'itp' is not NULL and '*itp' is NULL. * * Returns: * \li #ISC_R_SUCCESS -- success * \li Any other value -- failure */ ISC_LANG_ENDDECLS #endif /* DNS_CATZ_H_ */