All notable environment, configuration file, and other changes to this project will be documented in this file.
The format is not based on Keep a Changelog, since the project doesn't currently adhere to Semantic Versioning.
-
ratelimitnow defines rate of requests per second for IPv4 and IPv6 addresses separately. So replace this:ratelimit: rps: 30 ipv4_subnet_key_len: 24 ipv6_subnet_key_len: 48
with this:
ratelimit: ipv4: rps: 30 subnet_key_len: 24 ipv6: rps: 300 subnet_key_len: 48
-
The objects within the
filtering_groupshave a new property,block_firefox_canary. So replace this:filtering_groups: - id: default # …
with this:
filtering_groups: - id: default # … block_firefox_canary: true
The recommended default value is
true.
- There is now a new env variable
RESEARCH_METRICSthat controls whether collecting research metrics is enabled or not. Also, the first research metric is added:dns_research_blocked_per_country_total, it counts the number of blocked requests per country. Its default value is0, i.e. research metrics collection is disabled by default.
-
There are two changes in the keys of the
static_contentmap. Firstly, propertiesallow_originandcontent_typeare removed. Secondly, a new property, calledheaders, is added. So replace this:static_content: '/favicon.ico': # … allow_origin: '*' content_type: 'image/x-icon'
with this:
static_content: '/favicon.ico': # … headers: 'Access-Control-Allow-Origin': - '*' 'Content-Type': - 'image/x-icon'
Adjust or add the values, if necessary.
-
The object
filtershas two new properties,rule_list_cache_sizeanduse_rule_list_cache. So replace this:filters: response_ttl: 5m custom_filter_cache_size: 1024 safe_search_cache_size: 1024 refresh_interval: 1h refresh_timeout: 5m
with this:
filters: response_ttl: 5m custom_filter_cache_size: 1024 safe_search_cache_size: 1024 rule_list_cache_size: 10000 refresh_interval: 1h refresh_timeout: 5m use_rule_list_cache: true
Adjust the values, if necessary.
-
The object
filtershas a new property,safe_search_cache_size. So replace this:filters: response_ttl: 5m custom_filter_cache_size: 1024 refresh_interval: 1h refresh_timeout: 5m
with this:
filters: response_ttl: 5m custom_filter_cache_size: 1024 safe_search_cache_size: 1024 refresh_interval: 1h refresh_timeout: 5m
Adjust the values, if necessary.
- DNS Server Check now responds with NODATA message to all non-A neither non-AAAA requests.
- Added support for running a DoH3 server. No configuration changes are required to run it. If there was a DoH server configured, it will start listening for HTTP/3 connections on the same port where it listens for HTTP/2. Make sure that udp/443 is allowed in the iptables configuration on the server.
- The new environment variable
PROFILES_CACHE_PATHhas been added. Its default value is./profilecache.json. Adjust the value, if necessary.
-
The property
serverofupstreamobject has been changed. Now it is a URL optionally starting withtcp://orudp://, and then an address inip:portformat.upstream: server: 'tcp://8.8.8.8:53'
Adjust the value, if necessary.
-
The new optional field
static_content.*.allow_originhas been added:static_content: '/favicon.ico': allow_origin: '*'
-
The new optional object
additional_metrics_infohas been added:additional_metrics_info: test_key: 'test_value'
-
The new object
upstream.healthchecknow contains all healthcheck-related fields, including the new fielddomain_template. Propertyupstream.healthcheck_backoff_timehas been moved toupstream.healthcheck.backoff_duration. So replace this:upstream: server: 127.0.0.1:53 timeout: 2s healthcheck_enabled: true healthcheck_interval: 2s healthcheck_timeout: 1s healthcheck_backoff_time: 30s fallback: - 1.1.1.1:53 - 8.8.8.8:53
with this:
upstream: server: 127.0.0.1:53 timeout: 2s fallback: - 1.1.1.1:53 - 8.8.8.8:53 healthcheck: enabled: true interval: 2s timeout: 1s backoff_duration: 30s domain_template: '${RANDOM}.neverssl.com'
Adjust the new value, if necessary.
-
The property
domainofcheckobject has been changed todomains. So replace this:check: domain: "example.com"
with this:
check: domains: - 'example.com' - 'example.org'
Adjust the news values, if necessary.
-
The object
upstreamhas new properties,healthcheck_enabled,healthcheck_interval,healthcheck_timeout, andhealthcheck_backoff_time. So replace this:upstream: server: 127.0.0.9:53 timeout: 2s fallback: - 1.1.1.1:53 - 8.8.8.8:53
with this:
upstream: server: 127.0.0.9:53 timeout: 2s healthcheck_enabled: true healthcheck_interval: 2s healthcheck_timeout: 1s healthcheck_backoff_time: 30s fallback: - 1.1.1.1:53 - 8.8.8.8:53
Adjust the new values, if necessary.
- The environment variable
SSLKEYLOGFILEhas been renamed toSSL_KEY_LOG_FILE.
-
The properties
subnet_key_ip_4_mask_lenandsubnet_key_ip_6_mask_lenof objectratelimithave been renamed toipv4_subnet_key_lenandipv6_subnet_key_lencorrespondingly. So replace this:ratelimit: # … subnet_key_ip_4_mask_len: 24 subnet_key_ip_6_mask_len: 48
with this:
ratelimit: # … ipv4_subnet_key_len: 24 ipv6_subnet_key_len: 48
-
The
ratelimitobject has two new properties,subnet_key_ip_4_mask_lenandsubnet_key_ip_6_mask_len. So replace this:ratelimit: # …
with this:
ratelimit: # … subnet_key_ip_4_mask_len: 24 subnet_key_ip_6_mask_len: 48
-
The objects within the
filtering_groupshave a new property,block_private_relay.filtering_groups: - id: default # …
with this:
filtering_groups: - id: default # … block_private_relay: false
The recommended default value is
false.
-
The objects within
server_groupsarray had a change in their DDR configuration. There was an opinion that the previous configuration was too limiting and that denormalized configuration is more self-describing. So replace this:server_groups: - # … ddr_names: - 'dns.example.com' # …
with this:
server_groups: - # … ddr: enabled: true device_records: '*.d.dns.example.com': doh_path: '/dns-query{?dns}' https_port: 443 quic_port: 853 tls_port: 853 ipv4_hints: - 127.0.0.1 ipv6_hints: - '::1' public_records: 'dns.example.com': doh_path: '/dns-query{?dns}' https_port: 443 quic_port: 853 tls_port: 853 ipv4_hints: - 127.0.0.1 ipv6_hints: - '::1' # …
Adjust the values, if necessary. Make sure to synchronize and keep in sync the addresses and ports with the values of the server groups' servers.
-
The objects within
server_groupsarray have a new propertyddr_names:server_groups: - # … ddr_names: - 'dns.example.com' # …
It is empty by default. These values will be used for constructing a response for Discovery of Designated Resolvers. Empty value leads to a NODATA response. Adjust the new value, if necessary.
-
The property
tlsof objects within theserver_groups.*.servers.*array has been moved to theserver_groupobject becoming common for the whole group. Any group having at least a single server of DoH/DoT/DoQ protocols will require thetlsproperty specified. Any group having no encrypted resolvers will require thetlsproperty absence. So replace this:server_groups: - # … servers: - name: default_dot protocol: tls tls: # … # …
with this:
server_groups: - tls: # … # … servers: - name: default_dot protocol: tls # …
Adjust the new value, if necessary.
-
The object
upstreamhas a new property,timeout. So replace this:upstream: server: 127.0.0.9:53 fallback: - 1.1.1.1:53 - 8.8.8.8:53
with this:
upstream: server: 127.0.0.9:53 timeout: 2s fallback: - 1.1.1.1:53 - 8.8.8.8:53
Adjust the new value, if necessary.
-
The new object
connectivity_checkhas been added:connectivity_check: probe_ipv4: '8.8.8.8:53' probe_ipv6: '[2001:4860:4860::8888]:53'
-
The object
filtershas a new property,refresh_timeout. So replace this:filters: response_ttl: 5m custom_filter_cache_size: 1024 refresh_interval: 1h
with this:
filters: response_ttl: 5m custom_filter_cache_size: 1024 refresh_interval: 1h refresh_timeout: 5m
Adjust the values, if necessary.
-
The object
cachehas two new properties,typeandecs_size. So replace this:cache: size: 10000
with this:
cache: type: "simple" size: 10000 ecs_size: 10000
Adjust the values, if necessary.
-
Prometheus metric
dns_tls_handshake_totalhas been updated withserver_namelabel. This label represents "Server Name Indication" identifiers, grouped by endpoint identifier and known server names. All unknown server names are grouped inotherlabel:# TYPE dns_tls_handshake_total counter dns_tls_handshake_total{cipher_suite="TLS_AES_128_GCM_SHA256",did_resume="0",negotiated_proto="",proto="tls",server_name="default_dot: other",tls_version="tls1.3"} 4
- The special "disallow-all" response is served on
/robots.txtrequests towebmodule.
-
The property
cache_sizeof objectgeoiphas been renamed toip_cache_size. Also, a new property namedhost_cache_sizehas been added. So replace this:geoip: cache_size: 100000 refresh_interval: 1h
with this:
geoip: host_cache_size: 100000 ip_cache_size: 100000 refresh_interval: 1h
Adjust the new value, if necessary.
-
The object
backendhas a new property,bill_stat_interval. So replace this:backend: timeout: 10s refresh_interval: 15s full_refresh_interval: 24h
with this:
backend: timeout: 10s refresh_interval: 15s full_refresh_interval: 24h bill_stat_interval: 15s
Adjust the value, if necessary.
-
The new required environment variables
GENERAL_SAFE_SEARCH_URLandYOUTUBE_SAFE_SEARCH_URLhas been added. Those are expected to lead to plain text filters, for example:GENERAL_SAFE_SEARCH_URL='https://adguardteam.github.io/HostlistsRegistry/assets/engines_safe_search.txt' YOUTUBE_SAFE_SEARCH_URL='https://adguardteam.github.io/HostlistsRegistry/assets/youtube_safe_search.txt'
- The environment variables
CONSUL_DNSCHECK_KV_URLandCONSUL_DNSCHECK_SESSION_URLare now unset by default. Which means that by default HTTP key-value database isn't used.
-
The object
webhas a new optional property,linked_ip:web: linked_ip: bind: - address: 127.0.0.1:80 - address: 127.0.0.1:443 certificates: - certificate: ./test/cert.crt key: ./test/cert.key
-
The objects within the
server_groups.*.serversarray have a new optional property,linked_ip_enabled. It isfalseby default. Set totrueto enable linked IP address detection on that server:server_groups: - # … servers: - name: default_dns protocol: dns linked_ip_enabled: true # …
- Used our fork of miekg/dns library to fix the EDNS0 TCP keep-alive issue.
- Removed the static DNS check
/info.txt. Now thatwebmodule is available, it is no more needed since it can be configured via thewebmodule.
-
The object
dohhas been removed. -
The new optional object
webhas been added:web: safe_browsing: bind: - address: 127.0.0.1:80 - address: 127.0.0.1:443 certificates: - certificate: ./test/cert.crt key: ./test/cert.key block_page: /path/to/block_page.html adult_blocking: bind: - address: 127.0.0.1:80 - address: 127.0.0.1:443 certificates: - certificate: ./test/cert.crt key: ./test/cert.key block_page: /path/to/block_page.html non_doh_bind: - address: 127.0.0.1:80 - address: 127.0.0.1:443 certificates: - certificate: ./test/cert.crt key: ./test/cert.key static_content: '/favicon.ico': content_type: image/x-icon content: base64content root_redirect_url: "https://adguard-dns.com" error_404: /path/to/error_404.html error_500: /path/to/error_500.html timeout: 1m
- The object
geoiphas a new property,cache_size.
- The environment variable
LOG_OUTPUThas been removed. Logs are now always written to stdout.
- The environment variable
DNSDB_PATHis now unset by default. Which means that by default DNSDB is disabled.
- The new optional environment variable
SSLKEYLOGFILEhas been added.
- The object
checkhas a new property,node_location.
-
The property
device_id_wildcard_domainsin the objects within theserver_groups.*.serversarray has been renamed to the shorterdevice_id_wildcards. -
The DNS names from certificates are not used to detect device IDs and perform additional validations anymore.
- The new required environment variable
BLOCKED_SERVICE_INDEX_URLhas been added. It has no default value, so it's necessary to set it.
-
The objects within the
server_groups.*.serversarray have a new property,tls.device_id_wildcard_domains. It is an array of domain name wildcards used to detect device IDs. If necessary, add them:server_groups: - # … servers: - name: default_dot # … tls: # … device_id_wildcard_domains: - *.dns.adguard.com
-
The environment variable
CONSUL_URLhas been renamed toCONSUL_ALLOWLIST_URL. -
The new required environment variables
CONSUL_DNSCHECK_KV_URLandCONSUL_DNSCHECK_SESSION_URLare added. They have no default value, so it's necessary to set them. -
The object
checkhas a new property,ttl. Set it to a human-readable duration, for example1m.
- The property
parental.safe_searchof objects within thefiltering_groupsarray is renamed toparental.general_safe_searchto synchronize it with the backend.
-
The object
loghas been removed. Its properties have been moved to the environment. -
The new environment variable
LOG_OUTPUThas been added. It is the path to the plain text log file. Ifstdout, writes to standard output. Ifstderr, writes to standard error.The default value is
stdout, adjust the value, if necessary. -
The new environment variable
LOG_TIMESTAMPhas been added. When it is set to1, timestamps are shown in the plain text logs. When set to0, they are not shown.The default value is
1, adjust the value, if necessary. -
The environment variable
VERBOSEdoesn't support a set but empty value. Unset the value or replace it with a0.
-
Another change in the objects within the
filtering_groups. Before:filtering_groups: - id: default filters: - adguard_dns_filter parental: true block_adult: true safe_browsing: true safe_search: true youtube_safe_search: true
After:
filtering_groups: - id: default parental: enabled: true block_adult: true safe_search: true youtube_safe_search: true rule_lists: enabled: true ids: - adguard_dns_filter safe_browsing: enabled: true
- The object
checkhas a new property,node_name.
-
The objects within the
server_groups.*.serversarray have a new optional property in theirdnscryptobjects,inline. Also, the propertyconfigis renamed toconfig_path. So replace this:server_groups: - name: adguard_dns_default filtering_group: default servers: - name: default_dnscrypt # … dnscrypt: config: './test/dnscrypt.yml' # …
with this:
server_groups: - name: adguard_dns_default filtering_group: default servers: - name: default_dnscrypt # … dnscrypt: inline: provider_name: 2.dnscrypt-cert.example.org public_key: F11DDBCC4817E543845FDDD4CB881849B64226F3DE397625669D87B919BC4FB0 private_key: 5752095FFA56D963569951AFE70FE1690F378D13D8AD6F8054DFAA100907F8B6F11DDBCC4817E543845FDDD4CB881849B64226F3DE397625669D87B919BC4FB0 resolver_secret: 9E46E79FEB3AB3D45F4EB3EA957DEAF5D9639A0179F1850AFABA7E58F87C74C4 resolver_public: 9327C5E64783E19C339BD6B680A56DB85521CC6E4E0CA5DF5274E2D3CE026C6B es_version: 1 certificate_ttl: 8760h # …
or this:
server_groups: - name: adguard_dns_default filtering_group: default servers: - name: default_dnscrypt # … dnscrypt: config_path: './test/dnscrypt.yml' # …
Adjust the values, if necessary.
- The property
server_nameof objectcheckis removed.
-
The new optional object
dohhas been added, which supplements the DNS-over-HTTP server configuration. Example:doh: root_redirect_url: "https://adguard-dns.com/"
-
The objects within the
server_groups.*.serversarray have a new property,tls.session_keys. So, if necessary, replace this:server_groups: - name: adguard_dns_default filtering_group: default servers: - name: default_dot # … tls: certificates: - certificate: ./test/cert.crt key: ./test/cert.key # …
with this:
server_groups: - name: adguard_dns_default filtering_group: default servers: - name: default_dot # … tls: certificates: - certificate: ./test/cert.crt key: ./test/cert.key session_keys: - ./private/key_1 # …
-
The object
backendhas a new property,full_refresh_interval. So replace this:backend: timeout: 10s refresh_interval: 1m
with this:
backend: timeout: 10s refresh_interval: 1m full_refresh_interval: 24h
Adjust the value, if necessary.
-
The new object
checkhas been added, which configures the DNS checks mechanism. Example:check: domain: "dnscheck.adguard.com" ipv4: - 1.2.3.4 - 5.6.7.8 ipv6: - 1234::cdee - 1234::cdef server_name: "AdGuard DNS Default"
- The new environment variable
RULESTAT_URLhas been added. Its default value is, which means that no statistics are gathered. Adjust the value, if necessary.
- The new environment variable
DNSDB_PATHhas been added. Its default value is./dnsdb.bolt. Adjust the value, if necessary.
-
The new required environment variable
CONSUL_URLhas been added. It has no default value, so it's necessary to set it. -
The ratelimit configuration for a server has changed from this:
ratelimit: refuseany: true response_size_limit: 1KB rate_limit_cache_ttl: 10m back_off_cache_ttl: 30m rps: 30 backoff_limit: 1000
to this:
ratelimit: allowlist: list: - '127.0.0.1' - '127.0.0.1/24' refresh_interval: 30s back_off_count: 1000 back_off_duration: 30m back_off_period: 10m refuseany: true response_size_estimate: 1KB rps: 30
See README.md for documentation.
- The property
backendof thequery_logobject is removed.
-
The new required environment variable
FILTER_INDEX_URLhas been added. It has no default value, so it's necessary to set it. -
The environment variable
BACKEND_ENDPOINTis now required and has no default value. -
Property
listsof thefiltersobject is removed. -
A new property
refresh_intervalhas been added to thefiltersobject.
-
The new environment variable
FILTER_CACHE_PATHhas been added. Its default value is./filters/. Adjust the value, if necessary. -
The
listproperty ofsafe_browsingandadult_blockingobjects as well as thepathproperty of thefilters.listsobjects are removed. -
Property
urlof thefilters.listsobjects is now required.
-
The type of the
cache.sizeproperty was changed from bytes to integer. So replace this:cache: size: 50KB
with this:
cache: size: 10000
Set the new values accordingly.
-
The top-level object
parentalwas renamed toadult_blocking. -
The objects
safe_browsingandadult_blockinghave four new properties,cache_size,cache_ttl,refresh_interval, andurl. So replace this:safe_browsing: block_host: standard-block.dns.adguard.com list: ./test/safe_browsing.txt adult_blocking: block_host: family-block.dns.adguard.com list: ./test/parental.txt
with this:
safe_browsing: url: https://static.example.com/safe_browsing.txt block_host: standard-block.dns.adguard.com cache_size: 1024 cache_ttl: 1h list: ./test/safe_browsing.txt refresh_interval: 1h adult_blocking: url: https://static.example.com/adult_blocking.txt block_host: family-block.dns.adguard.com cache_size: 1024 cache_ttl: 1h list: ./test/parental.txt refresh_interval: 1h
Set the new values accordingly.
-
The objects within the
filtering_groupsarray have a new property,block_adult. So replace this:filtering_groups: - id: default filters: - adguard_dns_filter parental: false safe_browsing: true safe_search: false youtube_safe_search: false # …
with this:
filtering_groups: - id: default filters: - adguard_dns_filter parental: false block_adult: false safe_browsing: true safe_search: false youtube_safe_search: false # …
Set the new value accordingly.
-
The objects within the
filters.listsarray have a new property,refresh_interval. The property is only required when the propertyurlis also set. So replace this:filters: # … lists: - id: adguard_dns_filter url: 'https://example.com/adguard_dns_filter.txt' path: ./test/filters/adguard_dns_filter.txt - id: peter_lowe_list path: ./test/filters/peter_lowe_list.txt
with this:
filters: # … lists: - id: adguard_dns_filter url: 'https://example.com/adguard_dns_filter.txt' path: ./test/filters/adguard_dns_filter.txt refresh_interval: 1h - id: peter_lowe_list path: ./test/filters/peter_lowe_list.txt
Set the new value accordingly.
-
The property
youtube_restrictedwas renamed toyoutube_safe_search. So replace this:filtering_groups: - id: default # … youtube_restricted: false - id: strict # … youtube_restricted: true
with this:
filtering_groups: - id: default # … youtube_safe_search: false - id: strict # … youtube_safe_search: true
-
The blocked response TTL parameter has been moved and renamed. From this:
dns: blocked_response_ttl: 10s
to this:
filters: response_ttl: 10s
The
dnsobject has been completely removed.
-
The TLS configuration for a server has changed from this:
tls: certificates: - certificate: /test/cert.crt key: /test/cert.key domains: - dns.adguard.com
to this:
tls: certificates: - certificate: /test/cert.crt key: /test/cert.key
The domains to be used in device ID detection are now expected to be contained in the certificate's DNS Names section of SAN.
-
The filtering configuration has changed from this:
filters: - id: adguard_dns_filter path: ./tmp.dir/filter.txt
to this:
filters: custom_filter_cache_size: 1024 lists: - id: adguard_dns_filter path: ./tmp.dir/filter.txt