From 910001f0e120b6864e6b9c9d50fad253e6ceabea Mon Sep 17 00:00:00 2001
From: Loryan Strant <51473494+loryanstrant@users.noreply.github.com>
Date: Thu, 27 Nov 2025 01:11:41 +1100
Subject: [PATCH] Add DNS resolution notes to README (#134)

* Add DNS resolution notes to README

Added DNS resolution notes and instructions for using system resolver.
---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 43f8c96..e7fc347 100644
--- a/README.md
+++ b/README.md
@@ -281,6 +281,30 @@ Please review the [hardware](https://github.com/leukipp/touchkio/blob/main/HARDW
 - On the terminal you may see some _ERROR:gbm_wrapper.cc_ messages.
   - This appears to be a [known issue](https://github.com/electron/electron/issues/42322) that currently lacks a fix, but the webview still works.
 
+
+### DNS Resolution Notes
+
+TouchKio is based on Chromium/Electron, which by default may use its own DNS resolver and DNS-over-HTTPS (DoH). This can cause issues if you rely on local DNS or `/etc/hosts` entries, as these may be ignored.
+
+#### Why this happens
+Chromium has an internal asynchronous DNS resolver and optional DoH support. When enabled, it bypasses the system resolver stack, ignoring `/etc/hosts` and local DNS servers.
+
+#### How to fix it
+To force TouchKio to use the system resolver (which respects `/etc/hosts` and your network DNS), disable these Chromium features:
+
+```bash
+touchkio --disable-features=UseDNSHttps,AsyncDns
+```
+
+To make this permanent, modify `~/.config/systemd/user/touchkio.service` and update the `ExecStart` line to look like this:
+
+Then reload the service:
+```bash
+systemctl --user daemon-reload
+systemctl --user restart touchkio.service
+```
+
+
 For debugging, stop the service and launch `touchkio` directly on the terminal to monitor the log output in real-time.
 This output is also written into `~/.config/touchkio/logs/main.log` for review.