xref: /netbsd-src/external/mpl/dhcp/bind/dist/lib/dns/include/dns/masterdump.h (revision 4afad4b7fa6d4a0d3dedf41d1587a7250710ae54)
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