From aab8905d82e84d7f79451a2aefa248d8a636f21d Mon Sep 17 00:00:00 2001 From: Remi Gacogne Date: Fri, 20 Dec 2024 12:24:35 +0100 Subject: [PATCH] dnsdist: New YAML documentation format --- .../dnsdist-actions-definitions.yml | 1 + .../dnsdist-response-actions-definitions.yml | 3 + .../dnsdist-settings-definitions.yml | 29 + ...nsdist-settings-documentation-generator.py | 196 ++--- .../dnsdist-selectors-definitions.yml | 2 +- pdns/dnsdistdist/docs/reference/index.rst | 5 + .../docs/reference/yaml-actions.rst | 429 ++++++++++ .../docs/reference/yaml-response-actions.rst | 212 +++++ .../docs/reference/yaml-selectors.rst | 459 +++++++++++ .../docs/reference/yaml-settings.rst | 758 ++++++++++++++++++ .../reference/yaml-support-structures.rst | 50 ++ 11 files changed, 2024 insertions(+), 120 deletions(-) create mode 100644 pdns/dnsdistdist/docs/reference/yaml-actions.rst create mode 100644 pdns/dnsdistdist/docs/reference/yaml-response-actions.rst create mode 100644 pdns/dnsdistdist/docs/reference/yaml-selectors.rst create mode 100644 pdns/dnsdistdist/docs/reference/yaml-settings.rst create mode 100644 pdns/dnsdistdist/docs/reference/yaml-support-structures.rst diff --git a/pdns/dnsdistdist/dnsdist-actions-definitions.yml b/pdns/dnsdistdist/dnsdist-actions-definitions.yml index 5c0b4927abac..0265f3b29ba3 100644 --- a/pdns/dnsdistdist/dnsdist-actions-definitions.yml +++ b/pdns/dnsdistdist/dnsdist-actions-definitions.yml @@ -1,5 +1,6 @@ --- - name: "allow" + description: "Let these packets go through." - name: "delay" parameters: - name: "msec" diff --git a/pdns/dnsdistdist/dnsdist-response-actions-definitions.yml b/pdns/dnsdistdist/dnsdist-response-actions-definitions.yml index a66116a2fbf0..d39c845ae870 100644 --- a/pdns/dnsdistdist/dnsdist-response-actions-definitions.yml +++ b/pdns/dnsdistdist/dnsdist-response-actions-definitions.yml @@ -1,12 +1,15 @@ --- - name: "allow" + description: "Let these packets go through." - name: "ClearRecordTypes" + description: "Removes given type(s) records from the response. Beware you can accidentally turn the answer into a NODATA response without a SOA record in the additional section in which case you may want to use NegativeAndSOAAction() to generate an answer, see example below. Subsequent rules are processed after this action." skip-cpp: true skip-rust: true parameters: - name: "types" type: "Vec" default: true + description: "List of types to remove" - name: "delay" parameters: - name: "msec" diff --git a/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-definitions.yml b/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-definitions.yml index 3e4a6a329c98..4cae39264fe4 100644 --- a/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-definitions.yml +++ b/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-definitions.yml @@ -9,98 +9,127 @@ global: - name: "backends" type: "Vec" default: true + description: "List of backends" - name: "binds" type: "Vec" default: true + description: "List of endpoints to accept queries on" - name: "cache-hit-response-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed on a cache hit" - name: "cache-inserted-response-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed after inserting a new response into the cache" - name: "cache-miss-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed after a cache miss" - name: "cache-settings" type: "CacheSettingsConfiguration" default: true + description: "Caching-related settings" - name: "console" type: "ConsoleConfiguration" default: true + description: "Console-related settings" - name: "dynamic-rules" type: "Vec" default: true + description: "List of dynamic rules" - name: "dynamic-rules-settings" type: "DynamicRulesSettingsConfiguration" default: true + description: "Dynamic rules-related settings" - name: "edns-client-subnet" type: "EdnsClientSubnetConfiguration" default: true + description: "EDNS Client Subnet-related settings" - name: "general" type: "GeneralConfiguration" default: true + description: "General settings" - name: "key-value-stores" type: "KeyValueStoresConfiguration" default: true + description: "Key-Value stores" - name: "load-balancing-policies" type: "LoadBalancingPoliciesConfiguration" default: true + description: "Load-balancing policies" - name: "metrics" type: "MetricsConfiguration" default: true + description: "Metrics-related settings" - name: "packet-caches" type: "Vec" default: true + description: "Packet-cache definitions" - name: "pools" type: "Vec" default: true + description: "Pools of backends" - name: "proxy-protocol" type: "ProxyProtocolConfiguration" default: true + description: "Proxy-protocol-related settings" - name: "query-count" type: "QueryCountConfiguration" default: true + description: "Queries counting-related settings" - name: "query-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed when a query is received" - name: "remote-logging" type: "RemoteLoggingConfiguration" default: true + description: "Remote logging-related settings" - name: "response-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed when a response is received" - name: "ring-buffers" type: "RingBuffersConfiguration" default: true + description: "In-memory ring buffer settings" - name: "security-polling" type: "SecurityPollingConfiguration" default: true + description: "Automatic checking of outdated version" - name: "selectors" type: "Vec" default: true skip-serde: true + description: "List of selectors that can be reused in rules" - name: "self-answered-response-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed when a response is generated by DNSdist itself" - name: "snmp" type: "SnmpConfiguration" default: true + description: "SNMP-related settings" - name: "tuning" type: "TuningConfiguration" default: true + description: "Performance-related settings" - name: "webserver" type: "WebserverConfiguration" default: true + description: "Internal web server configuration" - name: "xfr-response-rules" type: "Vec" default: true skip-serde: true + description: "List of rules executed when a XFR response is received" metrics: parameters: diff --git a/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-documentation-generator.py b/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-documentation-generator.py index 5bf93ada222f..4d4240144183 100644 --- a/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-documentation-generator.py +++ b/pdns/dnsdistdist/dnsdist-rust-lib/dnsdist-settings-documentation-generator.py @@ -40,39 +40,18 @@ def get_rust_object_name(name): return object_name -def get_definitions_grouped_by_section(def_file): - sections = {} +def get_objects(def_file): objects = {} - global_objects = {} definitions = get_definitions_from_file(def_file) for definition_name, keys in definitions.items(): - if not 'section' in keys: - object_name = get_rust_object_name(definition_name) + 'Configuration' - objects[object_name] = keys - continue - section_name = keys['section'] - if 'type' in keys and keys['type'] == 'list': - object_name = get_rust_object_name(definition_name) + 'Configuration' - objects[object_name] = keys - if section_name == 'global': - global_objects[definition_name] = rust_type_to_human_str(object_name) - continue - if section_name == 'global': - if 'type' in keys and is_type_native(keys['type']): - sections[definition_name] = keys - print(definition_name) - global_objects[definition_name] = rust_type_to_human_str(keys['type'] if 'type' in keys else get_rust_object_name(definition_name) + 'Configuration') - else: - if not section_name in sections: - sections[section_name] = {} - global_objects[section_name] = rust_type_to_human_str(get_rust_object_name(section_name) + 'Configuration') - sections[section_name][definition_name] = keys - - return (sections, objects, global_objects) - -def rust_type_to_human_str(rust_type): + object_name = get_rust_object_name(definition_name) + 'Configuration' + objects[object_name] = keys + + return objects + +def rust_type_to_human_str(rust_type, entry_type, generate_ref=True): if is_vector_of(rust_type): - return 'Sequence of ' + rust_type_to_human_str(get_vector_sub_type(rust_type)) + return 'Sequence of ' + rust_type_to_human_str(get_vector_sub_type(rust_type), entry_type, generate_ref) if rust_type in ['u8', 'u16', 'u32', 'u64']: return 'Unsigned integer' if rust_type == 'f64': @@ -81,94 +60,44 @@ def rust_type_to_human_str(rust_type): return 'Boolean' if rust_type == 'String': return 'String' - return f':ref:`{rust_type} `' + if generate_ref: + return f':ref:`{rust_type} `' + return f'{rust_type}' -def print_structure(parameters): - # YAML block first - output = '.. code-block:: yaml\n\n' +def print_structure(parameters, entry_type): + output = '' + # list for parameter in parameters: - output += f' {parameter["name"]}: ' + output += f'- **{parameter["name"]}**: ' ptype = parameter['type'] - human_type = rust_type_to_human_str(ptype) + if 'rust-type' in parameter: + ptype = parameter['rust-type'] + human_type = rust_type_to_human_str(ptype, entry_type) output += f'{human_type}' if 'default' in parameter: default = parameter['default'] - if default is True: - output += '\n' - continue - if default == '': - output += ' ("")' - else: - output += f' ({default})' - else: - output += ' (Required)' - output += '\n' - - output += '\n\n' - - # then all parameters, one by one - for parameter in parameters: - ptype = parameter['type'] - if not is_type_native(ptype): - continue - output += f'{parameter["name"]}\n' - output += '^'*len(parameter["name"]) + '\n' - output += '\n' + if default is not True: + if default == '': + output += ' ``("")``' + else: + output += f' ``({default})``' - human_type = rust_type_to_human_str(ptype) - output += f'- {human_type}\n' + if 'description' in parameter: + description = parameter['description'] + output += ' - ' + description - if 'default' in parameter: - default = parameter['default'] - if default is True: - output += '\n' - continue - if default == '': - output += '- Default: ""\n' - else: - output += f'- Default: {default}\n' - else: - output += '- Required\n' output += '\n' - if 'description' in parameters: - description = parameters['description'] - output += description - output += '\n \n' - - return output - -def get_section_type(entries): - pass -def process_section(section_name, entries, prefix=''): - output = '' - - if not 'parameters' in entries and not 'type' in entries: - print(f'{section_name} has NEITHER type nor parameters') - for sub_section, sub_entries in sorted(entries.items()): - output += process_section(sub_section, sub_entries, prefix=section_name) - return output - - if prefix: - output += prefix + '.' - output += f'{section_name}\n' - output += '-' * (len(prefix) + (1 if len(prefix) > 0 else 0) + len(section_name)) + '\n' output += '\n' - if not 'parameters' in entries: - output += rust_type_to_human_str(entries['type']) + '\n' - else: - if 'type' in entries: - if entries['type'] != 'list': - print(f'Section {section_name} has parameters and a type which is not list!', file=sys.stderr) - return '' + return output - output += 'Sequence of objects containing:\n' - output += '\n' +def process_object(object_name, entries, entry_type, is_setting_struct=False): + output = f'.. _yaml-{entry_type}-{object_name}:\n\n' - parameters = entries['parameters'] - output += print_structure(parameters) + output += f'{object_name}\n' + output += '-' * len(object_name) + '\n' output += '\n' if 'description' in entries: @@ -176,11 +105,13 @@ def process_section(section_name, entries, prefix=''): output += description + '\n' output += ' \n' - return output + if 'parameters' in entries: + if not is_setting_struct: + output += "Parameters:\n\n" + parameters = entries['parameters'] + output += print_structure(parameters, entry_type) + output += '\n' -def process_object(object_name, entries): - output = f'.. _setting-yaml-{object_name}:\n\n' - output += process_section(object_name, entries) return output def get_temporary_file_for_generated_content(directory): @@ -205,32 +136,59 @@ def process_settings(): .. code-block:: yaml\n ''' - (sections, objects, global_objects) = get_definitions_grouped_by_section(sys.argv[1]) - for field_name, human_str in sorted(global_objects.items()): - output += f' {field_name}: {human_str}\n' + objects = get_objects('dnsdist-settings-definitions.yml') + for object_name, entries in sorted(objects.items()): + if object_name == 'GlobalConfiguration': + output += process_object(object_name, entries, 'settings', True) + break output += '\n' - for section_name, entries in sorted(sections.items()): - output += process_section(section_name, entries) - for object_name, entries in sorted(objects.items()): - output += process_object(object_name, entries) + if object_name != 'GlobalConfiguration': + output += process_object(object_name, entries, 'settings', True) + + return output + +def process_selectors_or_actions(def_file, entry_type): + title = f'YAML {entry_type} reference' + output = f'''.. raw:: latex + + \\setcounter{{secnumdepth}}{{-1}} + +.. _yaml-settings-{entry_type}: + +{title} +''' + output += len(title)*'=' + '\n\n' + entries = get_definitions_from_file(def_file) + + suffix = get_rust_object_name(entry_type) + for entry in entries: + output += process_object(get_rust_object_name(entry['name'] + suffix), entry, 'settings') return output def main(): - if len(sys.argv) != 2: - print(f'Usage: {sys.argv[0]} ') - sys.exit(1) + generated_fp = get_temporary_file_for_generated_content('../docs/') + output = process_settings() + generated_fp.write(output) + os.rename(generated_fp.name, '../docs/reference/yaml-settings.rst') generated_fp = get_temporary_file_for_generated_content('../docs/') + output = process_selectors_or_actions('../dnsdist-actions-definitions.yml', 'action') + generated_fp.write(output) + os.rename(generated_fp.name, '../docs/reference/yaml-actions.rst') - output = process_settings() -# output += process_selectors() + generated_fp = get_temporary_file_for_generated_content('../docs/') + output = process_selectors_or_actions('../dnsdist-response-actions-definitions.yml', 'responseaction') + generated_fp.write(output) + os.rename(generated_fp.name, '../docs/reference/yaml-response-actions.rst') + generated_fp = get_temporary_file_for_generated_content('../docs/') + output = process_selectors_or_actions('../dnsdist-selectors-definitions.yml', 'selector') generated_fp.write(output) - os.rename(generated_fp.name, '../docs/reference/yaml.rst') + os.rename(generated_fp.name, '../docs/reference/yaml-selectors.rst') if __name__ == '__main__': main() diff --git a/pdns/dnsdistdist/dnsdist-selectors-definitions.yml b/pdns/dnsdistdist/dnsdist-selectors-definitions.yml index b744f3e07448..aee284a17ea3 100644 --- a/pdns/dnsdistdist/dnsdist-selectors-definitions.yml +++ b/pdns/dnsdistdist/dnsdist-selectors-definitions.yml @@ -1,4 +1,5 @@ --- +- name: "all" - name: "And" skip-cpp: true skip-rust: true @@ -7,7 +8,6 @@ - name: "selectors" type: "Vec" default: true -- name: "all" - name: "ByName" skip-cpp: true skip-rust: true diff --git a/pdns/dnsdistdist/docs/reference/index.rst b/pdns/dnsdistdist/docs/reference/index.rst index 4f2938705ad5..94dbdfd4f9d5 100755 --- a/pdns/dnsdistdist/docs/reference/index.rst +++ b/pdns/dnsdistdist/docs/reference/index.rst @@ -31,3 +31,8 @@ These chapters contain extensive information on all functions and object availab svc custommetrics xsk + yaml-settings + yaml-selectors + yaml-actions + yaml-response-actions + yaml-support-structures diff --git a/pdns/dnsdistdist/docs/reference/yaml-actions.rst b/pdns/dnsdistdist/docs/reference/yaml-actions.rst new file mode 100644 index 000000000000..873bae31244d --- /dev/null +++ b/pdns/dnsdistdist/docs/reference/yaml-actions.rst @@ -0,0 +1,429 @@ +.. THIS IS A GENERATED FILE. DO NOT EDIT. See dnsdist-settings-documentation-generator.py + +.. raw:: latex + + \setcounter{secnumdepth}{-1} + +.. _yaml-settings-action: + +YAML action reference +===================== + +.. _yaml-settings-AllowAction: + +AllowAction +----------- + +Let these packets go through. + +.. _yaml-settings-DelayAction: + +DelayAction +----------- + +Parameters: + +- **msec**: Unsigned integer + + +.. _yaml-settings-DnstapLogAction: + +DnstapLogAction +--------------- + +Parameters: + +- **identity**: String +- **logger-name**: String +- **alter-function**: String ``("")`` + + +.. _yaml-settings-DropAction: + +DropAction +---------- + +.. _yaml-settings-SetEDNSOptionAction: + +SetEDNSOptionAction +------------------- + +Parameters: + +- **code**: Unsigned integer +- **data**: String + + +.. _yaml-settings-ERCodeAction: + +ERCodeAction +------------ + +Parameters: + +- **rcode**: Unsigned integer +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-HTTPStatusAction: + +HTTPStatusAction +---------------- + +Parameters: + +- **status**: Unsigned integer +- **body**: String +- **content-type**: String ``("")`` +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-KeyValueStoreLookupAction: + +KeyValueStoreLookupAction +------------------------- + +Parameters: + +- **kvs-name**: String +- **lookup-key-name**: String +- **destination-tag**: String + + +.. _yaml-settings-KeyValueStoreRangeLookupAction: + +KeyValueStoreRangeLookupAction +------------------------------ + +Parameters: + +- **kvs-name**: String +- **lookup-key-name**: String +- **destination-tag**: String + + +.. _yaml-settings-LogAction: + +LogAction +--------- + +Parameters: + +- **file-name**: String ``("")`` +- **binary**: Boolean ``(true)`` +- **append**: Boolean ``(false)`` +- **buffered**: Boolean ``(false)`` +- **verbose-only**: Boolean ``(true)`` +- **include-timestamp**: Boolean ``(false)`` + + +.. _yaml-settings-LuaAction: + +LuaAction +--------- + +Parameters: + +- **function**: String + + +.. _yaml-settings-LuaFFIAction: + +LuaFFIAction +------------ + +Parameters: + +- **function**: String + + +.. _yaml-settings-LuaFFIPerThreadAction: + +LuaFFIPerThreadAction +--------------------- + +Parameters: + +- **code**: String + + +.. _yaml-settings-NegativeAndSOAAction: + +NegativeAndSOAAction +-------------------- + +Parameters: + +- **nxd**: Boolean +- **zone**: String +- **ttl**: Unsigned integer +- **mname**: String +- **rname**: String +- **soa-parameters**: :ref:`SOAParams ` +- **soa-in-authority**: Boolean ``(false)`` +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-NoneAction: + +NoneAction +---------- + +.. _yaml-settings-PoolAction: + +PoolAction +---------- + +Parameters: + +- **pool-name**: String +- **stop-processing**: Boolean ``(true)`` + + +.. _yaml-settings-QPSAction: + +QPSAction +--------- + +Parameters: + +- **limit**: Unsigned integer + + +.. _yaml-settings-QPSPoolAction: + +QPSPoolAction +------------- + +Parameters: + +- **limit**: Unsigned integer +- **pool-name**: String +- **stop-processing**: Boolean ``(true)`` + + +.. _yaml-settings-RCodeAction: + +RCodeAction +----------- + +Parameters: + +- **rcode**: Unsigned integer +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-RemoteLogAction: + +RemoteLogAction +--------------- + +Parameters: + +- **logger-name**: String +- **alter-function**: String ``("")`` +- **server-id**: String ``("")`` +- **ip-encrypt-key**: String ``("")`` +- **export-tags**: Sequence of String +- **metas**: Sequence of :ref:`ProtoBufMetaConfiguration ` + + +.. _yaml-settings-SetAdditionalProxyProtocolValueAction: + +SetAdditionalProxyProtocolValueAction +------------------------------------- + +Parameters: + +- **proxy-type**: Unsigned integer +- **value**: String + + +.. _yaml-settings-SetDisableECSAction: + +SetDisableECSAction +------------------- + +.. _yaml-settings-SetDisableValidationAction: + +SetDisableValidationAction +-------------------------- + +.. _yaml-settings-SetECSAction: + +SetECSAction +------------ + +Parameters: + +- **ipv4**: String +- **ipv6**: String ``("")`` + + +.. _yaml-settings-SetECSOverrideAction: + +SetECSOverrideAction +-------------------- + +Parameters: + +- **override-existing**: Boolean + + +.. _yaml-settings-SetECSPrefixLengthAction: + +SetECSPrefixLengthAction +------------------------ + +Parameters: + +- **ipv4**: Unsigned integer +- **ipv6**: Unsigned integer + + +.. _yaml-settings-SetExtendedDNSErrorAction: + +SetExtendedDNSErrorAction +------------------------- + +Parameters: + +- **info-code**: Unsigned integer +- **extra-text**: String ``("")`` + + +.. _yaml-settings-SetMacAddrAction: + +SetMacAddrAction +---------------- + +Parameters: + +- **code**: Unsigned integer + + +.. _yaml-settings-SetMaxReturnedTTLAction: + +SetMaxReturnedTTLAction +----------------------- + +Parameters: + +- **max**: Unsigned integer + + +.. _yaml-settings-SetNoRecurseAction: + +SetNoRecurseAction +------------------ + +.. _yaml-settings-SetSkipCacheAction: + +SetSkipCacheAction +------------------ + +.. _yaml-settings-SetTagAction: + +SetTagAction +------------ + +Parameters: + +- **tag**: String +- **value**: String + + +.. _yaml-settings-SetTempFailureCacheTTLAction: + +SetTempFailureCacheTTLAction +---------------------------- + +Parameters: + +- **maxTTL**: Unsigned integer + + +.. _yaml-settings-SNMPTrapAction: + +SNMPTrapAction +-------------- + +Parameters: + +- **reason**: String ``("")`` + + +.. _yaml-settings-SpoofAction: + +SpoofAction +----------- + +Parameters: + +- **ips**: Sequence of String +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-SpoofCNAMEAction: + +SpoofCNAMEAction +---------------- + +Parameters: + +- **cname**: String +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-SpoofPacketAction: + +SpoofPacketAction +----------------- + +Parameters: + +- **response**: String +- **len**: Unsigned integer + + +.. _yaml-settings-SpoofRawAction: + +SpoofRawAction +-------------- + +Parameters: + +- **answers**: Sequence of String +- **qtype-for-any**: String ``("")`` +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-SpoofSVCAction: + +SpoofSVCAction +-------------- + +Parameters: + +- **parameters**: Sequence of :ref:`SVCRecordParameters ` +- **vars**: :ref:`ResponseConfig ` + + +.. _yaml-settings-TCAction: + +TCAction +-------- + +.. _yaml-settings-TeeAction: + +TeeAction +--------- + +Parameters: + +- **rca**: String +- **lca**: String ``("")`` +- **addECS**: Boolean ``(false)`` +- **addProxyProtocol**: Boolean ``(false)`` + + diff --git a/pdns/dnsdistdist/docs/reference/yaml-response-actions.rst b/pdns/dnsdistdist/docs/reference/yaml-response-actions.rst new file mode 100644 index 000000000000..5815285b3ee3 --- /dev/null +++ b/pdns/dnsdistdist/docs/reference/yaml-response-actions.rst @@ -0,0 +1,212 @@ +.. THIS IS A GENERATED FILE. DO NOT EDIT. See dnsdist-settings-documentation-generator.py + +.. raw:: latex + + \setcounter{secnumdepth}{-1} + +.. _yaml-settings-responseaction: + +YAML responseaction reference +============================= + +.. _yaml-settings-AllowResponseaction: + +AllowResponseaction +------------------- + +Let these packets go through. + +.. _yaml-settings-ClearRecordTypesResponseaction: + +ClearRecordTypesResponseaction +------------------------------ + +Removes given type(s) records from the response. Beware you can accidentally turn the answer into a NODATA response without a SOA record in the additional section in which case you may want to use NegativeAndSOAAction() to generate an answer, see example below. Subsequent rules are processed after this action. + +Parameters: + +- **types**: Sequence of Unsigned integer - List of types to remove + + +.. _yaml-settings-DelayResponseaction: + +DelayResponseaction +------------------- + +Parameters: + +- **msec**: Unsigned integer + + +.. _yaml-settings-DnstapLogResponseaction: + +DnstapLogResponseaction +----------------------- + +Parameters: + +- **identity**: String +- **logger-name**: String +- **alter-function**: String ``("")`` + + +.. _yaml-settings-DropResponseaction: + +DropResponseaction +------------------ + +.. _yaml-settings-LimitTTLResponseaction: + +LimitTTLResponseaction +---------------------- + +Parameters: + +- **min**: Unsigned integer +- **max**: Unsigned integer +- **types**: Sequence of Unsigned integer + + +.. _yaml-settings-LogResponseaction: + +LogResponseaction +----------------- + +Parameters: + +- **file-name**: String ``("")`` +- **append**: Boolean ``(false)`` +- **buffered**: Boolean ``(false)`` +- **verbose-only**: Boolean ``(true)`` +- **include-timestamp**: Boolean ``(false)`` + + +.. _yaml-settings-LuaResponseaction: + +LuaResponseaction +----------------- + +Parameters: + +- **function**: String + + +.. _yaml-settings-LuaFFIResponseaction: + +LuaFFIResponseaction +-------------------- + +Parameters: + +- **function**: String + + +.. _yaml-settings-LuaFFIPerThreadResponseaction: + +LuaFFIPerThreadResponseaction +----------------------------- + +Parameters: + +- **code**: String + + +.. _yaml-settings-RemoteLogResponseaction: + +RemoteLogResponseaction +----------------------- + +Parameters: + +- **logger-name**: String +- **alter-function**: String ``("")`` +- **server-id**: String ``("")`` +- **ip-encrypt-key**: String ``("")`` +- **include-cname**: Boolean ``(false)`` +- **export-tags**: Sequence of String +- **export-extended-errors-to-meta**: String ``("")`` +- **metas**: Sequence of :ref:`ProtoBufMetaConfiguration ` + + +.. _yaml-settings-SetExtendedDNSErrorResponseaction: + +SetExtendedDNSErrorResponseaction +--------------------------------- + +Parameters: + +- **info-code**: Unsigned integer +- **extra-text**: String ``("")`` + + +.. _yaml-settings-SetMinTTLResponseaction: + +SetMinTTLResponseaction +----------------------- + +Parameters: + +- **min**: Unsigned integer + + +.. _yaml-settings-SetMaxReturnedTTLResponseaction: + +SetMaxReturnedTTLResponseaction +------------------------------- + +Parameters: + +- **max**: Unsigned integer + + +.. _yaml-settings-SetMaxTTLResponseaction: + +SetMaxTTLResponseaction +----------------------- + +Parameters: + +- **max**: Unsigned integer + + +.. _yaml-settings-SetReducedTTLResponseaction: + +SetReducedTTLResponseaction +--------------------------- + +Parameters: + +- **percentage**: Unsigned integer + + +.. _yaml-settings-SetSkipCacheResponseaction: + +SetSkipCacheResponseaction +-------------------------- + +.. _yaml-settings-SetTagResponseaction: + +SetTagResponseaction +-------------------- + +Parameters: + +- **tag**: String +- **value**: String + + +.. _yaml-settings-SNMPTrapResponseaction: + +SNMPTrapResponseaction +---------------------- + +Parameters: + +- **reason**: String ``("")`` + + +.. _yaml-settings-TCResponseaction: + +TCResponseaction +---------------- + diff --git a/pdns/dnsdistdist/docs/reference/yaml-selectors.rst b/pdns/dnsdistdist/docs/reference/yaml-selectors.rst new file mode 100644 index 000000000000..08e62a3a8c60 --- /dev/null +++ b/pdns/dnsdistdist/docs/reference/yaml-selectors.rst @@ -0,0 +1,459 @@ +.. THIS IS A GENERATED FILE. DO NOT EDIT. See dnsdist-settings-documentation-generator.py + +.. raw:: latex + + \setcounter{secnumdepth}{-1} + +.. _yaml-settings-selector: + +YAML selector reference +======================= + +.. _yaml-settings-AllSelector: + +AllSelector +----------- + +.. _yaml-settings-AndSelector: + +AndSelector +----------- + +Parameters: + +- **selectors**: Sequence of :ref:`Selector ` + + +.. _yaml-settings-ByNameSelector: + +ByNameSelector +-------------- + +Parameters: + +- **selector-name**: String + + +.. _yaml-settings-DNSSECSelector: + +DNSSECSelector +-------------- + +.. _yaml-settings-DSTPortSelector: + +DSTPortSelector +--------------- + +Parameters: + +- **port**: Unsigned integer + + +.. _yaml-settings-EDNSOptionSelector: + +EDNSOptionSelector +------------------ + +Parameters: + +- **option-code**: Unsigned integer + + +.. _yaml-settings-EDNSVersionSelector: + +EDNSVersionSelector +------------------- + +Parameters: + +- **version**: Unsigned integer + + +.. _yaml-settings-ERCodeSelector: + +ERCodeSelector +-------------- + +Parameters: + +- **rcode**: Unsigned integer + + +.. _yaml-settings-HTTPHeaderSelector: + +HTTPHeaderSelector +------------------ + +Parameters: + +- **header**: String +- **expression**: String + + +.. _yaml-settings-HTTPPathSelector: + +HTTPPathSelector +---------------- + +Parameters: + +- **path**: String + + +.. _yaml-settings-HTTPPathRegexSelector: + +HTTPPathRegexSelector +--------------------- + +Parameters: + +- **expression**: String + + +.. _yaml-settings-KeyValueStoreLookupSelector: + +KeyValueStoreLookupSelector +--------------------------- + +Parameters: + +- **kvs-name**: String +- **lookup-key-name**: String + + +.. _yaml-settings-KeyValueStoreRangeLookupSelector: + +KeyValueStoreRangeLookupSelector +-------------------------------- + +Parameters: + +- **kvs-name**: String +- **lookup-key-name**: String + + +.. _yaml-settings-LuaSelector: + +LuaSelector +----------- + +Parameters: + +- **function**: String + + +.. _yaml-settings-LuaFFISelector: + +LuaFFISelector +-------------- + +Parameters: + +- **function**: String + + +.. _yaml-settings-LuaFFIPerThreadSelector: + +LuaFFIPerThreadSelector +----------------------- + +Parameters: + +- **code**: String + + +.. _yaml-settings-MaxQPSSelector: + +MaxQPSSelector +-------------- + +Parameters: + +- **qps**: Unsigned integer +- **burst**: Unsigned integer ``(0)`` + + +.. _yaml-settings-MaxQPSIPSelector: + +MaxQPSIPSelector +---------------- + +Parameters: + +- **qps**: Unsigned integer +- **ipv4-mask**: Unsigned integer ``(32)`` +- **ipv6-mask**: Unsigned integer ``(64)`` +- **burst**: Unsigned integer ``(0)`` +- **expiration**: Unsigned integer ``(300)`` +- **cleanup-delay**: Unsigned integer ``(60)`` +- **scan-fraction**: Unsigned integer ``(10)`` +- **shards**: Unsigned integer ``(10)`` + + +.. _yaml-settings-NetmaskGroupSelector: + +NetmaskGroupSelector +-------------------- + +Parameters: + +- **netmask-group-name**: String ``("")`` +- **netmasks**: Sequence of String +- **source**: Boolean ``(true)`` +- **quiet**: Boolean ``(false)`` + + +.. _yaml-settings-NotSelector: + +NotSelector +----------- + +Parameters: + +- **selector**: :ref:`Selector ` + + +.. _yaml-settings-OpcodeSelector: + +OpcodeSelector +-------------- + +Parameters: + +- **code**: Unsigned integer + + +.. _yaml-settings-OrSelector: + +OrSelector +---------- + +Parameters: + +- **selectors**: Sequence of :ref:`Selector ` + + +.. _yaml-settings-PayloadSizeSelector: + +PayloadSizeSelector +------------------- + +Parameters: + +- **comparison**: String +- **size**: Unsigned integer + + +.. _yaml-settings-PoolAvailableSelector: + +PoolAvailableSelector +--------------------- + +Parameters: + +- **pool**: String + + +.. _yaml-settings-PoolOutstandingSelector: + +PoolOutstandingSelector +----------------------- + +Parameters: + +- **pool**: String +- **max-outstanding**: Unsigned integer + + +.. _yaml-settings-ProbaSelector: + +ProbaSelector +------------- + +Parameters: + +- **probability**: Double + + +.. _yaml-settings-ProxyProtocolValueSelector: + +ProxyProtocolValueSelector +-------------------------- + +Parameters: + +- **option-type**: Unsigned integer +- **option-value**: String ``("")`` + + +.. _yaml-settings-QClassSelector: + +QClassSelector +-------------- + +Parameters: + +- **qclass**: String ``("")`` +- **numeric-value**: Unsigned integer ``(0)`` + + +.. _yaml-settings-QNameSelector: + +QNameSelector +------------- + +Parameters: + +- **qname**: String + + +.. _yaml-settings-QNameLabelsCountSelector: + +QNameLabelsCountSelector +------------------------ + +Parameters: + +- **min-labels-count**: Unsigned integer +- **max-labels-count**: Unsigned integer + + +.. _yaml-settings-QNameSetSelector: + +QNameSetSelector +---------------- + +Parameters: + +- **qnames**: Sequence of String + + +.. _yaml-settings-QNameSuffixSelector: + +QNameSuffixSelector +------------------- + +Parameters: + +- **suffixes**: Sequence of String +- **quiet**: Boolean ``(false)`` + + +.. _yaml-settings-QNameWireLengthSelector: + +QNameWireLengthSelector +----------------------- + +Parameters: + +- **min**: Unsigned integer +- **max**: Unsigned integer + + +.. _yaml-settings-QTypeSelector: + +QTypeSelector +------------- + +Parameters: + +- **qtype**: String +- **numeric-value**: Unsigned integer ``(0)`` + + +.. _yaml-settings-RCodeSelector: + +RCodeSelector +------------- + +Parameters: + +- **rcode**: Unsigned integer + + +.. _yaml-settings-RDSelector: + +RDSelector +---------- + +.. _yaml-settings-RE2Selector: + +RE2Selector +----------- + +Parameters: + +- **expression**: String + + +.. _yaml-settings-RecordsCountSelector: + +RecordsCountSelector +-------------------- + +Parameters: + +- **section**: Unsigned integer +- **minimum**: Unsigned integer +- **maximum**: Unsigned integer + + +.. _yaml-settings-RecordsTypeCountSelector: + +RecordsTypeCountSelector +------------------------ + +Parameters: + +- **section**: Unsigned integer +- **record-type**: Unsigned integer +- **minimum**: Unsigned integer +- **maximum**: Unsigned integer + + +.. _yaml-settings-RegexSelector: + +RegexSelector +------------- + +Parameters: + +- **expression**: String + + +.. _yaml-settings-SNISelector: + +SNISelector +----------- + +Parameters: + +- **server-name**: String + + +.. _yaml-settings-TagSelector: + +TagSelector +----------- + +Parameters: + +- **tag**: String +- **value**: String ``("")`` + + +.. _yaml-settings-TCPSelector: + +TCPSelector +----------- + +Parameters: + +- **tcp**: Boolean + + +.. _yaml-settings-TrailingDataSelector: + +TrailingDataSelector +-------------------- + diff --git a/pdns/dnsdistdist/docs/reference/yaml-settings.rst b/pdns/dnsdistdist/docs/reference/yaml-settings.rst new file mode 100644 index 000000000000..7dabce4dc961 --- /dev/null +++ b/pdns/dnsdistdist/docs/reference/yaml-settings.rst @@ -0,0 +1,758 @@ +.. THIS IS A GENERATED FILE. DO NOT EDIT. See dnsdist-settings-documentation-generator.py + +.. raw:: latex + + \setcounter{secnumdepth}{-1} + +YAML configuration reference +============================ + +Since 2.0.0, :program:`dnsdist` supports the YAML configuration format in addition to the existing Lua one. + +If the configuration file passed to :program:`dnsdist` via the ``-C`` command-line switch ends in ``.yml``, it is assumed to be in the new YAML format, and an attempt toload a Lua configuration file with the same name but the ``.lua`` will be done before loading the YAML configuration. If the names ends in ``.lua``, there will also be an attempt to find a file with the same name but ending in ``.yml``. Otherwise the existing Lua configuration format is assumed. + +A YAML configuration file contains several sections, that are described below. + +.. code-block:: yaml + +.. _yaml-settings-GlobalConfiguration: + +GlobalConfiguration +------------------- + +- **acl**: Sequence of String ``(127.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 169.254.0.0/16, 192.168.0.0/16, 172.16.0.0/12, ::1/128, fc00::/7, fe80::/10)`` - CIDR netmasks of the clients allowed to send DNS queries +- **backends**: Sequence of :ref:`BackendConfiguration ` - List of backends +- **binds**: Sequence of :ref:`BindConfiguration ` - List of endpoints to accept queries on +- **cache-hit-response-rules**: Sequence of :ref:`ResponseRuleConfiguration ` - List of rules executed on a cache hit +- **cache-inserted-response-rules**: Sequence of :ref:`ResponseRuleConfiguration ` - List of rules executed after inserting a new response into the cache +- **cache-miss-rules**: Sequence of :ref:`QueryRuleConfiguration ` - List of rules executed after a cache miss +- **cache-settings**: :ref:`CacheSettingsConfiguration ` - Caching-related settings +- **console**: :ref:`ConsoleConfiguration ` - Console-related settings +- **dynamic-rules**: Sequence of :ref:`DynamicRulesConfiguration ` - List of dynamic rules +- **dynamic-rules-settings**: :ref:`DynamicRulesSettingsConfiguration ` - Dynamic rules-related settings +- **edns-client-subnet**: :ref:`EdnsClientSubnetConfiguration ` - EDNS Client Subnet-related settings +- **general**: :ref:`GeneralConfiguration ` - General settings +- **key-value-stores**: :ref:`KeyValueStoresConfiguration ` - Key-Value stores +- **load-balancing-policies**: :ref:`LoadBalancingPoliciesConfiguration ` - Load-balancing policies +- **metrics**: :ref:`MetricsConfiguration ` - Metrics-related settings +- **packet-caches**: Sequence of :ref:`PacketCacheConfiguration ` - Packet-cache definitions +- **pools**: Sequence of :ref:`PoolConfiguration ` - Pools of backends +- **proxy-protocol**: :ref:`ProxyProtocolConfiguration ` - Proxy-protocol-related settings +- **query-count**: :ref:`QueryCountConfiguration ` - Queries counting-related settings +- **query-rules**: Sequence of :ref:`QueryRuleConfiguration ` - List of rules executed when a query is received +- **remote-logging**: :ref:`RemoteLoggingConfiguration ` - Remote logging-related settings +- **response-rules**: Sequence of :ref:`ResponseRuleConfiguration ` - List of rules executed when a response is received +- **ring-buffers**: :ref:`RingBuffersConfiguration ` - In-memory ring buffer settings +- **security-polling**: :ref:`SecurityPollingConfiguration ` - Automatic checking of outdated version +- **selectors**: Sequence of :ref:`Selector ` - List of selectors that can be reused in rules +- **self-answered-response-rules**: Sequence of :ref:`ResponseRuleConfiguration ` - List of rules executed when a response is generated by DNSdist itself +- **snmp**: :ref:`SnmpConfiguration ` - SNMP-related settings +- **tuning**: :ref:`TuningConfiguration ` - Performance-related settings +- **webserver**: :ref:`WebserverConfiguration ` - Internal web server configuration +- **xfr-response-rules**: Sequence of :ref:`ResponseRuleConfiguration ` - List of rules executed when a XFR response is received + + + +.. _yaml-settings-BackendConfiguration: + +BackendConfiguration +-------------------- + +- **address**: String +- **id**: String ``("")`` +- **name**: String ``("")`` +- **protocol**: String +- **tls**: :ref:`OutgoingTlsConfiguration ` +- **doh**: :ref:`OutgoingDohConfiguration ` +- **use-client-subnet**: Boolean ``(false)`` +- **use-proxy-protocol**: Boolean ``(false)`` +- **queries-per-second**: Unsigned integer ``(0)`` +- **order**: Unsigned integer ``(1)`` +- **weight**: Unsigned integer ``(1)`` +- **pools**: Sequence of String +- **retries**: Unsigned integer ``(5)`` +- **tcp**: :ref:`OutgoingTcpConfiguration ` +- **ip-bind-addr-no-port**: Boolean ``(true)`` +- **health-checks**: :ref:`HealthCheckConfiguration ` +- **source**: String ``("")`` +- **sockets**: Unsigned integer ``(1)`` +- **disable-zero-scope**: Boolean ``(false)`` +- **reconnect-on-up**: Boolean ``(false)`` +- **max-in-flight**: Unsigned integer ``(1)`` +- **tcp-only**: Boolean ``(false)`` +- **auto-upgrade**: :ref:`OutgoingAutoUpgradeConfiguration ` +- **max-concurrent-tcp-connections**: Unsigned integer ``(0)`` +- **ktls**: Boolean ``(false)`` +- **proxy-protocol-advertise-tls**: Boolean ``(false)`` +- **xsk-sockets**: Sequence of String +- **mac-address**: String ``("")`` +- **cpus**: String ``("")`` + + +.. _yaml-settings-BindConfiguration: + +BindConfiguration +----------------- + +- **listen-address**: String - Address and port to listen to +- **reuseport**: Boolean ``(false)`` +- **protocol**: String ``(Do53)`` +- **threads**: Unsigned integer ``(1)`` +- **interface**: String ``("")`` +- **cpus**: String ``("")`` +- **enable-proxy-protocol**: Boolean ``(false)`` +- **tcp**: :ref:`IncomingTcpConfiguration ` +- **tls**: :ref:`IncomingTlsConfiguration ` +- **doh**: :ref:`IncomingDohConfiguration ` +- **doq**: :ref:`IncomingDoqConfiguration ` +- **quic**: :ref:`IncomingQuicConfiguration ` +- **additional-addresses**: Sequence of String + + +.. _yaml-settings-CDBKVSConfiguration: + +CDBKVSConfiguration +------------------- + +- **name**: String +- **file-name**: String +- **refresh-delay**: Unsigned integer + + +.. _yaml-settings-CacheSettingsConfiguration: + +CacheSettingsConfiguration +-------------------------- + +- **stale-entries-ttl**: Unsigned integer ``(0)`` +- **cleaning-delay**: Unsigned integer ``(60)`` +- **cleaning-percentage**: Unsigned integer ``(100)`` + + +.. _yaml-settings-CarbonConfiguration: + +CarbonConfiguration +------------------- + +- **address**: String - Indicates the IP address where the statistics should be sent +- **name**: String ``("")`` - An optional string specifying the hostname that should be used. If left empty, the system hostname is used +- **interval**: Unsigned integer ``(30)`` - An optional unsigned integer indicating the interval in seconds between exports +- **namespace**: String ``("")`` - An optional string specifying the namespace name that should be used +- **instance**: String ``("")`` - An optional string specifying the instance name that should be used + + +.. _yaml-settings-ConsoleConfiguration: + +ConsoleConfiguration +-------------------- + +- **listen-address**: String ``("")`` - IP address and port to listen on for console connections +- **key**: String ``("")`` - The shared secret used to secure connections between the console client and the server, generated via ``makeKey()`` +- **acl**: Sequence of String ``(127.0.0.1, ::1)`` - List of network masks or IP addresses that are allowed to open a connection to the console server +- **maximum-output-size**: Unsigned integer ``(10000000)`` +- **log-connections**: Boolean ``(true)`` +- **max-concurrent-connections**: Unsigned integer ``(0)`` + + +.. _yaml-settings-CustomLoadBalancingPolicyConfiguration: + +CustomLoadBalancingPolicyConfiguration +-------------------------------------- + +- **name**: String +- **function**: String +- **ffi**: Boolean ``(false)`` +- **per-thread**: Boolean ``(false)`` + + +.. _yaml-settings-DnstapLoggerConfiguration: + +DnstapLoggerConfiguration +------------------------- + +- **name**: String +- **transport**: String +- **address**: String +- **buffer-hint**: Unsigned integer ``(0)`` +- **flush-timeout**: Unsigned integer ``(0)`` +- **input-queue-size**: Unsigned integer ``(0)`` +- **output-queue-size**: Unsigned integer ``(0)`` +- **queue-notify-threshold**: Unsigned integer ``(0)`` +- **reopen-interval**: Unsigned integer ``(0)`` + + +.. _yaml-settings-DohTuningConfiguration: + +DohTuningConfiguration +---------------------- + +- **outgoing-worker-threads**: Unsigned integer ``(10)`` +- **outgoing-max-idle-time**: Unsigned integer ``(300)`` +- **outgoing-cleanup-interval**: Unsigned integer ``(60)`` +- **outgoing-max-idle-connection-per-backend**: Unsigned integer ``(10)`` + + +.. _yaml-settings-DynamicRuleConfiguration: + +DynamicRuleConfiguration +------------------------ + +- **type**: String +- **seconds**: Unsigned integer +- **action-duration**: Unsigned integer +- **comment**: String +- **rate**: Unsigned integer ``(0)`` +- **ratio**: Double ``(0.0)`` +- **action**: String ``(drop)`` +- **warning-rate**: Unsigned integer ``(0)`` +- **warning-ratio**: Double ``(0.0)`` +- **tag-name**: String ``("")`` +- **tag-value**: String ``(0)`` +- **visitor-function**: String ``("")`` +- **rcode**: String ``("")`` +- **qtype**: String ``("")`` +- **minimum-number-of-responses**: Unsigned integer ``(0)`` +- **minimum-global-cache-hit-ratio**: Double ``(0.0)`` + + +.. _yaml-settings-DynamicRulesConfiguration: + +DynamicRulesConfiguration +------------------------- + +- **name**: String +- **mask-ipv4**: Unsigned integer ``(32)`` +- **mask-ipv6**: Unsigned integer ``(64)`` +- **mask-port**: Unsigned integer ``(0)`` +- **exclude-ranges**: Sequence of String +- **include-ranges**: Sequence of String +- **exclude-domains**: Sequence of String +- **rules**: Sequence of :ref:`DynamicRuleConfiguration ` + + +.. _yaml-settings-DynamicRulesSettingsConfiguration: + +DynamicRulesSettingsConfiguration +--------------------------------- + +- **purge-interval**: Unsigned integer ``(60)`` +- **default-action**: String ``(Drop)`` + + +.. _yaml-settings-EdnsClientSubnetConfiguration: + +EdnsClientSubnetConfiguration +----------------------------- + +- **override-existing**: Boolean ``(false)`` - When `useClientSubnet` in `newServer()` is set and dnsdist adds an EDNS Client Subnet Client option to the query, override an existing option already present in the query, if any. Please see Passing the source address to the backend for more information. Note that it’s not recommended to enable setECSOverride in front of an authoritative server responding with EDNS Client Subnet information as mismatching data (ECS scopes) can confuse clients and lead to SERVFAIL responses on downstream nameservers +- **source-prefix-v4**: Unsigned integer ``(32)`` - When `useClientSubnet` in `newServer()` is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestor's IPv4 address to `prefix` bits +- **source-prefix-v6**: Unsigned integer ``(56)`` - When `useClientSubnet` in `newServer()` is set and dnsdist adds an EDNS Client Subnet Client option to the query, truncate the requestor's IPv6 address to `prefix` bits + + +.. _yaml-settings-GeneralConfiguration: + +GeneralConfiguration +-------------------- + +- **edns-udp-payload-size-self-generated-answers**: Unsigned integer ``(1232)`` +- **add-edns-to-self-generated-answers**: Boolean ``(true)`` +- **truncate-tc-answers**: Boolean ``(false)`` +- **fixup-case**: Boolean ``(false)`` +- **verbose**: Boolean ``(false)`` +- **verbose-health-checks**: Boolean ``(false)`` +- **allow-empty-responses**: Boolean ``(false)`` +- **drop-empty-queries**: Boolean ``(false)`` +- **capabilities-to-retain**: Sequence of String + + +.. _yaml-settings-HealthCheckConfiguration: + +HealthCheckConfiguration +------------------------ + +- **mode**: String ``(auto)`` +- **qname**: String ``("")`` +- **qclass**: String ``(IN)`` +- **qtype**: String ``(A)`` +- **function**: String ``("")`` +- **timeout**: Unsigned integer ``(1000)`` +- **set-cd**: Boolean ``(false)`` +- **max-failures**: Unsigned integer ``(1)`` +- **rise**: Unsigned integer ``(1)`` +- **interval**: Unsigned integer ``(1)`` +- **must-resolve**: Boolean ``(false)`` +- **use-tcp**: Boolean ``(false)`` +- **lazy**: :ref:`LazyHealthCheckConfiguration ` + + +.. _yaml-settings-HttpCustomResponseHeaderConfiguration: + +HttpCustomResponseHeaderConfiguration +------------------------------------- + +- **key**: String +- **value**: String + + +.. _yaml-settings-HttpResponsesMapConfiguration: + +HttpResponsesMapConfiguration +----------------------------- + +- **expression**: String +- **status**: Unsigned integer +- **content**: String +- **headers**: Sequence of :ref:`HttpCustomResponseHeaderConfiguration ` + + +.. _yaml-settings-IncomingDohConfiguration: + +IncomingDohConfiguration +------------------------ + +- **provider**: String ``(nghttp2)`` +- **paths**: Sequence of String ``(/dns-query)`` +- **idle-timeout**: Unsigned integer ``(30)`` +- **server-tokens**: String ``(h2o/dnsdist)`` +- **send-cache-control-headers**: Boolean ``(true)`` +- **keep-incoming-headers**: Boolean ``(false)`` +- **trust-forwarded-for-header**: Boolean ``(false)`` +- **early-acl-drop**: Boolean ``(true)`` +- **exact-path-matching**: Boolean ``(true)`` +- **internal-pipe-buffer-size**: Unsigned integer ``(1048576)`` +- **custom-response-headers**: Sequence of :ref:`HttpCustomResponseHeaderConfiguration ` +- **responses-map**: Sequence of :ref:`HttpResponsesMapConfiguration ` + + +.. _yaml-settings-IncomingDoqConfiguration: + +IncomingDoqConfiguration +------------------------ + +- **max_concurrent_queries_per_connection**: Unsigned integer ``(65535)`` + + +.. _yaml-settings-IncomingQuicConfiguration: + +IncomingQuicConfiguration +------------------------- + +- **idle-timeout**: Unsigned integer ``(5)`` +- **congestion-control-algorithm**: String ``(reno)`` +- **internal-pipe-buffer-size**: Unsigned integer ``(1048576)`` + + +.. _yaml-settings-IncomingTcpConfiguration: + +IncomingTcpConfiguration +------------------------ + +- **max-in-flight-queries**: Unsigned integer ``(0)`` +- **listen-queue-size**: Unsigned integer ``(0)`` +- **fast-open-queue-size**: Unsigned integer ``(0)`` +- **max-concurrent-connections**: Unsigned integer ``(0)`` + + +.. _yaml-settings-IncomingTlsCertificateKeyPairConfiguration: + +IncomingTlsCertificateKeyPairConfiguration +------------------------------------------ + +- **certificate**: String +- **key**: String ``("")`` +- **password**: String ``("")`` + + +.. _yaml-settings-IncomingTlsConfiguration: + +IncomingTlsConfiguration +------------------------ + +- **provider**: String ``(OpenSSL)`` +- **certificates**: Sequence of :ref:`IncomingTlsCertificateKeyPairConfiguration ` +- **ignore-errors**: Boolean ``(false)`` +- **ciphers**: String ``("")`` +- **ciphers-tls-13**: String ``("")`` +- **minimum-version**: String ``(tls1.0)`` +- **ticket-key-file**: String ``("")`` +- **tickets-keys-rotation-delay**: Unsigned integer ``(43200)`` +- **number-of-tickets-keys**: Unsigned integer ``(5)`` +- **prefer-server-ciphers**: Boolean ``(true)`` +- **session-timeout**: Unsigned integer ``(0)`` +- **session-tickets**: Boolean ``(true)`` +- **number-of-stored-sessions**: Unsigned integer ``(20480)`` +- **ocsp-response-files**: Sequence of String +- **key-log-file**: String ``("")`` +- **release-buffers**: Boolean ``(true)`` +- **enable-renegotiation**: Boolean ``(false)`` +- **async-mode**: Boolean ``(false)`` +- **ktls**: Boolean ``(false)`` +- **read-ahead**: Boolean ``(true)`` +- **proxy-protocol-outside-tls**: Boolean ``(false)`` +- **ignore-configuration-errors**: Boolean ``(false)`` + + +.. _yaml-settings-KVSLookupKeyQNameConfiguration: + +KVSLookupKeyQNameConfiguration +------------------------------ + +- **name**: String +- **wire-format**: Boolean ``(true)`` + + +.. _yaml-settings-KVSLookupKeySourceIPConfiguration: + +KVSLookupKeySourceIPConfiguration +--------------------------------- + +- **name**: String +- **v4-mask**: Unsigned integer ``(32)`` +- **v6-mask**: Unsigned integer ``(128)`` +- **include-port**: Boolean ``(false)`` + + +.. _yaml-settings-KVSLookupKeySuffixConfiguration: + +KVSLookupKeySuffixConfiguration +------------------------------- + +- **name**: String +- **minimum-labels**: Unsigned integer ``(0)`` +- **wire-format**: Boolean ``(true)`` + + +.. _yaml-settings-KVSLookupKeyTagConfiguration: + +KVSLookupKeyTagConfiguration +---------------------------- + +- **name**: String +- **tag**: String + + +.. _yaml-settings-KVSLookupKeysConfiguration: + +KVSLookupKeysConfiguration +-------------------------- + +- **source-ip-keys**: Sequence of :ref:`KVSLookupKeySourceIPConfiguration ` +- **qname-keys**: Sequence of :ref:`KVSLookupKeyQNameConfiguration ` +- **suffix-keys**: Sequence of :ref:`KVSLookupKeySuffixConfiguration ` +- **tag-keys**: Sequence of :ref:`KVSLookupKeyTagConfiguration ` + + +.. _yaml-settings-KeyValueStoresConfiguration: + +KeyValueStoresConfiguration +--------------------------- + +- **lmdb**: Sequence of :ref:`LMDBKVSConfiguration ` +- **cdb**: Sequence of :ref:`CDBKVSConfiguration ` +- **lookup-keys**: :ref:`KVSLookupKeysConfiguration ` + + +.. _yaml-settings-LMDBKVSConfiguration: + +LMDBKVSConfiguration +-------------------- + +- **name**: String +- **file-name**: String +- **database-name**: String +- **no-lock**: Boolean ``(false)`` + + +.. _yaml-settings-LazyHealthCheckConfiguration: + +LazyHealthCheckConfiguration +---------------------------- + +- **interval**: Unsigned integer ``(30)`` +- **min-sample-count**: Unsigned integer ``(1)`` +- **mode**: String ``(TimeoutOrServFail)`` +- **sample-size**: Unsigned integer ``(100)`` +- **threshold**: Unsigned integer ``(20)`` +- **use-exponential-back-off**: Boolean ``(false)`` +- **max-back-off**: Unsigned integer ``(3600)`` + + +.. _yaml-settings-LoadBalancingPoliciesConfiguration: + +LoadBalancingPoliciesConfiguration +---------------------------------- + +- **servfail-on-no-server**: Boolean ``(false)`` +- **round-robin-servfail-on-no-server**: Boolean ``(false)`` +- **weighted-balancing-factor**: Double ``(0.0)`` +- **consistent-hashing-balancing-factor**: Double ``(0.0)`` +- **custom-policies**: Sequence of :ref:`CustomLoadBalancingPolicyConfiguration ` +- **hash-perturbation**: Unsigned integer ``(0)`` + + +.. _yaml-settings-MetricsConfiguration: + +MetricsConfiguration +-------------------- + +- **carbon**: Sequence of :ref:`CarbonConfiguration ` + + +.. _yaml-settings-OutgoingAutoUpgradeConfiguration: + +OutgoingAutoUpgradeConfiguration +-------------------------------- + +- **enabled**: Boolean ``(false)`` +- **interval**: Unsigned integer ``(3600)`` +- **keep**: Boolean ``(false)`` +- **pool**: String ``("")`` +- **doh-key**: Unsigned integer ``(7)`` +- **use-lazy-health-check**: Boolean ``(false)`` + + +.. _yaml-settings-OutgoingDohConfiguration: + +OutgoingDohConfiguration +------------------------ + +- **path**: String ``(/dns-query)`` +- **add-x-forwarded-headers**: Boolean ``(false)`` + + +.. _yaml-settings-OutgoingTcpConfiguration: + +OutgoingTcpConfiguration +------------------------ + +- **connect-timeout**: Unsigned integer ``(5)`` +- **send-timeout**: Unsigned integer ``(30)`` +- **receive-timeout**: Unsigned integer ``(30)`` +- **fast-open**: Boolean ``(false)`` + + +.. _yaml-settings-OutgoingTlsConfiguration: + +OutgoingTlsConfiguration +------------------------ + +- **provider**: String ``(OpenSSL)`` +- **subject-name**: String ``("")`` +- **subject-address**: String ``("")`` +- **validate-certificate**: Boolean ``(true)`` +- **ca-store**: String ``("")`` +- **ciphers**: String ``("")`` +- **ciphers-tls-13**: String ``("")`` +- **key-log-file**: String ``("")`` +- **release-buffers**: Boolean ``(true)`` +- **enable-renegotiation**: Boolean ``(false)`` +- **ktls**: Boolean ``(false)`` + + +.. _yaml-settings-PacketCacheConfiguration: + +PacketCacheConfiguration +------------------------ + +- **name**: String +- **size**: Unsigned integer +- **deferrable-insert-lock**: Boolean ``(true)`` +- **dont-age**: Boolean ``(false)`` +- **keep-stale-data**: Boolean ``(false)`` +- **max-negative-ttl**: Unsigned integer ``(3600)`` +- **max-ttl**: Unsigned integer ``(86400)`` +- **min-ttl**: Unsigned integer ``(0)`` +- **shards**: Unsigned integer ``(20)`` +- **parse-ecs**: Boolean ``(false)`` +- **stale-ttl**: Unsigned integer ``(60)`` +- **temporary-failure-ttl**: Unsigned integer ``(60)`` +- **cookie-hashing**: Boolean ``(false)`` +- **maximum-entry-size**: Unsigned integer ``(0)`` +- **options-to-skip**: Sequence of String + + +.. _yaml-settings-PoolConfiguration: + +PoolConfiguration +----------------- + +- **name**: String +- **packet-cache**: String +- **policy**: String ``(least-outstanding)`` + + +.. _yaml-settings-ProtoBufMetaConfiguration: + +ProtoBufMetaConfiguration +------------------------- + +- **key**: String +- **value**: String + + +.. _yaml-settings-ProtobufLoggerConfiguration: + +ProtobufLoggerConfiguration +--------------------------- + +- **name**: String +- **address**: String - An IP:PORT combination where the logger is listening +- **timeout**: Unsigned integer ``(2)`` - TCP connect timeout in seconds +- **max-queued-entries**: Unsigned integer ``(100)`` - Queue this many messages before dropping new ones (e.g. when the remote listener closes the connection) +- **reconnect-wait-time**: Unsigned integer ``(1)`` - Time in seconds between reconnection attempts + + +.. _yaml-settings-ProxyProtocolConfiguration: + +ProxyProtocolConfiguration +-------------------------- + +- **acl**: Sequence of String ``("")`` +- **maximum-payload-size**: Unsigned integer ``(512)`` +- **apply-acl-to-proxied-clients**: Boolean ``(false)`` + + +.. _yaml-settings-QueryCountConfiguration: + +QueryCountConfiguration +----------------------- + +- **enabled**: Boolean ``(false)`` +- **filter**: String ``("")`` + + +.. _yaml-settings-QueryRuleConfiguration: + +QueryRuleConfiguration +---------------------- + +- **name**: String +- **uuid**: String +- **selector**: :ref:`Selector ` +- **action**: :ref:`Action ` + + +.. _yaml-settings-RemoteLoggingConfiguration: + +RemoteLoggingConfiguration +-------------------------- + +- **protobuf-loggers**: Sequence of :ref:`ProtobufLoggerConfiguration ` +- **dnstap-loggers**: Sequence of :ref:`DnstapLoggerConfiguration ` + + +.. _yaml-settings-ResponseRuleConfiguration: + +ResponseRuleConfiguration +------------------------- + +- **name**: String +- **uuid**: String +- **selector**: :ref:`Selector ` +- **action**: :ref:`ResponseAction ` + + +.. _yaml-settings-RingBuffersConfiguration: + +RingBuffersConfiguration +------------------------ + +- **size**: Unsigned integer ``(10000)`` - The maximum amount of queries to keep in the ringbuffer +- **shards**: Unsigned integer ``(10)`` - The number of shards to use to limit lock contention +- **lock-retries**: Unsigned integer ``(5)`` - Set the number of shards to attempt to lock without blocking before giving up and simply blocking while waiting for the next shard to be available. Default to 5 if there is more than one shard, 0 otherwise +- **record-queries**: Boolean ``(true)`` - Whether to record queries in the ring buffers +- **record-responses**: Boolean ``(true)`` - Whether to record responses in the ring buffers + + +.. _yaml-settings-SecurityPollingConfiguration: + +SecurityPollingConfiguration +---------------------------- + +- **polling-interval**: Unsigned integer ``(3600)`` +- **suffix**: String ``(secpoll.powerdns.com.)`` + + +.. _yaml-settings-SnmpConfiguration: + +SnmpConfiguration +----------------- + +- **enabled**: Boolean ``(false)`` +- **traps-enabled**: Boolean ``(false)`` +- **daemon-socket**: String ``("")`` + + +.. _yaml-settings-TcpTuningConfiguration: + +TcpTuningConfiguration +---------------------- + +- **worker-threads**: Unsigned integer ``(10)`` +- **receive-timeout**: Unsigned integer ``(2)`` +- **send-timeout**: Unsigned integer ``(2)`` +- **max-queries-per-connection**: Unsigned integer ``(0)`` +- **max-connection-duration**: Unsigned integer ``(0)`` +- **max-queued-connections**: Unsigned integer ``(10000)`` +- **internal-pipe-buffer-size**: Unsigned integer ``(1048576)`` +- **outgoing-max-idle-time**: Unsigned integer ``(300)`` +- **outgoing-cleanup-interval**: Unsigned integer ``(60)`` +- **outgoing-max-idle-connection-per-backend**: Unsigned integer ``(10)`` +- **max-connections-per-client**: Unsigned integer ``(0)`` +- **fast-open-key**: String ``("")`` + + +.. _yaml-settings-TlsTuningConfiguration: + +TlsTuningConfiguration +---------------------- + +- **outgoing-tickets-cache-cleanup-delay**: Unsigned integer ``(60)`` +- **outgoing-tickets-cache-validity**: Unsigned integer ``(600)`` +- **max-outgoing-tickets-per-backend**: Unsigned integer ``(20)`` + + +.. _yaml-settings-TuningConfiguration: + +TuningConfiguration +------------------- + +- **doh**: :ref:`DohTuningConfiguration ` +- **tcp**: :ref:`TcpTuningConfiguration ` +- **tls**: :ref:`TlsTuningConfiguration ` +- **udp**: :ref:`UdpTuningConfiguration ` + + +.. _yaml-settings-UdpTuningConfiguration: + +UdpTuningConfiguration +---------------------- + +- **messages-per-round**: Unsigned integer ``(1)`` +- **send-buffer-size**: Unsigned integer ``(0)`` +- **receive-buffer-size**: Unsigned integer ``(0)`` +- **max-outstanding-per-backend**: Unsigned integer ``(65535)`` +- **timeout**: Unsigned integer ``(2)`` +- **randomize-outgoing-sockets-to-backend**: Boolean ``(false)`` +- **randomize-ids-to-backend**: Boolean ``(false)`` + + +.. _yaml-settings-WebserverConfiguration: + +WebserverConfiguration +---------------------- + +- **listen-address**: String ``("")`` - IP address and port to listen on +- **password**: String ``("")`` - The password used to access the internal webserver. Since 1.7.0 the password should be hashed and salted via the ``hashPassword()`` command +- **api-key**: String ``("")`` - The API Key (set to an empty string do disable it). Since 1.7.0 the key should be hashed and salted via the ``hashPassword()`` command +- **acl**: Sequence of String ``(127.0.0.1, ::1)`` - List of network masks or IP addresses that are allowed to open a connection to the web server +- **api-requires-authentication**: Boolean ``(true)`` - Whether access to the API (/api endpoints) requires a valid API key +- **stats-require-authentication**: Boolean ``(true)`` - Whether access to the statistics (/metrics and /jsonstat endpoints) requires a valid password or API key +- **dashboard-requires-authentication**: Boolean ``(true)`` - Whether access to the internal dashboard requires a valid password +- **max-concurrent-connections**: Unsigned integer ``(100)`` - The maximum number of concurrent web connections, or 0 which means an unlimited number +- **hash-plaintext-credentials**: Boolean ``(false)`` - Whether passwords and API keys provided in plaintext should be hashed during startup, to prevent the plaintext versions from staying in memory. Doing so increases significantly the cost of verifying credentials +- **custom-headers**: Sequence of :ref:`HttpCustomResponseHeaderConfiguration ` +- **api-configuration-directory**: String ``("")`` +- **api-read-write**: Boolean ``(false)`` + + diff --git a/pdns/dnsdistdist/docs/reference/yaml-support-structures.rst b/pdns/dnsdistdist/docs/reference/yaml-support-structures.rst new file mode 100644 index 000000000000..8bcac41efe13 --- /dev/null +++ b/pdns/dnsdistdist/docs/reference/yaml-support-structures.rst @@ -0,0 +1,50 @@ +.. raw:: latex + + \setcounter{secnumdepth}{-1} + +YAML support structures +======================= + +.. _yaml-settings-ResponseConfig: + +ResponseConfig +-------------- + +- **set-aa**: Boolean +- **set-ad**: Boolean +- **set-ra**: Boolean +- **ttl**: Unsigned integer + +.. _yaml-settings-SOAParams: + +SOAParams +--------- + +- **serial**: Unsigned integer +- **refresh**: Unsigned integer +- **retry**: Unsigned integer +- **expire**: Unsigned integer +- **minimum**: Unsigned integer + +.. _yaml-settings-SVCRecordAdditionalParams: + +SVCRecordAdditionalParams +------------------------- + +- **key**: Unsigned integer +- **value**: String + +.. _yaml-settings-SVCRecordParameters: + +SVCRecordParameters +------------------- + +- **mandatory-params**: Sequence of Unsigned integer +- **alpns**: Sequence of String +- **ipv4-hints**: Sequence of String +- **ipv6-hints**: Sequence of String +- **additional_params**: Sequence of :ref:`SVCRecordAdditionalParams ` +- **target**: String +- **port**: Unsigned integer +- **priority**: Unsigned integer +- **no-default-alpn**: Boolean