"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/dns/include/dns/catz.h" (4 Sep 2020, 11892 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "catz.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef DNS_CATZ_H
   13 #define DNS_CATZ_H 1
   14 
   15 #include <inttypes.h>
   16 #include <stdbool.h>
   17 
   18 #include <isc/ht.h>
   19 #include <isc/lang.h>
   20 #include <isc/refcount.h>
   21 #include <isc/rwlock.h>
   22 #include <isc/time.h>
   23 #include <isc/timer.h>
   24 
   25 #include <dns/db.h>
   26 #include <dns/fixedname.h>
   27 #include <dns/ipkeylist.h>
   28 #include <dns/rdata.h>
   29 #include <dns/types.h>
   30 
   31 ISC_LANG_BEGINDECLS
   32 
   33 #define DNS_CATZ_ERROR_LEVEL  ISC_LOG_WARNING
   34 #define DNS_CATZ_INFO_LEVEL   ISC_LOG_INFO
   35 #define DNS_CATZ_DEBUG_LEVEL1 ISC_LOG_DEBUG(1)
   36 #define DNS_CATZ_DEBUG_LEVEL2 ISC_LOG_DEBUG(2)
   37 #define DNS_CATZ_DEBUG_LEVEL3 ISC_LOG_DEBUG(3)
   38 #define DNS_CATZ_DEBUG_QUIET  (DNS_CATZ_DEBUG_LEVEL3 + 1)
   39 
   40 /*
   41  * Catalog Zones functions and structures.
   42  */
   43 
   44 /*
   45  * Options for a member zone in a catalog
   46  */
   47 struct dns_catz_entry_options {
   48     /*
   49      * Options that can be overridden in catalog zone
   50      */
   51     /* default-masters definition */
   52     dns_ipkeylist_t masters;
   53 
   54     /* both as text in config format, NULL if none */
   55     isc_buffer_t *allow_query;
   56     isc_buffer_t *allow_transfer;
   57 
   58     /*
   59      * Options that are only set in named.conf
   60      */
   61     /* zone-directory definition */
   62     char *zonedir;
   63 
   64     /* zone should not be stored on disk (no 'file' statement in def */
   65     bool in_memory;
   66     /*
   67      * Minimal interval between catalog zone updates, if a new version
   68      * of catalog zone is received before this time the update will be
   69      * postponed. This is a global option for the whole catalog zone.
   70      */
   71     uint32_t min_update_interval;
   72 };
   73 
   74 void
   75 dns_catz_options_init(dns_catz_options_t *options);
   76 /*%<
   77  * Initialize 'options' to NULL values.
   78  *
   79  * Requires:
   80  * \li  'options' to be non NULL.
   81  */
   82 
   83 void
   84 dns_catz_options_free(dns_catz_options_t *options, isc_mem_t *mctx);
   85 /*%<
   86  * Free 'options' contents into 'mctx'. ('options' itself is not freed.)
   87  *
   88  * Requires:
   89  * \li  'options' to be non NULL.
   90  * \li  'mctx' to be a valid memory context.
   91  */
   92 
   93 isc_result_t
   94 dns_catz_options_copy(isc_mem_t *mctx, const dns_catz_options_t *opts,
   95               dns_catz_options_t *nopts);
   96 /*%<
   97  * Duplicate 'opts' into 'nopts', allocating space from 'mctx'.
   98  *
   99  * Requires:
  100  * \li  'mctx' to be a valid memory context.
  101  * \li  'options' to be non NULL and valid options.
  102  * \li  'nopts' to be non NULL.
  103  */
  104 
  105 isc_result_t
  106 dns_catz_options_setdefault(isc_mem_t *mctx, const dns_catz_options_t *defaults,
  107                 dns_catz_options_t *opts);
  108 /*%<
  109  * Replace empty values in 'opts' with values from 'defaults'
  110  *
  111  * Requires:
  112  * \li  'mctx' to be a valid memory context.
  113  * \li  'defaults' to be non NULL and valid options.
  114  * \li  'opts' to be non NULL.
  115  */
  116 
  117 dns_name_t *
  118 dns_catz_entry_getname(dns_catz_entry_t *entry);
  119 /*%<
  120  * Get domain name for 'entry'
  121  *
  122  * Requires:
  123  * \li  'entry' to be non NULL.
  124  *
  125  * Returns:
  126  * \li  domain name for entry.
  127  */
  128 
  129 isc_result_t
  130 dns_catz_entry_new(isc_mem_t *mctx, const dns_name_t *domain,
  131            dns_catz_entry_t **nentryp);
  132 /*%<
  133  * Allocate a new catz_entry on 'mctx', with the name 'domain'
  134  *
  135  * Requires:
  136  * \li  'mctx' to be a valid memory context.
  137  * \li  'domain' to be valid dns_name or NULL.
  138  * \li  'nentryp' to be non NULL, *nentryp to be NULL.
  139  *
  140  * Returns:
  141  * \li  ISC_R_SUCCESS on success
  142  * \li  ISC_R_NOMEMORY on allocation failure
  143  */
  144 
  145 isc_result_t
  146 dns_catz_entry_copy(dns_catz_zone_t *zone, const dns_catz_entry_t *entry,
  147             dns_catz_entry_t **nentryp);
  148 /*%<
  149  * Allocate a new catz_entry and deep copy 'entry' into 'nentryp'.
  150  *
  151  * Requires:
  152  * \li  'mctx' to be a valid memory context.
  153  * \li  'entry' to be non NULL.
  154  * \li  'nentryp' to be non NULL, *nentryp to be NULL.
  155  *
  156  * Returns:
  157  * \li  ISC_R_SUCCESS on success
  158  * \li  ISC_R_NOMEMORY on allocation failure
  159  */
  160 
  161 void
  162 dns_catz_entry_attach(dns_catz_entry_t *entry, dns_catz_entry_t **entryp);
  163 /*%<
  164  * Attach an entry
  165  *
  166  * Requires:
  167  * \li  'entry' is a valid dns_catz_entry_t.
  168  * \li  'entryp' is not NULL and '*entryp' is NULL.
  169  */
  170 
  171 void
  172 dns_catz_entry_detach(dns_catz_zone_t *zone, dns_catz_entry_t **entryp);
  173 /*%<
  174  * Detach an entry, free if no further references
  175  *
  176  * Requires:
  177  * \li  'zone' is a valid dns_catz_zone_t.
  178  * \li  'entryp' is not NULL and '*entryp' is not NULL.
  179  */
  180 
  181 bool
  182 dns_catz_entry_validate(const dns_catz_entry_t *entry);
  183 /*%<
  184  * Validate whether entry is correct.
  185  * (NOT YET IMPLEMENTED: always returns true)
  186  *
  187  * Requires:
  188  *\li   'entry' is a valid dns_catz_entry_t.
  189  */
  190 
  191 bool
  192 dns_catz_entry_cmp(const dns_catz_entry_t *ea, const dns_catz_entry_t *eb);
  193 /*%<
  194  * Deep compare two entries
  195  *
  196  * Requires:
  197  * \li  'ea' is a valid dns_catz_entry_t.
  198  * \li  'eb' is a valid dns_catz_entry_t.
  199  *
  200  * Returns:
  201  * \li 'true' if entries are the same.
  202  * \li 'false' if the entries differ.
  203  */
  204 
  205 void
  206 dns_catz_zone_attach(dns_catz_zone_t *zone, dns_catz_zone_t **zonep);
  207 /*%<
  208  * Attach a catzone
  209  *
  210  * Requires:
  211  * \li  'zone' is a valid dns_catz_zone_t.
  212  * \li  'zonep' is not NULL and '*zonep' is NULL.
  213  */
  214 
  215 void
  216 dns_catz_zone_detach(dns_catz_zone_t **zonep);
  217 /*%<
  218  * Detach a zone, free if no further references
  219  *
  220  * Requires:
  221  * \li  'zonep' is not NULL and '*zonep' is not NULL.
  222  */
  223 
  224 isc_result_t
  225 dns_catz_new_zone(dns_catz_zones_t *catzs, dns_catz_zone_t **zonep,
  226           const dns_name_t *name);
  227 /*%<
  228  * Allocate a new catz zone on catzs mctx
  229  *
  230  * Requires:
  231  * \li  'catzs' is a valid dns_catz_zones_t.
  232  * \li  'zonep' is not NULL and '*zonep' is NULL.
  233  * \li  'name' is a valid dns_name_t.
  234  *
  235  */
  236 
  237 dns_name_t *
  238 dns_catz_zone_getname(dns_catz_zone_t *zone);
  239 /*%<
  240  * Get catalog zone name
  241  *
  242  * Requires:
  243  * \li  'zone' is a valid dns_catz_zone_t.
  244  */
  245 
  246 dns_catz_options_t *
  247 dns_catz_zone_getdefoptions(dns_catz_zone_t *zone);
  248 /*%<
  249  * Get default member zone options for catalog zone 'zone'
  250  *
  251  * Requires:
  252  * \li  'zone' is a valid dns_catz_zone_t.
  253  */
  254 
  255 void
  256 dns_catz_zone_resetdefoptions(dns_catz_zone_t *zone);
  257 /*%<
  258  * Reset the default member zone options for catalog zone 'zone' to
  259  * the default values.
  260  *
  261  * Requires:
  262  * \li  'zone' is a valid dns_catz_zone_t.
  263  */
  264 
  265 isc_result_t
  266 dns_catz_zones_merge(dns_catz_zone_t *target, dns_catz_zone_t *newzone);
  267 /*%<
  268  * Merge 'newzone' into 'target', calling addzone/delzone/modzone
  269  * (from zone->catzs->zmm) for appropriate member zones.
  270  *
  271  * Requires:
  272  * \li  'orig' is a valid dns_catz_zone_t.
  273  * \li  'newzone' is not NULL and '*newzone' is not NULL.
  274  *
  275  */
  276 
  277 isc_result_t
  278 dns_catz_update_process(dns_catz_zones_t *catzs, dns_catz_zone_t *zone,
  279             const dns_name_t *src_name, dns_rdataset_t *rdataset);
  280 /*%<
  281  * Process a single rdataset from a catalog zone 'zone' update, src_name is the
  282  * record name.
  283  *
  284  * Requires:
  285  * \li  'catzs' is a valid dns_catz_zones_t.
  286  * \li  'zone' is a valid dns_catz_zone_t.
  287  * \li  'src_name' is a valid dns_name_t.
  288  * \li  'rdataset' is valid rdataset.
  289  */
  290 
  291 isc_result_t
  292 dns_catz_generate_masterfilename(dns_catz_zone_t *zone, dns_catz_entry_t *entry,
  293                  isc_buffer_t **buffer);
  294 /*%<
  295  * Generate master file name and put it into *buffer (might be reallocated).
  296  * The general format of the file name is:
  297  * __catz__catalog.zone.name__member_zone_name.db
  298  * But if it's too long it's shortened to:
  299  * __catz__unique_hash_generated_from_the_above.db
  300  *
  301  * Requires:
  302  * \li  'zone' is a valid dns_catz_zone_t.
  303  * \li  'entry' is a valid dns_catz_entry_t.
  304  * \li  'buffer' is not NULL and '*buffer' is not NULL.
  305  */
  306 
  307 isc_result_t
  308 dns_catz_generate_zonecfg(dns_catz_zone_t *zone, dns_catz_entry_t *entry,
  309               isc_buffer_t **buf);
  310 /*%<
  311  * Generate a zone config entry (in text form) from dns_catz_entry and puts
  312  * it into *buf. buf might be reallocated.
  313  *
  314  * Requires:
  315  * \li  'zone' is a valid dns_catz_zone_t.
  316  * \li  'entry' is a valid dns_catz_entry_t.
  317  * \li  'buf' is not NULL and '*buf' is NULL.
  318  *
  319  */
  320 
  321 /* Methods provided by named to dynamically modify the member zones */
  322 /* xxxwpk TODO config! */
  323 typedef isc_result_t (*dns_catz_zoneop_fn_t)(dns_catz_entry_t *entry,
  324                          dns_catz_zone_t * origin,
  325                          dns_view_t *      view,
  326                          isc_taskmgr_t *   taskmgr,
  327                          void *        udata);
  328 struct dns_catz_zonemodmethods {
  329     dns_catz_zoneop_fn_t addzone;
  330     dns_catz_zoneop_fn_t modzone;
  331     dns_catz_zoneop_fn_t delzone;
  332     void *           udata;
  333 };
  334 
  335 isc_result_t
  336 dns_catz_new_zones(dns_catz_zones_t **catzsp, dns_catz_zonemodmethods_t *zmm,
  337            isc_mem_t *mctx, isc_taskmgr_t *taskmgr,
  338            isc_timermgr_t *timermgr);
  339 /*%<
  340  * Allocate a new catz_zones object, a collection storing all catalog zones
  341  * for a view.
  342  *
  343  * Requires:
  344  * \li 'catzsp' is not NULL and '*catzsp' is NULL.
  345  * \li 'zmm' is not NULL.
  346  *
  347  */
  348 
  349 isc_result_t
  350 dns_catz_add_zone(dns_catz_zones_t *catzs, const dns_name_t *name,
  351           dns_catz_zone_t **catzp);
  352 /*%<
  353  * Allocate a new catz named 'name' and put it in 'catzs' collection.
  354  *
  355  * Requires:
  356  * \li  'catzs' is a valid dns_catz_zones_t.
  357  * \li  'name' is a valid dns_name_t.
  358  * \li  'zonep' is not NULL and *zonep is NULL.
  359  *
  360  */
  361 
  362 dns_catz_zone_t *
  363 dns_catz_get_zone(dns_catz_zones_t *catzs, const dns_name_t *name);
  364 /*%<
  365  * Returns a zone named 'name' from collection 'catzs'
  366  *
  367  * Requires:
  368  * \li  'catzs' is a valid dns_catz_zones_t.
  369  * \li  'name' is a valid dns_name_t.
  370  */
  371 
  372 void
  373 dns_catz_catzs_attach(dns_catz_zones_t *catzs, dns_catz_zones_t **catzsp);
  374 /*%<
  375  * Attach 'catzs' to 'catzsp'.
  376  *
  377  * Requires:
  378  * \li  'catzs' is a valid dns_catz_zones_t.
  379  * \li  'catzsp' is not NULL and *catzsp is NULL.
  380  */
  381 
  382 void
  383 dns_catz_catzs_detach(dns_catz_zones_t **catzsp);
  384 /*%<
  385  * Detach 'catzsp', free if no further references.
  386  *
  387  * Requires:
  388  * \li  'catzsp' is not NULL and *catzsp is not NULL.
  389  */
  390 
  391 void
  392 dns_catz_catzs_set_view(dns_catz_zones_t *catzs, dns_view_t *view);
  393 /*%<
  394  * Set a view for 'catzs'.
  395  *
  396  * Requires:
  397  * \li  'catzs' is a valid dns_catz_zones_t.
  398  * \li  'catzs->view' is NULL or 'catzs->view' == 'view'.
  399  */
  400 
  401 isc_result_t
  402 dns_catz_dbupdate_callback(dns_db_t *db, void *fn_arg);
  403 /*%<
  404  * Callback for update of catalog zone database.
  405  * If there was no catalog zone update recently it launches an
  406  * update_taskaction immediately.
  407  * If there was an update recently it schedules update_taskaction for some time
  408  * in the future.
  409  * If there is an update scheduled it replaces old db version with a new one.
  410  *
  411  * Requires:
  412  * \li  'db' is a valid database.
  413  * \li  'fn_arg' is not NULL (casted to dns_catz_zones_t*).
  414  */
  415 
  416 void
  417 dns_catz_update_taskaction(isc_task_t *task, isc_event_t *event);
  418 /*%<
  419  * Task that launches dns_catz_update_from_db.
  420  *
  421  * Requires:
  422  * \li  'event' is not NULL.
  423  */
  424 
  425 void
  426 dns_catz_update_from_db(dns_db_t *db, dns_catz_zones_t *catzs);
  427 /*%<
  428  * Process an updated database for a catalog zone.
  429  * It creates a new catz, iterates over database to fill it with content, and
  430  * then merges new catz into old catz.
  431  *
  432  * Requires:
  433  * \li  'db' is a valid DB.
  434  * \li  'catzs' is a valid dns_catz_zones_t.
  435  *
  436  */
  437 
  438 void
  439 dns_catz_prereconfig(dns_catz_zones_t *catzs);
  440 /*%<
  441  * Called before reconfig, clears 'active' flag on all the zones in set
  442  *
  443  * Requires:
  444  * \li  'catzs' is a valid dns_catz_zones_t.
  445  *
  446  */
  447 
  448 void
  449 dns_catz_postreconfig(dns_catz_zones_t *catzs);
  450 /*%<
  451  * Called after reconfig, walks through all zones in set, removes those
  452  * inactive and force reload of those with changed configuration.
  453  *
  454  * Requires:
  455  * \li  'catzs' is a valid dns_catz_zones_t.
  456  */
  457 
  458 isc_result_t
  459 dns_catz_get_iterator(dns_catz_zone_t *catz, isc_ht_iter_t **itp);
  460 /*%<
  461  * Get the hashtable iterator on catalog zone members, point '*itp' to it.
  462  *
  463  * Requires:
  464  * \li  'catzs' is a valid dns_catz_zones_t.
  465  * \li  'itp' is not NULL and '*itp' is NULL.
  466  *
  467  * Returns:
  468  * \li #ISC_R_SUCCESS       -- success
  469  * \li Any other value      -- failure
  470  */
  471 
  472 ISC_LANG_ENDDECLS
  473 
  474 #endif /* DNS_CATZ_H_ */