From 6d929ee97641bacc7daba7630eab32f092f1fcbc Mon Sep 17 00:00:00 2001 From: DL6ER Date: Tue, 8 May 2018 17:32:24 +0200 Subject: [PATCH 1/2] Add "DNS resolver" page with details on how we integreated and what we actually modified in dnsmasq Signed-off-by: DL6ER --- docs/ftldns/dns-resolver.md | 23 +++++++++++++++++++++++ mkdocs.yml | 14 ++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 docs/ftldns/dns-resolver.md diff --git a/docs/ftldns/dns-resolver.md b/docs/ftldns/dns-resolver.md new file mode 100644 index 0000000..bdcc9d8 --- /dev/null +++ b/docs/ftldns/dns-resolver.md @@ -0,0 +1,23 @@ +*FTL*DNS comes with a lightweight but powerful inbuilt DNS/DHCP/TCP/... server eliminating the need to install `dnsmasq` separately (we used to do this before Pi-hole v4.0). However, it is important to understand that we are not moving away from `dnsmasq`, but, in contrast, are coupling even closer to it by incorporating it into FTL. This provides us with a much more reliable monolith DNS solution where we can be sure that the versions of *FTL* and the DNS internals are always 100% compatible with each other. + +As we maintain our own fork of `dnsmasq` we have been able to apply some *minimal* changes to the source code which might bring substantial benefits for our users. However, although the potential for changes is endless, we want to include as few modifications as possible. As a purely volunteer driven project, you will surely understand that it was already a major undertaking to get *FTL*DNS set up and running. It was much more than just copy-pasting `dnsmasq` into place. + +We have always been very explicit about how we will react to feature requests that target the resolver part (from the initial *FTL*DNS beta test announcement): + +> Think of *FTL*DNS as `dnsmasq` with Pi-hole’s special sauce. This allows us to easily merge any upstream changes that get added, while still allowing us to continue to develop Pi-hole as we have been. + +If we would start to modify the resolver code in too many places, then this would probably make us deviate too much from `dnsmasq`'s code base and we couldn't apply patches easily preventing us from being able to ship important security updates. + +### Implemented modifications in `dnsmasq`'s source code + +#### FTL hooks +We place hooks in a lot of places in the resolver that branch out into `FTL` code to process queries and responses. By this, we keep the resolver code itself clean. + +#### Remove limit on maximum cache size +Users are able to configure the size of the resolvers name cache. The default is 150 names. Setting the cache size to zero disables caching. We think users should be allowed to set the cache size to any value they find appropriate. However, `dnsmasq`'s source code contains a condition that limits the maximum size of the cache to 10,000 names. We removed this hard-coded upper limit in [option.c](https://github.com/pi-hole/FTL/blame/development/dnsmasq/option.c#L2589-L2590) and submitted a patch to remove this hard-coded limit in the upstream version of `dnsmasq`. + +#### Improve detection algorithm for determining the "best" forward destination +The DNS forward destination determination algorithm in *FTL*DNS's is modified to be much less restrictive than the original algorithm in `dnsmasq`. We keep using the fastest responding server now for 1000 queries or 10 minutes (whatever happens earlier) instead of 50 queries or 10 seconds (default values in `dnsmasq`). +We keep the exceptions, i.e., we try all possible forward destinations if `SERVFAIL` or `REFUSED` is received or if a timeout occurs. +Overall, this change has proven to greatly reduce the number of actually performed queries in typical Pi-hole environments. It may even be understood as being preferential in terms of privacy (as we send queries much less often to all servers). +This has been implemented in commit [d1c163e](https://github.com/pi-hole/FTL/commit/d1c163e499a5cd9f311610e9da1e9365bbf81e89) on the `FTLDNS` branch. diff --git a/mkdocs.yml b/mkdocs.yml index 9bf929f..614ad4f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,15 +8,28 @@ theme: language: 'en' markdown_extensions: +# Code highlighting in ``` ``` blocks - codehilite(guess_lang=true) +# Table of Contents - toc(permalink=true) +# block-styled side content - admonition +# linkafies URL and email links without having to wrap them in Markdown syntax. Also, allows shortens repository issue, pull request, and commit links. - pymdownx.magiclink +# Task lists (https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/) - pymdownx.tasklist(custom_checkbox=true) +# Highlight words with ==mark me== - pymdownx.mark +# Adds support for deletion ~~Delete me~~ and subscript text~a\ subscript~ - pymdownx.tilde +# This extension is a convenience extension, and it currently provides no other additional features - pymdownx.extra +# Adds syntax for defining footnotes in Markdown documents (https://python-markdown.github.io/extensions/footnotes/) - footnotes +# Adds the ability to define abbreviations + - abbr +# Include files in other documents like {!some/dir/in/docs/filename.md!} + - markdown_include.include(base_path=docs) pages: - 'Overview & Support': 'index.md' - 'Getting Started': @@ -27,6 +40,7 @@ pages: - 'FTLDNS': - 'Overview': "ftldns/index.md" - 'Configuration': "ftldns/configfile.md" + - 'DNS resolver': "ftldns/dns-resolver.md" - 'Blocking mode': "ftldns/blockingmode.md" - 'RegEx blocking': "ftldns/regex.md" - 'Privacy levels': "ftldns/privacylevels.md" From b674ca338725390e24102380dfa1b8b553552018 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Tue, 8 May 2018 19:59:55 +0200 Subject: [PATCH 2/2] Work on review comments Signed-off-by: DL6ER --- docs/ftldns/dns-resolver.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ftldns/dns-resolver.md b/docs/ftldns/dns-resolver.md index 868f268..a8f5a27 100644 --- a/docs/ftldns/dns-resolver.md +++ b/docs/ftldns/dns-resolver.md @@ -1,4 +1,4 @@ -*FTL*DNS comes with a lightweight but powerful inbuilt DNS/DHCP/TCP/... server eliminating the need to install `dnsmasq` separately (we used to do this before Pi-hole v4.0). However, it is important to understand that we are not moving away from `dnsmasq`, but, in contrast, are coupling even closer to it by incorporating it into FTL. This provides us with a much more reliable monolith DNS solution where we can be sure that the versions of *FTL* and the DNS internals are always 100% compatible with each other. +*FTL*DNS comes with a lightweight but powerful inbuilt DNS/DHCP/TFTP/... server eliminating the need to install `dnsmasq` separately (we used to do this before Pi-hole v4.0). However, it is important to understand that we are not moving away from `dnsmasq`, but, in contrast, are coupling even closer to it by incorporating it into FTL. This provides us with a much more reliable monolith DNS solution where we can be sure that the versions of *FTL* and the DNS internals are always 100% compatible with each other. As we maintain our own fork of `dnsmasq` we have been able to apply some *minimal* changes to the source code which might bring substantial benefits for our users. However, although the potential for changes is endless, we want to include as few modifications as possible. As a purely volunteer driven project, you will surely understand that it was already a major undertaking to get *FTL*DNS set up and running. It was much more than just copy-pasting `dnsmasq` into place. @@ -14,7 +14,7 @@ If we would start to modify the resolver code in too many places, then this woul We place hooks in a lot of places in the resolver that branch out into `FTL` code to process queries and responses. By this, we keep the resolver code itself clean. #### Remove limit on maximum cache size -Users are able to configure the size of the resolvers name cache. The default is 150 names. Setting the cache size to zero disables caching. We think users should be allowed to set the cache size to any value they find appropriate. However, `dnsmasq`'s source code contains a condition that limits the maximum size of the cache to 10,000 names. We removed this hard-coded upper limit in [option.c](https://github.com/pi-hole/FTL/blame/development/dnsmasq/option.c#L2589-L2590) and submitted a patch to remove this hard-coded limit in the upstream version of `dnsmasq`. +Users are able to configure the size of the resolvers name cache. The default is 150 names. Setting the cache size to zero disables caching. We think users should be allowed to set the cache size to any value they find appropriate. However, `dnsmasq`'s source code contains a condition that limits the maximum size of the cache to 10,000 names. We removed this hard-coded upper limit in [option.c](https://github.com/pi-hole/FTL/commit/ea3309e7b1991f50d40555b9a18f39894c237b29#diff-733116077302620357dcd8252f41449dR2582R258) and submitted a patch to remove this hard-coded limit in the upstream version of `dnsmasq`. #### Improve detection algorithm for determining the "best" forward destination The DNS forward destination determination algorithm in *FTL*DNS's is modified to be much less restrictive than the original algorithm in `dnsmasq`. We keep using the fastest responding server now for 1000 queries or 10 minutes (whatever happens earlier) instead of 50 queries or 10 seconds (default values in `dnsmasq`).