From e7a5c42a897bc5483ccb0b5871345cf14fc58bd6 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 11:05:37 +0200 Subject: [PATCH 1/7] docs(doh): update https-dns-proxy guide Document that https-dns-proxy is now bundled in NethSecurity,\nstarts disabled by default, and requires an explicit\ndnsmasq_config_update value plus service enablement before use.\n\nAlso describe the current upgrade caveat: if\ndnsmasq_config_update stays set to '-', the first-boot defaults\nscript can disable the service again after an image upgrade.\n\nAssisted-by: Copilot:gpt-5.4 --- dns_over_http.rst | 50 +++++++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/dns_over_http.rst b/dns_over_http.rst index efe7d0e7..a1cf3c2d 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -10,8 +10,9 @@ DNS over HTTPS (DoH) is a protocol for encrypting DNS queries over HTTPS, enhanc This feature allows you to configure upstream DNS servers that support the DoH protocol. The ``https-dns-proxy`` package provides a local DNS-to-HTTPS proxy that forwards DNS queries to a remote DoH provider. -This document provides instructions for installing and configuring the DoH upstream servers that provide -filtering and are based in the EU, but you can use any DoH provider that suits your needs. +This document provides instructions for configuring DoH upstream servers that +provide filtering and are based in the EU, but you can use any DoH provider +that suits your needs. This configuration only applies to the upstream servers of the firewall: clients will continue to send DNS requests to the firewall in plaintext on port 53. A list of DoH providers that support European locations and filtering are available on the @@ -28,20 +29,23 @@ Some popular alternatives include: Installation ============ -The ``https-dns-proxy`` package is not included in default NethSecurity images, so you will need to install it manually: :: - - opkg update - opkg install https-dns-proxy +The ``https-dns-proxy`` package is included in NethSecurity images, so no +separate installation step is required. Configuration ============= -By default, the package includes two providers (Cloudflare and Google). -To use a custom DoH provider, you'll need to: +By default, the package includes two providers (Cloudflare and Google), listens +on ``127.0.0.1:5053`` and ``127.0.0.1:5054``, and keeps +``dnsmasq_config_update`` set to ``-`` so it does not modify the firewall DNS +configuration automatically. + +To start using the proxy, you need to: 1. Remove the default providers (optional) 2. Add your preferred DoH provider configuration -3. Commit and apply the configuration +3. Choose the ``dnsmasq_config_update`` value to use +4. Commit the configuration and enable the service Configuration steps ------------------- @@ -65,9 +69,16 @@ In this example, we will configure the DNS4EU (joindns4.eu) DoH provider. The ``bootstrap_dns`` parameter is optional, if not provided, the system will use Google and Cloudflare DNS for bootstrap. -3. Apply the configuration, https-dns-proxy will automatically use the local DoH proxy as upstream DNS: :: +3. Enable integration with ``dnsmasq`` and start the service: :: + + uci set https-dns-proxy.config.dnsmasq_config_update='*' + uci commit https-dns-proxy + /etc/init.d/https-dns-proxy enable + /etc/init.d/https-dns-proxy start - reload_config + The value ``*`` updates all ``dnsmasq`` instances. If you need a more + specific integration, set ``dnsmasq_config_update`` to the instance name or + index you want to manage. Verification ^^^^^^^^^^^^ @@ -100,18 +111,15 @@ Run the following commands via SSH or terminal: :: Image update ------------ -The ``https-dns-proxy`` package overrides the default DNS configuration, -so if you update your NethSecurity image, the system will not be able to connect to Internet -and restore the package. +The package is included in the image, so it does not need to be reinstalled +after an upgrade. -To overcome this issue, you can temporarily stop the DoH proxy before updating the image: :: +However, NethSecurity treats ``dnsmasq_config_update='-'`` as the disabled +state. If that value is still set during an image upgrade, the first-boot +defaults script can disable ``https-dns-proxy`` again. - service https-dns-proxy stop - -This will restore the default DNS configuration and allow the system to connect to the Internet -after image update. Once the update is complete, you can restart the DoH proxy: :: - - service https-dns-proxy restart +At the moment this is not expected to be a practical problem because +configuration is supported only from the command line. Blocking other DoH providers ---------------------------- From ac172812d7c38bfb74ba574728b530090cb070e1 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 11:08:54 +0200 Subject: [PATCH 2/7] Apply suggestion from @gsanchietti --- dns_over_http.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/dns_over_http.rst b/dns_over_http.rst index a1cf3c2d..beacd0b8 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -118,8 +118,6 @@ However, NethSecurity treats ``dnsmasq_config_update='-'`` as the disabled state. If that value is still set during an image upgrade, the first-boot defaults script can disable ``https-dns-proxy`` again. -At the moment this is not expected to be a practical problem because -configuration is supported only from the command line. Blocking other DoH providers ---------------------------- From be8367cec3d6424b5999c9ffed6f5bca218fbaf3 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 11:17:40 +0200 Subject: [PATCH 3/7] Apply suggestion from @gsanchietti --- dns_over_http.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dns_over_http.rst b/dns_over_http.rst index beacd0b8..b2ec52de 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -29,7 +29,7 @@ Some popular alternatives include: Installation ============ -The ``https-dns-proxy`` package is included in NethSecurity images, so no +Since NethSecurity 8.8, the ``https-dns-proxy`` package is included in NethSecurity image, so no separate installation step is required. Configuration From 7fd607915f75204d0d1789d18d5c9b806af66501 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 11:18:38 +0200 Subject: [PATCH 4/7] Apply suggestion from @gsanchietti --- dns_over_http.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/dns_over_http.rst b/dns_over_http.rst index b2ec52de..d5026bbe 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -32,6 +32,11 @@ Installation Since NethSecurity 8.8, the ``https-dns-proxy`` package is included in NethSecurity image, so no separate installation step is required. +On NethSecurity 7.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: + + opkg update + opkg install https-dns-proxy + Configuration ============= From 0e1dd359de1284a9f0b52c69bdc8ca1d90970ecd Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 11:19:21 +0200 Subject: [PATCH 5/7] Apply suggestion from @gsanchietti --- dns_over_http.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/dns_over_http.rst b/dns_over_http.rst index d5026bbe..a72344d7 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -32,6 +32,11 @@ Installation Since NethSecurity 8.8, the ``https-dns-proxy`` package is included in NethSecurity image, so no separate installation step is required. +On NethSecurity 7.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: + + opkg update + opkg install https-dns-proxy + On NethSecurity 7.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: opkg update From 917c092d582e8d347c5a02975554225480e1e7b7 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Tue, 26 May 2026 11:19:55 +0200 Subject: [PATCH 6/7] Apply suggestion from @gsanchietti --- dns_over_http.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/dns_over_http.rst b/dns_over_http.rst index a72344d7..d5026bbe 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -32,11 +32,6 @@ Installation Since NethSecurity 8.8, the ``https-dns-proxy`` package is included in NethSecurity image, so no separate installation step is required. -On NethSecurity 7.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: - - opkg update - opkg install https-dns-proxy - On NethSecurity 7.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: opkg update From 3f21c1cd9e9d1bfc9686d9c9155fbeca30a0e020 Mon Sep 17 00:00:00 2001 From: Giacomo Sanchietti Date: Thu, 28 May 2026 15:42:16 +0200 Subject: [PATCH 7/7] Apply suggestion from @gsanchietti --- dns_over_http.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dns_over_http.rst b/dns_over_http.rst index d5026bbe..a84cdf57 100644 --- a/dns_over_http.rst +++ b/dns_over_http.rst @@ -32,7 +32,7 @@ Installation Since NethSecurity 8.8, the ``https-dns-proxy`` package is included in NethSecurity image, so no separate installation step is required. -On NethSecurity 7.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: +On NethSecurity 8.7, the package is not included in default NethSecurity image, so you will need to install it manually: :: opkg update opkg install https-dns-proxy