From c279f35e144b591338d7efeda958614eac146407 Mon Sep 17 00:00:00 2001
From: Oier Bravo Urtasun <oierbravo@gmail.com>
Date: Sun, 24 May 2026 14:23:14 +0200
Subject: [PATCH] feat(dns): 'hosts' output + /etc/hosts simulation docs

dns-records.sh <mode> hosts prints a marker-wrapped /etc/hosts block to pipe
into /etc/hosts (single-machine testing without a DNS server). README documents
apply/remove + the airgap caveat (spoof hosts break real internet while present).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md              | 22 ++++++++++++++++++++++
 tooling/dns-records.sh | 14 +++++++++++++-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index bd06ff8..3a306ad 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,28 @@ Alternatives: `ENABLE_MDNS=true` + `BASE_DOMAIN=*.local` (zero-config mDNS,
 macOS/Linux native, Windows needs Bonjour) — but mDNS can't serve the air-gap
 upstream spoofs. Or layer in `docker-compose.dnsmasq.yml` for a turnkey DNS.
 
+### Simulate the DNS via /etc/hosts (single machine, testing)
+
+No DNS server? Append the records straight to `/etc/hosts` (marker-wrapped):
+
+```sh
+tooling/dns-records.sh online hosts | sudo tee -a /etc/hosts   # services only
+tooling/dns-records.sh airgap hosts | sudo tee -a /etc/hosts   # + Mojang spoofs
+```
+
+Remove them later:
+
+```sh
+sudo sed -i '/# >>> ulicraft/,/# <<< ulicraft/d' /etc/hosts
+```
+
+Notes:
+- `/etc/hosts` has **no wildcard** — only the listed names resolve.
+- `airgap` adds the Mojang/launcher/NeoForge hostnames pointing at the LAN; this
+  **breaks normal internet access to those domains** while present. Use it only
+  while offline; for an online box use `online`.
+- `mc.<domain>` works (client defaults to :25565); SRV isn't used via `/etc/hosts`.
+
 ## Prerequisites
 
 Docker + Docker Compose; for prep also `pnpm`, `packwiz`, `jq`, `curl`,
diff --git a/tooling/dns-records.sh b/tooling/dns-records.sh
index ac53ca9..ce49e36 100755
--- a/tooling/dns-records.sh
+++ b/tooling/dns-records.sh
@@ -40,9 +40,21 @@ names=("${services[@]}")
 case "$mode" in
   online) ;;
   airgap) names+=("${spoof[@]}") ;;
-  *) echo "usage: $0 [online|airgap]" >&2; exit 1 ;;
+  *) echo "usage: $0 [online|airgap] [hosts]" >&2; exit 1 ;;
 esac
 
+# Marker so /etc/hosts edits can be applied/removed cleanly.
+MARK="ulicraft ${mode}"
+
+# `hosts` format: print ONLY the /etc/hosts block (marker-wrapped) so it can be
+# piped straight into /etc/hosts to simulate the party DNS. See README.
+if [ "${2:-}" = hosts ]; then
+  echo "# >>> ${MARK} >>>"
+  for n in "${names[@]}"; do printf '%s %s\n' "$HOST_LAN_IP" "$n"; done
+  echo "# <<< ${MARK} <<<"
+  exit 0
+fi
+
 echo "# DNS records for mode=${mode}  ->  ${HOST_LAN_IP}"
 echo "# Configure these on your party DNS server (all A records to the host)."
 echo