From 65e686512539453c7dd8cd38c25dc3bbd65c1465 Mon Sep 17 00:00:00 2001
From: dev <dev@noreply.git.backend-3.com>
Date: Thu, 15 Oct 2026 06:39:59 +0000
Subject: [PATCH] Add extra/dns/README.md

---
 extra/dns/README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 extra/dns/README.md

diff --git a/extra/dns/README.md b/extra/dns/README.md
new file mode 100644
index 0000000..ea8a826
--- /dev/null
+++ b/extra/dns/README.md
@@ -0,0 +1,97 @@
+
+local dns control for linux with leak reduction, firewall-aware protections, and repair tools.
+
+### what it does
+
+- routes system dns through local `dnsmasq` -> `unbound`
+- keeps dns easier to monitor and control
+- helps reduce dns leak risk
+- adds rollback and repair workflows for safer network changes
+
+### local chain
+
+- `dnsmasq` on `127.0.0.1:53`
+- `unbound` on `127.0.0.1:5335`
+
+### includes
+
+- localhost-only dns listeners
+- blocklist and whitelist support
+- upstream dns presets and custom upstreams
+- vpn-aware firewall rules
+- lockdown mode on disconnect
+- dns-only fallback mode
+- route and wireguard checks
+- one-click repair and dns repair
+- ipv4-only `unbound`
+- gui and headless command support
+
+> [!NOTE]
+> optional proton cli supported- if unavailable, local dns, firewall, and repair features can still be used normally.
+
+### install
+
+```bash
+tar -xzf dns-linux-amd64.tar.gz
+cd dns
+chmod +x dns
+sudo cp dns /usr/local/bin/dns
+sudo chmod +x /usr/local/bin/dns
+sudo cp app.ico /usr/share/pixmaps/dns.ico
+sudo tee /usr/share/applications/dns.desktop >/dev/null <<'EOF'
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=dns
+Comment=dns manager
+Exec=/usr/local/bin/dns
+Icon=/usr/share/pixmaps/dns.ico
+Terminal=false
+Categories=Network;Security;System;
+StartupNotify=true
+EOF
+sudo update-desktop-database /usr/share/applications 2>/dev/null || true
+dns --headless status
+```
+
+### run
+
+```bash
+dns
+```
+
+### cmds
+
+```bash
+dns --headless status
+dns --headless tests
+dns --headless startup-report
+```
+
+### admin
+
+```bash
+sudo dns --headless apply
+sudo dns --headless confirm-apply
+sudo dns --headless repair
+sudo dns --headless repair-dns
+sudo dns --headless revert
+```
+
+### build
+
+```bash
+chmod +x install.sh build.sh package-install.sh
+./install.sh
+./build.sh onefile
+```
+
+### uninstall
+
+```bash
+sudo rm -f /usr/local/bin/dns
+sudo rm -f /usr/share/pixmaps/dns.ico
+sudo rm -f /usr/share/applications/dns.desktop
+sudo rm -rf /opt/dns
+sudo update-desktop-database /usr/share/applications 2>/dev/null || true
+```
\ No newline at end of file