From: Aleš Date: Wed, 2 Feb 2022 22:57:08 +0000 (+0100) Subject: datamodel: docstrings annotatinons for server and options schemas X-Git-Tag: v6.0.0a1~44^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d36b7ce33f8f5dd73778e0f1f75b4b324620a1be;p=thirdparty%2Fknot-resolver.git datamodel: docstrings annotatinons for server and options schemas - related to #706 --- diff --git a/manager/knot_resolver_manager/datamodel/config_schema.py b/manager/knot_resolver_manager/datamodel/config_schema.py index 7231cacd0..101e5f31e 100644 --- a/manager/knot_resolver_manager/datamodel/config_schema.py +++ b/manager/knot_resolver_manager/datamodel/config_schema.py @@ -53,27 +53,27 @@ _MAIN_TEMPLATE = _import_lua_template() class KresConfig(SchemaNode): - """ - Knot Resolver declarative configuration. - - --- - server: DNS server control and management configuration. - options: Fine-tuning global parameters of DNS resolver operation. - network: Network connections and protocols. - static_hints: Static hints configuration section. - views: List of views and its configuration. - policy: List of policy rules and its configuration. - rpz: List of Response Policy Zones and its configuration. - stub_zones: List of Stub Zones and its configuration. - forward_zones: List of Forward Zones and its configuration. - cache: DNS resolver cache configuration. - dnssec: DNSSEC disabling/enabling and configuration. - dns64: DNS64 disabling/enabling and configuration. - logging: Logging and debugging configuration. - lua: Custom Lua configuration. - """ - class Raw(SchemaNode): + """ + Knot Resolver declarative configuration. + + --- + server: DNS server control and management configuration. + options: Fine-tuning global parameters of DNS resolver operation. + network: Network connections and protocols configuration. + static_hints: Static hints for forward records (A/AAAA) and reverse records (PTR) + views: List of views and its configuration. + policy: List of policy rules and its configuration. + rpz: List of Response Policy Zones and its configuration. + stub_zones: List of Stub Zones and its configuration. + forward_zones: List of Forward Zones and its configuration. + cache: DNS resolver cache configuration. + dnssec: Disable DNSSEC, enable with defaults or set new configuration. + dns64: Disable DNS64, enable with defaults or set new configuration. + logging: Logging and debugging configuration. + lua: Custom Lua configuration. + """ + server: ServerSchema = ServerSchema() options: OptionsSchema = OptionsSchema() network: NetworkSchema = NetworkSchema() diff --git a/manager/knot_resolver_manager/datamodel/options_schema.py b/manager/knot_resolver_manager/datamodel/options_schema.py index 24d4f9de0..832d3511b 100644 --- a/manager/knot_resolver_manager/datamodel/options_schema.py +++ b/manager/knot_resolver_manager/datamodel/options_schema.py @@ -10,18 +10,44 @@ GlueCheckingEnum = Literal["normal", "strict", "permissive"] class PredictionSchema(SchemaNode): + """ + Helps keep the cache hot by prefetching expiring records and learning usage patterns and repetitive queries. + + --- + window: Sampling window length. + period: Number of windows that can be kept in memory. + """ + window: TimeUnit = TimeUnit("15m") period: int = 24 class OptionsSchema(SchemaNode): class Raw(SchemaNode): + """ + Fine-tuning global parameters of DNS resolver operation. + + --- + glue_checking: Glue records scrictness checking level. + qname_minimisation: Send minimum amount of information in recursive queries to enhance privacy. + query_loopback: Permits queries to loopback addresses. + reorder_rrset: Controls whether resource records within a RRSet are reordered each time it is served from the cache. + query_case_randomization: Randomize Query Character Case. + priming: Initializing DNS resolver cache with Priming Queries (RFC 8109) + rebinding_protection: Protection against DNS Rebinding attack. + refuse_no_rd: Queries without RD (recursion desired) bit set in query are answered with REFUSED. + time_jump_detection: Detection of difference between local system time and expiration time bounds in DNSSEC signatures for '. NS' records. + violators_workarounds: Workarounds for known DNS protocol violators. + serve_stale: Allows using timed-out records in case DNS resolver is unable to contact upstream servers. + prediction: Helps keep the cache hot by prefetching expiring records and learning usage patterns and repetitive queries. + """ + glue_checking: GlueCheckingEnum = "normal" qname_minimisation: bool = True query_loopback: bool = False reorder_rrset: bool = True query_case_randomization: bool = True - query_priming: bool = True + priming: bool = True rebinding_protection: bool = False refuse_no_rd: bool = True time_jump_detection: bool = True @@ -36,7 +62,7 @@ class OptionsSchema(SchemaNode): query_loopback: bool reorder_rrset: bool query_case_randomization: bool - query_priming: bool + priming: bool rebinding_protection: bool refuse_no_rd: bool time_jump_detection: bool diff --git a/manager/knot_resolver_manager/datamodel/server_schema.py b/manager/knot_resolver_manager/datamodel/server_schema.py index 9c55bf87d..ea6a550fb 100644 --- a/manager/knot_resolver_manager/datamodel/server_schema.py +++ b/manager/knot_resolver_manager/datamodel/server_schema.py @@ -41,11 +41,27 @@ BackendEnum = Literal["auto", "systemd", "supervisord"] class WatchDogSchema(SchemaNode): + """ + Configuration of systemd watchdog. + + --- + qname: Name to internaly query for. + qtype: DNS type to internaly query for. + """ + qname: DomainName qtype: DNSRecordTypeEnum class ManagementSchema(SchemaNode): + """ + Configuration of management HTTP API. + + --- + unix_socket: Path to unix domain socket to listen to. + interface: IP address and port number to listen to. + """ + unix_socket: Optional[CheckedPath] = None interface: Optional[IPAddressPort] = None @@ -55,6 +71,17 @@ class ManagementSchema(SchemaNode): class WebmgmtSchema(SchemaNode): + """ + Configuration of legacy web management endpoint. + + --- + unix_socket: Path to unix domain socket to listen to. + interface: IP address or interface name with port number to listen to. + tls: Enable/disable TLS. + cert_file: Path to certificate file. + key_file: Path to certificate key. + """ + unix_socket: Optional[CheckedPath] = None interface: Optional[InterfacePort] = None tls: bool = False @@ -67,23 +94,23 @@ class WebmgmtSchema(SchemaNode): class ServerSchema(SchemaNode): - """ - DNS resolver server control and management configuration. - - --- - hostname: Internal Knot Resolver hostname. Default is hostname of machine. - groupid: Additional identifier in case more managers are running on single machine. - nsid: Name Server Identifier (RFC 5001) which allows DNS clients to request resolver to send back its NSID along with the reply to a DNS request. - workers: The number of running 'Knot Resolver daemon' (kresd) workers. Based on number of CPUs if set to 'auto'. - use_cache_gc: Use cache garbage collector (kres-cache-gc) automatically. - backend: Forces manager to use a specific service manager. Defaults to autodetection. - watchdog: Systemd watchdog configuration. Can only be used with 'systemd' backend. - rundir: Directory where the manager can create files and which will be manager's cwd - management: Management API configuration. - webmgmt: Legacy built-in web management API configuration. - """ - class Raw(SchemaNode): + """ + DNS server control and management configuration. + + --- + hostname: Internal DNS resolver hostname. Default is machine hostname. + groupid: Additional identifier in case more DNS resolvers are running on single machine. + nsid: Name Server Identifier (RFC 5001) which allows DNS clients to request resolver to send back its NSID along with the reply to a DNS request. + workers: The number of running kresd (Knot Resolver daemon) workers. If set to 'auto', it is equal to number of CPUs available. + use_cache_gc: Use (start) kres-cache-gc (cache garbage collector) automatically. + backend: Forces the manager to use a specific service supervisor. + watchdog: Disable systemd watchdog, enable with defaults or set new configuration. Can only be used with 'systemd' backend. + rundir: Directory where the resolver can create files and which will be it's cwd. + management: Configuration of management HTTP API. + webmgmt: Configuration of legacy web management endpoint. + """ + hostname: Optional[str] = None groupid: Optional[str] = None nsid: Optional[str] = None diff --git a/manager/knot_resolver_manager/datamodel/templates/options.lua.j2 b/manager/knot_resolver_manager/datamodel/templates/options.lua.j2 index 2996b63bb..4abe977bb 100644 --- a/manager/knot_resolver_manager/datamodel/templates/options.lua.j2 +++ b/manager/knot_resolver_manager/datamodel/templates/options.lua.j2 @@ -17,7 +17,7 @@ modules.load('serve_stale < cache') {% endif %} -- options.query-priming -{% if cfg.options.query_priming %} +{% if cfg.options.priming %} modules.load('priming') {% else %} modules.unload('priming')