# E2E DNS from LAN (no public DNS) runbook

When the E2E domain sweep runs from a machine where `*.sankofa.nexus`, `*.d-bis.org`, etc. do not resolve (e.g. no Cloudflare/split-horizon DNS, no VPN), all tests fail at DNS (`Could not resolve host`). This runbook gives three ways to unblock.

## Option 1: Temporary `/etc/hosts` (recommended for this machine)

Use the generated hosts file so this machine resolves all E2E hostnames to the LAN proxy (NPMplus).

1. **Append E2E hosts to `/etc/hosts`** (from repo root):
   ```bash
   sudo cp /etc/hosts /etc/hosts.bak.$(date +%Y%m%d)
   cat config/e2e-hosts-append.txt | sudo tee -a /etc/hosts
   ```
   Or generate fresh:
   ```bash
   ./scripts/verify/generate-e2e-hosts.sh | sudo tee -a /etc/hosts
   ```

2. **Run E2E using the system resolver** (so `getent`/hosts are used instead of `dig @8.8.8.8`):
   ```bash
   E2E_USE_SYSTEM_RESOLVER=1 ./scripts/verify/verify-end-to-end-routing.sh
   ```

3. **Revert when done** (optional): run the dedicated script to remove the E2E block:
   ```bash
   sudo ./scripts/verify/remove-e2e-hosts-from-etc-hosts.sh
   ```
   Or restore from backup: `sudo cp /etc/hosts.bak.YYYYMMDD /etc/hosts`

**Mappings used:** Most domains → NPMplus primary `192.168.11.167`. Gitea/dev/codespaces → NPMplus Fourth `192.168.11.170`. Proxmox UI → `pve.ml110` (`.10`), `pve.r630-01` (`.11`), `pve.r630-02` (`.12`). See `config/ip-addresses.conf` and `scripts/verify/generate-e2e-hosts.sh`.

## Option 2: Working DNS path to `*.sankofa.nexus` (and other zones)

- **Cloudflare:** Ensure the zones (e.g. `sankofa.nexus`, `d-bis.org`) have A/CNAME records pointing to the correct public IPs (e.g. `76.53.10.36` for main NPMplus, `76.53.10.40` for Fourth). Then from any machine with internet, DNS will resolve and E2E can use the default `dig @8.8.8.8` (no `/etc/hosts` or `E2E_USE_SYSTEM_RESOLVER`).
- **Split-horizon / internal DNS:** If you have an internal DNS server that serves these names (e.g. Pi-hole, dnsmasq) with the same mappings as `e2e-hosts-append.txt`, point this machine’s resolver to it and run E2E normally (or with `ACCEPT_ANY_DNS=1` if resolved IPs differ from `PUBLIC_IP`).
- **VPN:** If a VPN makes these hostnames resolve (e.g. via internal DNS), connect and run E2E; you may need `ACCEPT_ANY_DNS=1` if the VPN resolves to private IPs.

## Option 3: Bastion / jump host

Run the E2E sweep from a host where the domains already resolve and are reachable (e.g. a VM on the same LAN that has `/etc/hosts` or internal DNS, or a jump host that uses the right resolver). Copy the repo (or mount it), then:

```bash
# On bastion (with /etc/hosts or DNS already set)
cd /path/to/proxmox
E2E_USE_SYSTEM_RESOLVER=1 ./scripts/verify/verify-end-to-end-routing.sh
```

No need to change the script if the bastion’s resolver returns the correct IPs.

## Summary

| Goal                         | Action                                                                 |
|-----------------------------|------------------------------------------------------------------------|
| Run E2E on this machine now | Use Option 1: append `config/e2e-hosts-append.txt` to `/etc/hosts`, then `E2E_USE_SYSTEM_RESOLVER=1 ./scripts/verify/verify-end-to-end-routing.sh` |
| Fix DNS for everyone        | Option 2: Configure Cloudflare or internal DNS for the E2E hostnames  |
| Run E2E from another host   | Option 3: Use a bastion/jump host that already resolves the domains   |

## References

- E2E script: `scripts/verify/verify-end-to-end-routing.sh`
- Hosts generator: `scripts/verify/generate-e2e-hosts.sh`
- Hosts append file: `config/e2e-hosts-append.txt`
- Revert script: `scripts/verify/remove-e2e-hosts-from-etc-hosts.sh`
- IP source of truth: `config/ip-addresses.conf`