From 202c68e6a83d582bda4291d6a87cc33cb7dcc98c Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Tue, 1 Oct 2024 19:16:55 -0700 Subject: [PATCH] document optional statements the same, enabled or not the generated grammar for named.conf clauses that may or may not be enabled at compile time will now print the same comment regardless of whether or not they are. previously, the grammar didn't print a comment if an option was enabled, but printed "not configured" if it was disabled. now, in both cases, it will say "optional (only available if configured)". as an incidental fix, clarified the documentation for "named-checkconf -n". --- bin/check/named-checkconf.rst | 4 +- doc/misc/options | 40 +++++++------- lib/isccfg/check.c | 2 +- lib/isccfg/include/isccfg/grammar.h | 86 +++++++++++++++++------------ lib/isccfg/namedconf.c | 46 ++++++++------- lib/isccfg/parser.c | 5 +- 6 files changed, 105 insertions(+), 78 deletions(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index c474169ea6..bdc7933a60 100644 --- a/bin/check/named-checkconf.rst +++ b/bin/check/named-checkconf.rst @@ -73,7 +73,9 @@ Options .. option:: -n - Do not error on options that are disabled in this build. + Do not print errors when encountering options that are disabled in + this build. This allows checking of configuration files for other + builds, in which those options are enabled. .. option:: -p diff --git a/doc/misc/options b/doc/misc/options index eacf693634..b6d4e062e3 100644 --- a/doc/misc/options +++ b/doc/misc/options @@ -37,7 +37,7 @@ http { endpoints { ; ... }; listener-clients ; streams-per-connection ; -}; // may occur multiple times +}; // optional (only available if configured), may occur multiple times key { algorithm ; @@ -129,10 +129,10 @@ options { dnssec-secure-to-insecure ; // obsolete dnssec-update-mode ( maintain | no-resign ); // obsolete dnssec-validation ( yes | no | auto ); - dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // not configured - dnstap-identity ( | none | hostname ); // not configured - dnstap-output ( file | unix ) [ size ( unlimited | ) ] [ versions ( unlimited | ) ] [ suffix ( increment | timestamp ) ]; // not configured - dnstap-version ( | none ); // not configured + dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // optional (only available if configured) + dnstap-identity ( | none | hostname ); // optional (only available if configured) + dnstap-output ( file | unix ) [ size ( unlimited | ) ] [ versions ( unlimited | ) ] [ suffix ( increment | timestamp ) ]; // optional (only available if configured) + dnstap-version ( | none ); // optional (only available if configured) dual-stack-servers [ port ] { ( [ port ] | [ port ] | [ port ] ); ... }; dump-file ; edns-udp-size ; @@ -145,19 +145,19 @@ options { flush-zones-on-shutdown ; forward ( first | only ); forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; - fstrm-set-buffer-hint ; // not configured - fstrm-set-flush-timeout ; // not configured - fstrm-set-input-queue-size ; // not configured - fstrm-set-output-notify-threshold ; // not configured - fstrm-set-output-queue-model ( mpsc | spsc ); // not configured - fstrm-set-output-queue-size ; // not configured - fstrm-set-reopen-interval ; // not configured + fstrm-set-buffer-hint ; // optional (only available if configured) + fstrm-set-flush-timeout ; // optional (only available if configured) + fstrm-set-input-queue-size ; // optional (only available if configured) + fstrm-set-output-notify-threshold ; // optional (only available if configured) + fstrm-set-output-queue-model ( mpsc | spsc ); // optional (only available if configured) + fstrm-set-output-queue-size ; // optional (only available if configured) + fstrm-set-reopen-interval ; // optional (only available if configured) geoip-directory ( | none ); hostname ( | none ); - http-listener-clients ; - http-port ; - http-streams-per-connection ; - https-port ; + http-listener-clients ; // optional (only available if configured) + http-port ; // optional (only available if configured) + http-streams-per-connection ; // optional (only available if configured) + https-port ; // optional (only available if configured) interface-interval ; ipv4only-contact ; ipv4only-enable ; @@ -168,7 +168,7 @@ options { lame-ttl ; listen-on [ port ] [ proxy ] [ tls ] [ http ] { ; ... }; // may occur multiple times listen-on-v6 [ port ] [ proxy ] [ tls ] [ http ] { ; ... }; // may occur multiple times - lmdb-mapsize ; + lmdb-mapsize ; // optional (only available if configured) managed-keys-directory ; masterfile-format ( raw | text ); masterfile-style ( full | relative ); @@ -357,7 +357,7 @@ server { statistics-channels { inet ( | | * ) [ port ( | * ) ] [ allow { ; ... } ]; // may occur multiple times -}; // may occur multiple times +}; // optional (only available if configured), may occur multiple times tls { ca-file ; @@ -435,7 +435,7 @@ view [ ] { dnssec-secure-to-insecure ; // obsolete dnssec-update-mode ( maintain | no-resign ); // obsolete dnssec-validation ( yes | no | auto ); - dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // not configured + dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // optional (only available if configured) dual-stack-servers [ port ] { ( [ port ] | [ port ] | [ port ] ); ... }; dyndb { }; // may occur multiple times edns-udp-size ; @@ -457,7 +457,7 @@ view [ ] { }; // may occur multiple times key-directory ; lame-ttl ; - lmdb-mapsize ; + lmdb-mapsize ; // optional (only available if configured) managed-keys { ( static-key | initial-key | static-ds | initial-ds ) ; ... }; // may occur multiple times, deprecated masterfile-format ( raw | text ); masterfile-style ( full | relative ); diff --git a/lib/isccfg/check.c b/lib/isccfg/check.c index 4609734779..6762fbca86 100644 --- a/lib/isccfg/check.c +++ b/lib/isccfg/check.c @@ -3102,7 +3102,7 @@ check_zoneconf(const cfg_obj_t *zconfig, const cfg_obj_t *voptions, const char *znamestr; const char *typestr = NULL; const char *target = NULL; - unsigned int ztype; + int ztype; const cfg_obj_t *zoptions, *goptions = NULL; const cfg_obj_t *obj = NULL, *kasp = NULL; const cfg_obj_t *inviewobj = NULL; diff --git a/lib/isccfg/include/isccfg/grammar.h b/lib/isccfg/include/isccfg/grammar.h index 6cd39d00c5..28dfa3e136 100644 --- a/lib/isccfg/include/isccfg/grammar.h +++ b/lib/isccfg/include/isccfg/grammar.h @@ -31,48 +31,62 @@ * Definitions shared between the configuration parser * and the grammars; not visible to users of the parser. */ +enum { + /*% A configuration option that was not configured at compile time. */ + CFG_CLAUSEFLAG_NOTCONFIGURED = 1 << 0, -/*% Clause may occur multiple times (e.g., "zone") */ -#define CFG_CLAUSEFLAG_MULTI 0x00000001 -/*% Clause is obsolete (logs a warning, but is not a fatal error) */ -#define CFG_CLAUSEFLAG_OBSOLETE 0x00000002 -/* obsolete: #define CFG_CLAUSEFLAG_NOTIMP 0x00000004 */ -/* obsolete: #define CFG_CLAUSEFLAG_NYI 0x00000008 */ -/* obsolete: #define CFG_CLAUSEFLAG_NEWDEFAULT 0x00000010 */ -/*% - * Clause needs to be interpreted during parsing - * by calling a callback function, like the - * "directory" option. - */ -#define CFG_CLAUSEFLAG_CALLBACK 0x00000020 -/*% An option that is only used in testing. */ -#define CFG_CLAUSEFLAG_TESTONLY 0x00000040 -/*% A configuration option that was not configured at compile time. */ -#define CFG_CLAUSEFLAG_NOTCONFIGURED 0x00000080 -/*% An option for an experimental feature. */ -#define CFG_CLAUSEFLAG_EXPERIMENTAL 0x00000100 -/*% An option that should be omited from the documentation */ -#define CFG_CLAUSEFLAG_NODOC 0x00000200 -/*% Clause will be obsolete in a future release (logs a warning) */ -#define CFG_CLAUSEFLAG_DEPRECATED 0x00000400 -/*% Clause has been obsolete so long that it's now a fatal error */ -#define CFG_CLAUSEFLAG_ANCIENT 0x00000800 + /*% + * A configuration option that *is* configured, but could be + * disabled at compile time in some builds. + */ + CFG_CLAUSEFLAG_OPTIONAL = 1 << 1, + + /*% Clause may occur multiple times (e.g., "zone") */ + CFG_CLAUSEFLAG_MULTI = 1 << 2, + + /*% Clause is obsolete (logs a warning, but is not a fatal error) */ + CFG_CLAUSEFLAG_OBSOLETE = 1 << 3, + + /*% + * Clause needs to be interpreted during parsing by calling a + * callback function, like the "directory" option. + */ + CFG_CLAUSEFLAG_CALLBACK = 1 << 4, + + /*% Clause that is only used in testing. */ + CFG_CLAUSEFLAG_TESTONLY = 1 << 5, + + /*% An option for an experimental feature. */ + CFG_CLAUSEFLAG_EXPERIMENTAL = 1 << 6, + + /*% An option that should be omited from the documentation */ + CFG_CLAUSEFLAG_NODOC = 1 << 7, + + /*% Clause will be obsolete in a future release (logs a warning) */ + CFG_CLAUSEFLAG_DEPRECATED = 1 << 8, + + /*% Clause has been obsolete so long that it's now a fatal error */ + CFG_CLAUSEFLAG_ANCIENT = 1 << 9, +}; /*% * Zone types for which a clause is valid: * These share space with CFG_CLAUSEFLAG values, but count - * down from the top. + * down from the most significant bit, instead of up from + * the least. */ -#define CFG_ZONE_PRIMARY 0x80000000 -#define CFG_ZONE_SECONDARY 0x40000000 -#define CFG_ZONE_STUB 0x20000000 -#define CFG_ZONE_HINT 0x10000000 -#define CFG_ZONE_FORWARD 0x08000000 -#define CFG_ZONE_STATICSTUB 0x04000000 -#define CFG_ZONE_REDIRECT 0x02000000 -#define CFG_ZONE_DELEGATION 0x01000000 -#define CFG_ZONE_INVIEW 0x00800000 -#define CFG_ZONE_MIRROR 0x00400000 +enum { + CFG_ZONE_PRIMARY = 1 << 31, + CFG_ZONE_SECONDARY = 1 << 30, + CFG_ZONE_STUB = 1 << 29, + CFG_ZONE_HINT = 1 << 28, + CFG_ZONE_FORWARD = 1 << 27, + CFG_ZONE_STATICSTUB = 1 << 26, + CFG_ZONE_REDIRECT = 1 << 25, + CFG_ZONE_DELEGATION = 1 << 24, + CFG_ZONE_INVIEW = 1 << 23, + CFG_ZONE_MIRROR = 1 << 22, +}; typedef struct cfg_clausedef cfg_clausedef_t; typedef struct cfg_tuplefielddef cfg_tuplefielddef_t; diff --git a/lib/isccfg/namedconf.c b/lib/isccfg/namedconf.c index 02057b2cf7..9c29016c8b 100644 --- a/lib/isccfg/namedconf.c +++ b/lib/isccfg/namedconf.c @@ -159,7 +159,7 @@ static cfg_tuplefielddef_t listenon_tuple_fields[] = { { "proxy", &cfg_type_astring, CFG_CLAUSEFLAG_EXPERIMENTAL }, { "tls", &cfg_type_astring, 0 }, #if HAVE_LIBNGHTTP2 - { "http", &cfg_type_astring, 0 }, + { "http", &cfg_type_astring, CFG_CLAUSEFLAG_OPTIONAL }, #else { "http", &cfg_type_astring, CFG_CLAUSEFLAG_NOTCONFIGURED }, #endif @@ -1156,7 +1156,8 @@ static cfg_clausedef_t namedconf_clauses[] = { { "controls", &cfg_type_controls, CFG_CLAUSEFLAG_MULTI }, { "dnssec-policy", &cfg_type_dnssecpolicy, CFG_CLAUSEFLAG_MULTI }, #if HAVE_LIBNGHTTP2 - { "http", &cfg_type_http_description, CFG_CLAUSEFLAG_MULTI }, + { "http", &cfg_type_http_description, + CFG_CLAUSEFLAG_MULTI | CFG_CLAUSEFLAG_OPTIONAL }, #else { "http", &cfg_type_http_description, CFG_CLAUSEFLAG_MULTI | CFG_CLAUSEFLAG_NOTCONFIGURED }, @@ -1171,7 +1172,7 @@ static cfg_clausedef_t namedconf_clauses[] = { { "primaries", &cfg_type_remoteservers, CFG_CLAUSEFLAG_MULTI }, #if defined(HAVE_LIBXML2) || defined(HAVE_JSON_C) { "statistics-channels", &cfg_type_statschannels, - CFG_CLAUSEFLAG_MULTI }, + CFG_CLAUSEFLAG_MULTI | CFG_CLAUSEFLAG_OPTIONAL }, #else { "statistics-channels", &cfg_type_statschannels, CFG_CLAUSEFLAG_MULTI | CFG_CLAUSEFLAG_NOTCONFIGURED }, @@ -1236,9 +1237,9 @@ static cfg_clausedef_t options_clauses[] = { { "directory", &cfg_type_qstring, CFG_CLAUSEFLAG_CALLBACK }, { "dnsrps-library", &cfg_type_qstring, CFG_CLAUSEFLAG_OBSOLETE }, #ifdef HAVE_DNSTAP - { "dnstap-output", &cfg_type_dnstapoutput, 0 }, - { "dnstap-identity", &cfg_type_serverid, 0 }, - { "dnstap-version", &cfg_type_qstringornone, 0 }, + { "dnstap-output", &cfg_type_dnstapoutput, CFG_CLAUSEFLAG_OPTIONAL }, + { "dnstap-identity", &cfg_type_serverid, CFG_CLAUSEFLAG_OPTIONAL }, + { "dnstap-version", &cfg_type_qstringornone, CFG_CLAUSEFLAG_OPTIONAL }, #else /* ifdef HAVE_DNSTAP */ { "dnstap-output", &cfg_type_dnstapoutput, CFG_CLAUSEFLAG_NOTCONFIGURED }, @@ -1252,13 +1253,19 @@ static cfg_clausedef_t options_clauses[] = { { "files", NULL, CFG_CLAUSEFLAG_ANCIENT }, { "flush-zones-on-shutdown", &cfg_type_boolean, 0 }, #ifdef HAVE_DNSTAP - { "fstrm-set-buffer-hint", &cfg_type_uint32, 0 }, - { "fstrm-set-flush-timeout", &cfg_type_uint32, 0 }, - { "fstrm-set-input-queue-size", &cfg_type_uint32, 0 }, - { "fstrm-set-output-notify-threshold", &cfg_type_uint32, 0 }, - { "fstrm-set-output-queue-model", &cfg_type_fstrm_model, 0 }, - { "fstrm-set-output-queue-size", &cfg_type_uint32, 0 }, - { "fstrm-set-reopen-interval", &cfg_type_duration, 0 }, + { "fstrm-set-buffer-hint", &cfg_type_uint32, CFG_CLAUSEFLAG_OPTIONAL }, + { "fstrm-set-flush-timeout", &cfg_type_uint32, + CFG_CLAUSEFLAG_OPTIONAL }, + { "fstrm-set-input-queue-size", &cfg_type_uint32, + CFG_CLAUSEFLAG_OPTIONAL }, + { "fstrm-set-output-notify-threshold", &cfg_type_uint32, + CFG_CLAUSEFLAG_OPTIONAL }, + { "fstrm-set-output-queue-model", &cfg_type_fstrm_model, + CFG_CLAUSEFLAG_OPTIONAL }, + { "fstrm-set-output-queue-size", &cfg_type_uint32, + CFG_CLAUSEFLAG_OPTIONAL }, + { "fstrm-set-reopen-interval", &cfg_type_duration, + CFG_CLAUSEFLAG_OPTIONAL }, #else /* ifdef HAVE_DNSTAP */ { "fstrm-set-buffer-hint", &cfg_type_uint32, CFG_CLAUSEFLAG_NOTCONFIGURED }, @@ -1305,10 +1312,11 @@ static cfg_clausedef_t options_clauses[] = { { "port", &cfg_type_uint32, 0 }, { "tls-port", &cfg_type_uint32, 0 }, #if HAVE_LIBNGHTTP2 - { "http-port", &cfg_type_uint32, 0 }, - { "http-listener-clients", &cfg_type_uint32, 0 }, - { "http-streams-per-connection", &cfg_type_uint32, 0 }, - { "https-port", &cfg_type_uint32, 0 }, + { "http-port", &cfg_type_uint32, CFG_CLAUSEFLAG_OPTIONAL }, + { "http-listener-clients", &cfg_type_uint32, CFG_CLAUSEFLAG_OPTIONAL }, + { "http-streams-per-connection", &cfg_type_uint32, + CFG_CLAUSEFLAG_OPTIONAL }, + { "https-port", &cfg_type_uint32, CFG_CLAUSEFLAG_OPTIONAL }, #else { "http-port", &cfg_type_uint32, CFG_CLAUSEFLAG_NOTCONFIGURED }, { "http-listener-clients", &cfg_type_uint32, @@ -2066,7 +2074,7 @@ static cfg_clausedef_t view_clauses[] = { CFG_CLAUSEFLAG_MULTI | CFG_CLAUSEFLAG_DEPRECATED }, { "dnssec-validation", &cfg_type_boolorauto, 0 }, #ifdef HAVE_DNSTAP - { "dnstap", &cfg_type_dnstap, 0 }, + { "dnstap", &cfg_type_dnstap, CFG_CLAUSEFLAG_OPTIONAL }, #else /* ifdef HAVE_DNSTAP */ { "dnstap", &cfg_type_dnstap, CFG_CLAUSEFLAG_NOTCONFIGURED }, #endif /* HAVE_DNSTAP */ @@ -2089,7 +2097,7 @@ static cfg_clausedef_t view_clauses[] = { { "ixfr-from-differences", &cfg_type_ixfrdifftype, 0 }, { "lame-ttl", &cfg_type_duration, 0 }, #ifdef HAVE_LMDB - { "lmdb-mapsize", &cfg_type_sizeval, 0 }, + { "lmdb-mapsize", &cfg_type_sizeval, CFG_CLAUSEFLAG_OPTIONAL }, #else /* ifdef HAVE_LMDB */ { "lmdb-mapsize", &cfg_type_sizeval, CFG_CLAUSEFLAG_NOTCONFIGURED }, #endif /* ifdef HAVE_LMDB */ diff --git a/lib/isccfg/parser.c b/lib/isccfg/parser.c index 0b9e2626c8..bef0acdb29 100644 --- a/lib/isccfg/parser.c +++ b/lib/isccfg/parser.c @@ -2589,7 +2589,10 @@ static struct flagtext { const char *text; } flagtexts[] = { { CFG_CLAUSEFLAG_OBSOLETE, "obsolete" }, { CFG_CLAUSEFLAG_TESTONLY, "test only" }, - { CFG_CLAUSEFLAG_NOTCONFIGURED, "not configured" }, + { CFG_CLAUSEFLAG_NOTCONFIGURED, + "optional (only available if configured)" }, + { CFG_CLAUSEFLAG_OPTIONAL, + "optional (only available if configured)" }, { CFG_CLAUSEFLAG_MULTI, "may occur multiple times" }, { CFG_CLAUSEFLAG_EXPERIMENTAL, "experimental" }, { CFG_CLAUSEFLAG_DEPRECATED, "deprecated" },