1*4afad4b7Schristos /* $NetBSD: masterdump.h,v 1.1 2024/02/18 20:57:37 christos Exp $ */ 2*4afad4b7Schristos 3*4afad4b7Schristos /* 4*4afad4b7Schristos * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5*4afad4b7Schristos * 6*4afad4b7Schristos * SPDX-License-Identifier: MPL-2.0 7*4afad4b7Schristos * 8*4afad4b7Schristos * This Source Code Form is subject to the terms of the Mozilla Public 9*4afad4b7Schristos * License, v. 2.0. If a copy of the MPL was not distributed with this 10*4afad4b7Schristos * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11*4afad4b7Schristos * 12*4afad4b7Schristos * See the COPYRIGHT file distributed with this work for additional 13*4afad4b7Schristos * information regarding copyright ownership. 14*4afad4b7Schristos */ 15*4afad4b7Schristos 16*4afad4b7Schristos #ifndef DNS_MASTERDUMP_H 17*4afad4b7Schristos #define DNS_MASTERDUMP_H 1 18*4afad4b7Schristos 19*4afad4b7Schristos /*! \file dns/masterdump.h */ 20*4afad4b7Schristos 21*4afad4b7Schristos /*** 22*4afad4b7Schristos *** Imports 23*4afad4b7Schristos ***/ 24*4afad4b7Schristos 25*4afad4b7Schristos #include <stdio.h> 26*4afad4b7Schristos 27*4afad4b7Schristos #include <isc/lang.h> 28*4afad4b7Schristos 29*4afad4b7Schristos #include <dns/types.h> 30*4afad4b7Schristos 31*4afad4b7Schristos /*** 32*4afad4b7Schristos *** Types 33*4afad4b7Schristos ***/ 34*4afad4b7Schristos 35*4afad4b7Schristos typedef struct dns_master_style dns_master_style_t; 36*4afad4b7Schristos 37*4afad4b7Schristos /*** 38*4afad4b7Schristos *** Definitions 39*4afad4b7Schristos ***/ 40*4afad4b7Schristos 41*4afad4b7Schristos /* 42*4afad4b7Schristos * Flags affecting master file formatting. Flags 0x0000FFFF 43*4afad4b7Schristos * define the formatting of the rdata part and are defined in 44*4afad4b7Schristos * rdata.h. 45*4afad4b7Schristos */ 46*4afad4b7Schristos 47*4afad4b7Schristos /*% Omit the owner name when possible. */ 48*4afad4b7Schristos #define DNS_STYLEFLAG_OMIT_OWNER 0x000010000ULL 49*4afad4b7Schristos 50*4afad4b7Schristos /*% 51*4afad4b7Schristos * Omit the TTL when possible. If DNS_STYLEFLAG_TTL is 52*4afad4b7Schristos * also set, this means no TTLs are ever printed 53*4afad4b7Schristos * because $TTL directives are generated before every 54*4afad4b7Schristos * change in the TTL. In this case, no columns need to 55*4afad4b7Schristos * be reserved for the TTL. Master files generated with 56*4afad4b7Schristos * these options will be rejected by BIND 4.x because it 57*4afad4b7Schristos * does not recognize the $TTL directive. 58*4afad4b7Schristos * 59*4afad4b7Schristos * If DNS_STYLEFLAG_TTL is not also set, the TTL will be 60*4afad4b7Schristos * omitted when it is equal to the previous TTL. 61*4afad4b7Schristos * This is correct according to RFC1035, but the 62*4afad4b7Schristos * TTLs may be silently misinterpreted by older 63*4afad4b7Schristos * versions of BIND which use the SOA MINTTL as a 64*4afad4b7Schristos * default TTL value. 65*4afad4b7Schristos */ 66*4afad4b7Schristos #define DNS_STYLEFLAG_OMIT_TTL 0x000020000ULL 67*4afad4b7Schristos 68*4afad4b7Schristos /*% Omit the class when possible. */ 69*4afad4b7Schristos #define DNS_STYLEFLAG_OMIT_CLASS 0x000040000ULL 70*4afad4b7Schristos 71*4afad4b7Schristos /*% Output $TTL directives. */ 72*4afad4b7Schristos #define DNS_STYLEFLAG_TTL 0x000080000ULL 73*4afad4b7Schristos 74*4afad4b7Schristos /*% 75*4afad4b7Schristos * Output $ORIGIN directives and print owner names relative to 76*4afad4b7Schristos * the origin when possible. 77*4afad4b7Schristos */ 78*4afad4b7Schristos #define DNS_STYLEFLAG_REL_OWNER 0x000100000ULL 79*4afad4b7Schristos 80*4afad4b7Schristos /*% Print domain names in RR data in relative form when possible. 81*4afad4b7Schristos * For this to take effect, DNS_STYLEFLAG_REL_OWNER must also be set. */ 82*4afad4b7Schristos #define DNS_STYLEFLAG_REL_DATA 0x000200000ULL 83*4afad4b7Schristos 84*4afad4b7Schristos /*% Print the trust level of each rdataset. */ 85*4afad4b7Schristos #define DNS_STYLEFLAG_TRUST 0x000400000ULL 86*4afad4b7Schristos 87*4afad4b7Schristos /*% Print negative caching entries. */ 88*4afad4b7Schristos #define DNS_STYLEFLAG_NCACHE 0x000800000ULL 89*4afad4b7Schristos 90*4afad4b7Schristos /*% Never print the TTL. */ 91*4afad4b7Schristos #define DNS_STYLEFLAG_NO_TTL 0x001000000ULL 92*4afad4b7Schristos 93*4afad4b7Schristos /*% Never print the CLASS. */ 94*4afad4b7Schristos #define DNS_STYLEFLAG_NO_CLASS 0x002000000ULL 95*4afad4b7Schristos 96*4afad4b7Schristos /*% Report re-signing time. */ 97*4afad4b7Schristos #define DNS_STYLEFLAG_RESIGN 0x004000000ULL 98*4afad4b7Schristos 99*4afad4b7Schristos /*% Don't printout the cryptographic parts of DNSSEC records. */ 100*4afad4b7Schristos #define DNS_STYLEFLAG_NOCRYPTO 0x008000000ULL 101*4afad4b7Schristos 102*4afad4b7Schristos /*% Comment out data by prepending with ";" */ 103*4afad4b7Schristos #define DNS_STYLEFLAG_COMMENTDATA 0x010000000ULL 104*4afad4b7Schristos 105*4afad4b7Schristos /*% Print TTL with human-readable units. */ 106*4afad4b7Schristos #define DNS_STYLEFLAG_TTL_UNITS 0x020000000ULL 107*4afad4b7Schristos 108*4afad4b7Schristos /*% Indent output. */ 109*4afad4b7Schristos #define DNS_STYLEFLAG_INDENT 0x040000000ULL 110*4afad4b7Schristos 111*4afad4b7Schristos /*% Output in YAML style. */ 112*4afad4b7Schristos #define DNS_STYLEFLAG_YAML 0x080000000ULL 113*4afad4b7Schristos 114*4afad4b7Schristos /*% Print ECS cache entries as comments (reserved for future use). */ 115*4afad4b7Schristos #define DNS_STYLEFLAG_ECSCACHE 0x100000000ULL 116*4afad4b7Schristos 117*4afad4b7Schristos /*% Print expired cache entries. */ 118*4afad4b7Schristos #define DNS_STYLEFLAG_EXPIRED 0x200000000ULL 119*4afad4b7Schristos 120*4afad4b7Schristos ISC_LANG_BEGINDECLS 121*4afad4b7Schristos 122*4afad4b7Schristos /*** 123*4afad4b7Schristos *** Constants 124*4afad4b7Schristos ***/ 125*4afad4b7Schristos 126*4afad4b7Schristos /*% 127*4afad4b7Schristos * The default master file style. 128*4afad4b7Schristos * 129*4afad4b7Schristos * This uses $TTL directives to avoid the need to dedicate a 130*4afad4b7Schristos * tab stop for the TTL. The class is only printed for the first 131*4afad4b7Schristos * rrset in the file and shares a tab stop with the RR type. 132*4afad4b7Schristos */ 133*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_default; 134*4afad4b7Schristos 135*4afad4b7Schristos /*% 136*4afad4b7Schristos * A master file style that dumps zones to a very generic format easily 137*4afad4b7Schristos * imported/checked with external tools. 138*4afad4b7Schristos */ 139*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_full; 140*4afad4b7Schristos 141*4afad4b7Schristos /*% 142*4afad4b7Schristos * A master file style that prints explicit TTL values on each 143*4afad4b7Schristos * record line, never using $TTL statements. The TTL has a tab 144*4afad4b7Schristos * stop of its own, but the class and type share one. 145*4afad4b7Schristos */ 146*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t 147*4afad4b7Schristos dns_master_style_explicitttl; 148*4afad4b7Schristos 149*4afad4b7Schristos /*% 150*4afad4b7Schristos * A master style format designed for cache files. It prints explicit TTL 151*4afad4b7Schristos * values on each record line and never uses $ORIGIN or relative names. 152*4afad4b7Schristos */ 153*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_cache; 154*4afad4b7Schristos 155*4afad4b7Schristos /*% 156*4afad4b7Schristos * A master style format designed for cache files. The same as above but 157*4afad4b7Schristos * this also prints expired entries. 158*4afad4b7Schristos */ 159*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t 160*4afad4b7Schristos dns_master_style_cache_with_expired; 161*4afad4b7Schristos 162*4afad4b7Schristos /*% 163*4afad4b7Schristos * A master style that prints name, ttl, class, type, and value on 164*4afad4b7Schristos * every line. Similar to explicitttl above, but more verbose. 165*4afad4b7Schristos * Intended for generating master files which can be easily parsed 166*4afad4b7Schristos * by perl scripts and similar applications. 167*4afad4b7Schristos */ 168*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_simple; 169*4afad4b7Schristos 170*4afad4b7Schristos /*% 171*4afad4b7Schristos * The style used for debugging, "dig" output, etc. 172*4afad4b7Schristos */ 173*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_debug; 174*4afad4b7Schristos 175*4afad4b7Schristos /*% 176*4afad4b7Schristos * Similar to dns_master_style_debug but data is prepended with ";" 177*4afad4b7Schristos */ 178*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_comment; 179*4afad4b7Schristos 180*4afad4b7Schristos /*% 181*4afad4b7Schristos * Similar to dns_master_style_debug but data is indented with "\t" (tab) 182*4afad4b7Schristos */ 183*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_indent; 184*4afad4b7Schristos 185*4afad4b7Schristos /*% 186*4afad4b7Schristos * The style used for dumping "key" zones. 187*4afad4b7Schristos */ 188*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_keyzone; 189*4afad4b7Schristos 190*4afad4b7Schristos /*% 191*4afad4b7Schristos * YAML-compatible output 192*4afad4b7Schristos */ 193*4afad4b7Schristos LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_yaml; 194*4afad4b7Schristos 195*4afad4b7Schristos /*** 196*4afad4b7Schristos *** Functions 197*4afad4b7Schristos ***/ 198*4afad4b7Schristos 199*4afad4b7Schristos void 200*4afad4b7Schristos dns_dumpctx_attach(dns_dumpctx_t *source, dns_dumpctx_t **target); 201*4afad4b7Schristos /*%< 202*4afad4b7Schristos * Attach to a dump context. 203*4afad4b7Schristos * 204*4afad4b7Schristos * Require: 205*4afad4b7Schristos *\li 'source' to be valid. 206*4afad4b7Schristos *\li 'target' to be non NULL and '*target' to be NULL. 207*4afad4b7Schristos */ 208*4afad4b7Schristos 209*4afad4b7Schristos void 210*4afad4b7Schristos dns_dumpctx_detach(dns_dumpctx_t **dctxp); 211*4afad4b7Schristos /*%< 212*4afad4b7Schristos * Detach from a dump context. 213*4afad4b7Schristos * 214*4afad4b7Schristos * Require: 215*4afad4b7Schristos *\li 'dctxp' to point to a valid dump context. 216*4afad4b7Schristos * 217*4afad4b7Schristos * Ensures: 218*4afad4b7Schristos *\li '*dctxp' is NULL. 219*4afad4b7Schristos */ 220*4afad4b7Schristos 221*4afad4b7Schristos void 222*4afad4b7Schristos dns_dumpctx_cancel(dns_dumpctx_t *dctx); 223*4afad4b7Schristos /*%< 224*4afad4b7Schristos * Cancel a in progress dump. 225*4afad4b7Schristos * 226*4afad4b7Schristos * Require: 227*4afad4b7Schristos *\li 'dctx' to be valid. 228*4afad4b7Schristos */ 229*4afad4b7Schristos 230*4afad4b7Schristos dns_dbversion_t * 231*4afad4b7Schristos dns_dumpctx_version(dns_dumpctx_t *dctx); 232*4afad4b7Schristos /*%< 233*4afad4b7Schristos * Return the version handle (if any) of the database being dumped. 234*4afad4b7Schristos * 235*4afad4b7Schristos * Require: 236*4afad4b7Schristos *\li 'dctx' to be valid. 237*4afad4b7Schristos */ 238*4afad4b7Schristos 239*4afad4b7Schristos dns_db_t * 240*4afad4b7Schristos dns_dumpctx_db(dns_dumpctx_t *dctx); 241*4afad4b7Schristos /*%< 242*4afad4b7Schristos * Return the database being dumped. 243*4afad4b7Schristos * 244*4afad4b7Schristos * Require: 245*4afad4b7Schristos *\li 'dctx' to be valid. 246*4afad4b7Schristos */ 247*4afad4b7Schristos 248*4afad4b7Schristos /*@{*/ 249*4afad4b7Schristos isc_result_t 250*4afad4b7Schristos dns_master_dumptostreamasync(isc_mem_t *mctx, dns_db_t *db, 251*4afad4b7Schristos dns_dbversion_t *version, 252*4afad4b7Schristos const dns_master_style_t *style, FILE *f, 253*4afad4b7Schristos isc_task_t *task, dns_dumpdonefunc_t done, 254*4afad4b7Schristos void *done_arg, dns_dumpctx_t **dctxp); 255*4afad4b7Schristos 256*4afad4b7Schristos isc_result_t 257*4afad4b7Schristos dns_master_dumptostream(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, 258*4afad4b7Schristos const dns_master_style_t *style, 259*4afad4b7Schristos dns_masterformat_t format, 260*4afad4b7Schristos dns_masterrawheader_t *header, FILE *f); 261*4afad4b7Schristos /*%< 262*4afad4b7Schristos * Dump the database 'db' to the steam 'f' in the specified format by 263*4afad4b7Schristos * 'format'. If the format is dns_masterformat_text (the RFC1035 format), 264*4afad4b7Schristos * 'style' specifies the file style (e.g., &dns_master_style_default). 265*4afad4b7Schristos * 266*4afad4b7Schristos * If 'format' is dns_masterformat_raw, then 'header' can contain 267*4afad4b7Schristos * information to be written to the file header. 268*4afad4b7Schristos * 269*4afad4b7Schristos * Temporary dynamic memory may be allocated from 'mctx'. 270*4afad4b7Schristos * 271*4afad4b7Schristos * Require: 272*4afad4b7Schristos *\li 'task' to be valid. 273*4afad4b7Schristos *\li 'done' to be non NULL. 274*4afad4b7Schristos *\li 'dctxp' to be non NULL && '*dctxp' to be NULL. 275*4afad4b7Schristos * 276*4afad4b7Schristos * Returns: 277*4afad4b7Schristos *\li ISC_R_SUCCESS 278*4afad4b7Schristos *\li ISC_R_NOMEMORY 279*4afad4b7Schristos *\li Any database or rrset iterator error. 280*4afad4b7Schristos *\li Any dns_rdata_totext() error code. 281*4afad4b7Schristos */ 282*4afad4b7Schristos /*@}*/ 283*4afad4b7Schristos 284*4afad4b7Schristos /*@{*/ 285*4afad4b7Schristos 286*4afad4b7Schristos isc_result_t 287*4afad4b7Schristos dns_master_dumpasync(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, 288*4afad4b7Schristos const dns_master_style_t *style, const char *filename, 289*4afad4b7Schristos isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg, 290*4afad4b7Schristos dns_dumpctx_t **dctxp, dns_masterformat_t format, 291*4afad4b7Schristos dns_masterrawheader_t *header); 292*4afad4b7Schristos 293*4afad4b7Schristos isc_result_t 294*4afad4b7Schristos dns_master_dump(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, 295*4afad4b7Schristos const dns_master_style_t *style, const char *filename, 296*4afad4b7Schristos dns_masterformat_t format, dns_masterrawheader_t *header); 297*4afad4b7Schristos 298*4afad4b7Schristos /*%< 299*4afad4b7Schristos * Dump the database 'db' to the file 'filename' in the specified format by 300*4afad4b7Schristos * 'format'. If the format is dns_masterformat_text (the RFC1035 format), 301*4afad4b7Schristos * 'style' specifies the file style (e.g., &dns_master_style_default). 302*4afad4b7Schristos * 303*4afad4b7Schristos * If 'format' is dns_masterformat_raw, then 'header' can contain 304*4afad4b7Schristos * information to be written to the file header. 305*4afad4b7Schristos * 306*4afad4b7Schristos * Temporary dynamic memory may be allocated from 'mctx'. 307*4afad4b7Schristos * 308*4afad4b7Schristos * Returns: 309*4afad4b7Schristos *\li ISC_R_SUCCESS 310*4afad4b7Schristos *\li ISC_R_NOMEMORY 311*4afad4b7Schristos *\li Any database or rrset iterator error. 312*4afad4b7Schristos *\li Any dns_rdata_totext() error code. 313*4afad4b7Schristos */ 314*4afad4b7Schristos /*@}*/ 315*4afad4b7Schristos 316*4afad4b7Schristos isc_result_t 317*4afad4b7Schristos dns_master_rdatasettotext(const dns_name_t *owner_name, 318*4afad4b7Schristos dns_rdataset_t *rdataset, 319*4afad4b7Schristos const dns_master_style_t *style, dns_indent_t *indent, 320*4afad4b7Schristos isc_buffer_t *target); 321*4afad4b7Schristos /*%< 322*4afad4b7Schristos * Convert 'rdataset' to text format, storing the result in 'target'. 323*4afad4b7Schristos * 324*4afad4b7Schristos * Notes: 325*4afad4b7Schristos *\li The rdata cursor position will be changed. 326*4afad4b7Schristos * 327*4afad4b7Schristos * Requires: 328*4afad4b7Schristos *\li 'rdataset' is a valid non-question rdataset. 329*4afad4b7Schristos * 330*4afad4b7Schristos *\li 'rdataset' is not empty. 331*4afad4b7Schristos */ 332*4afad4b7Schristos 333*4afad4b7Schristos isc_result_t 334*4afad4b7Schristos dns_master_questiontotext(const dns_name_t *owner_name, 335*4afad4b7Schristos dns_rdataset_t *rdataset, 336*4afad4b7Schristos const dns_master_style_t *style, 337*4afad4b7Schristos isc_buffer_t *target); 338*4afad4b7Schristos 339*4afad4b7Schristos isc_result_t 340*4afad4b7Schristos dns_master_dumpnodetostream(isc_mem_t *mctx, dns_db_t *db, 341*4afad4b7Schristos dns_dbversion_t *version, dns_dbnode_t *node, 342*4afad4b7Schristos const dns_name_t *name, 343*4afad4b7Schristos const dns_master_style_t *style, FILE *f); 344*4afad4b7Schristos 345*4afad4b7Schristos isc_result_t 346*4afad4b7Schristos dns_master_dumpnode(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, 347*4afad4b7Schristos dns_dbnode_t *node, const dns_name_t *name, 348*4afad4b7Schristos const dns_master_style_t *style, const char *filename); 349*4afad4b7Schristos 350*4afad4b7Schristos dns_masterstyle_flags_t 351*4afad4b7Schristos dns_master_styleflags(const dns_master_style_t *style); 352*4afad4b7Schristos 353*4afad4b7Schristos isc_result_t 354*4afad4b7Schristos dns_master_stylecreate(dns_master_style_t **style, 355*4afad4b7Schristos dns_masterstyle_flags_t flags, unsigned int ttl_column, 356*4afad4b7Schristos unsigned int class_column, unsigned int type_column, 357*4afad4b7Schristos unsigned int rdata_column, unsigned int line_length, 358*4afad4b7Schristos unsigned int tab_width, unsigned int split_width, 359*4afad4b7Schristos isc_mem_t *mctx); 360*4afad4b7Schristos 361*4afad4b7Schristos void 362*4afad4b7Schristos dns_master_styledestroy(dns_master_style_t **style, isc_mem_t *mctx); 363*4afad4b7Schristos 364*4afad4b7Schristos ISC_LANG_ENDDECLS 365*4afad4b7Schristos 366*4afad4b7Schristos #endif /* DNS_MASTERDUMP_H */ 367