chore: update submodule references and documentation
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
This commit is contained in:
defiQUG
106
docs/05-network/EXPLORER_PUBLIC_URL_UNREACHABLE_FIX.md
Normal file
106
docs/05-network/EXPLORER_PUBLIC_URL_UNREACHABLE_FIX.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Explorer public URL unreachable — DNS and connectivity fix
|
||||
|
||||
**Issue:** `https://explorer.d-bis.org/` returns timeout (000) from some hosts.
|
||||
**Diagnosis (2026-03-02):** DNS is correct; failure is **connectivity** to the WAN IP or NPMplus from the client.
|
||||
|
||||
---
|
||||
|
||||
## 1. What we know
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| **DNS** | `explorer.d-bis.org` → **76.53.10.36** ✓ (dig, getent) |
|
||||
| **Backend** | **192.168.11.140:443** with `Host: explorer.d-bis.org` → **200** ✓ |
|
||||
| **Curl to 76.53.10.36:443** | **Timeout** (from LAN host 192.168.11.23) |
|
||||
| **Curl to 192.168.11.167:443** (NPMplus) | **000** / timeout (from same LAN host) |
|
||||
|
||||
So the problem is **not** DNS and **not** the explorer backend. It is **reaching** either the UDM Pro WAN IP (76.53.10.36) or NPMplus (192.168.11.167) on port 443 from the client.
|
||||
|
||||
---
|
||||
|
||||
## 2. Likely causes
|
||||
|
||||
### A. NAT hairpin (LAN client → WAN IP)
|
||||
|
||||
If the **client is on the same LAN** (e.g. 192.168.11.x):
|
||||
|
||||
- Traffic to **76.53.10.36** goes to the **UDM Pro** (gateway).
|
||||
- Port forward is: **76.53.10.36:80/443** → **192.168.11.167:80/443** (NPMplus).
|
||||
- Many routers **do not support NAT hairpin** (NAT loopback): traffic from LAN → WAN IP is not translated back to the forwarded host. Result: **timeout** or no route.
|
||||
|
||||
**Fix options:**
|
||||
|
||||
1. **Enable NAT hairpin / loopback** on UDM Pro if available:
|
||||
Settings → Firewall & Security (or Routing) → enable “NAT loopback” / “Hairpin NAT” so that traffic from LAN to 76.53.10.36 is forwarded to 192.168.11.167.
|
||||
2. **Use direct backend for LAN testing:**
|
||||
`curl -sk -H "Host: explorer.d-bis.org" https://192.168.11.140:443/` (or use a **hosts** entry; see below).
|
||||
3. **Hosts file (LAN only):** On machines that need to use the domain from LAN, point the domain at NPMplus or the backend so you don’t go through the WAN IP:
|
||||
- `192.168.11.167 explorer.d-bis.org` (hit NPMplus directly), or
|
||||
- `192.168.11.140 explorer.d-bis.org` (hit explorer backend directly; only if you’re okay bypassing NPMplus).
|
||||
|
||||
### B. UDM Pro port forward
|
||||
|
||||
- Confirm **76.53.10.36** is the correct WAN IP (or the IP used in DNS for explorer.d-bis.org).
|
||||
- Confirm **two** port-forward rules:
|
||||
- **76.53.10.36:80** → **192.168.11.167:80** (TCP)
|
||||
- **76.53.10.36:443** → **192.168.11.167:443** (TCP)
|
||||
- If NPMplus runs on **192.168.11.166** and .167 is a VIP, ensure the forward points to the IP where NPMplus actually listens (often .167 as the floating VIP).
|
||||
|
||||
### C. NPMplus / firewall
|
||||
|
||||
- From a host that **can** reach 192.168.11.0/24 (e.g. Proxmox or another VM):
|
||||
- `curl -sk -H "Host: explorer.d-bis.org" https://192.168.11.167:443/`
|
||||
- `curl -sk -H "Host: explorer.d-bis.org" https://192.168.11.166:443/`
|
||||
- If these fail, check:
|
||||
- NPMplus (and any reverse proxy) is listening on **0.0.0.0:443** (not only 127.0.0.1).
|
||||
- Firewall on the NPMplus host (and Proxmox host) allows **inbound 443** from the LAN (and from the UDM Pro for WAN-originated traffic).
|
||||
|
||||
### D. Cloudflare Tunnel (if used)
|
||||
|
||||
- If explorer.d-bis.org is **not** using “DNS only” and instead uses a **Cloudflare Tunnel** (CNAME to `*.cfargotunnel.com`), then:
|
||||
- DNS would resolve to **Cloudflare IPs**, not 76.53.10.36.
|
||||
- Failure would be tunnel/origin, not UDM Pro port forward.
|
||||
- Current design in docs: **A record 76.53.10.36, DNS only** (no proxy). So if dig shows 76.53.10.36, tunnel is not in the path; if dig shows Cloudflare IPs, follow the tunnel runbook and check tunnel status and origin URL (e.g. https://192.168.11.167:443 or https://192.168.11.140:443).
|
||||
|
||||
---
|
||||
|
||||
## 3. Quick fix for LAN clients (hosts file)
|
||||
|
||||
On machines that must use the domain name from the LAN (and where hairpin is not available or not desired):
|
||||
|
||||
```text
|
||||
# Option A: point domain at NPMplus (recommended if NPMplus is reachable on LAN)
|
||||
192.168.11.167 explorer.d-bis.org
|
||||
|
||||
# Option B: point domain at explorer backend (bypasses NPMplus)
|
||||
192.168.11.140 explorer.d-bis.org
|
||||
```
|
||||
|
||||
- **Linux:** `echo '192.168.11.167 explorer.d-bis.org' | sudo tee -a /etc/hosts`
|
||||
- **Windows:** Add line to `C:\Windows\System32\drivers\etc\hosts` (as Admin).
|
||||
|
||||
Then `curl -sk https://explorer.d-bis.org/` will use the IP in hosts and no longer depend on 76.53.10.36 or hairpin.
|
||||
|
||||
---
|
||||
|
||||
## 4. Verify from external network
|
||||
|
||||
To confirm the **public** path (DNS + UDM Pro + NPMplus) without LAN/hairpin:
|
||||
|
||||
- From a device **off the LAN** (e.g. phone on cellular, or another network):
|
||||
`curl -sI https://explorer.d-bis.org/`
|
||||
- If that returns **200/301/302**, the issue is **only** when calling from inside the LAN (hairpin or firewall). If it also fails, the problem is port forward, NPMplus, or firewall for WAN-originated traffic.
|
||||
|
||||
---
|
||||
|
||||
## 5. Summary
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| DNS | OK (explorer.d-bis.org → 76.53.10.36) |
|
||||
| Explorer backend | OK (192.168.11.140:443 with Host header) |
|
||||
| Public URL from LAN | Fails: timeout to 76.53.10.36 or NPMplus |
|
||||
| Likely cause | NAT hairpin and/or firewall; possibly NPMplus not reachable on .167/.166:443 from this LAN segment |
|
||||
| Fix | Enable hairpin on UDM Pro and/or use hosts file for LAN; verify port forward and NPMplus listen/firewall; test from external network |
|
||||
|
||||
Related: [INGRESS_VERIFICATION_RUNBOOK.md](../04-configuration/INGRESS_VERIFICATION_RUNBOOK.md), [DNS_NPMPLUS_VM_COMPREHENSIVE_ARCHITECTURE.md](../04-configuration/DNS_NPMPLUS_VM_COMPREHENSIVE_ARCHITECTURE.md).
|
||||
88
docs/05-network/FIX_ALL_ISSUES_RUNBOOK.md
Normal file
88
docs/05-network/FIX_ALL_ISSUES_RUNBOOK.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Fix All Issues — Single Runbook
|
||||
|
||||
**Purpose:** One place to fix explorer public URL timeout and other documented issues.
|
||||
**References:** [EXPLORER_PUBLIC_URL_UNREACHABLE_FIX.md](EXPLORER_PUBLIC_URL_UNREACHABLE_FIX.md), [FIXES_PREPARED.md](../04-configuration/FIXES_PREPARED.md), [FULL_FIXES_PREPARED.md](../04-configuration/FULL_FIXES_PREPARED.md).
|
||||
|
||||
---
|
||||
|
||||
## 1. Explorer public URL timeout (ERR_CONNECTION_TIMED_OUT)
|
||||
|
||||
**Symptom:** Browser shows "explorer.d-bis.org took too long to respond" / ERR_CONNECTION_TIMED_OUT.
|
||||
|
||||
### 1a. This machine (ASERET / Linux WSL)
|
||||
|
||||
- **Already done:** `/etc/hosts` contains `192.168.11.140 explorer.d-bis.org` — curl and Linux tools use the backend directly.
|
||||
- **If you removed it:**
|
||||
`echo '192.168.11.140 explorer.d-bis.org' | sudo tee -a /etc/hosts`
|
||||
|
||||
### 1b. Windows (same PC — browser uses Windows hosts)
|
||||
|
||||
So that **Chrome/Edge on Windows** can reach the explorer:
|
||||
|
||||
1. Open Notepad **as Administrator**.
|
||||
2. Open file: `C:\Windows\System32\drivers\etc\hosts`
|
||||
3. Add a line: `192.168.11.140 explorer.d-bis.org`
|
||||
4. Save. Flush DNS: open CMD as Admin → `ipconfig /flushdns`
|
||||
5. Reload https://explorer.d-bis.org/ in the browser.
|
||||
|
||||
### 1c. Fix for all LAN clients (no hosts on each machine)
|
||||
|
||||
On **UDM Pro**: enable **NAT loopback** (hairpin) so traffic from LAN to 76.53.10.36 is forwarded to 192.168.11.167.
|
||||
|
||||
- UniFi Network → Settings → Firewall & Security (or Routing) → enable **NAT loopback** / **Hairpin NAT** if available.
|
||||
- Then any device on the LAN can use https://explorer.d-bis.org without a hosts entry.
|
||||
|
||||
### 1d. External access (from internet)
|
||||
|
||||
Confirm **UDM Pro** port forward:
|
||||
|
||||
- **76.53.10.36:80** → **192.168.11.167:80** (TCP)
|
||||
- **76.53.10.36:443** → **192.168.11.167:443** (TCP)
|
||||
|
||||
Test from a device **off the LAN** (e.g. phone on cellular): `https://explorer.d-bis.org/` → should return 200.
|
||||
|
||||
---
|
||||
|
||||
## 2. Other required fixes (from FIXES_PREPARED / FULL_FIXES_PREPARED)
|
||||
|
||||
| Item | Action | Doc |
|
||||
|------|--------|-----|
|
||||
| UDM Pro port forward (Alltra/HYBX) | Manual: 76.53.10.38 → 192.168.11.169 (80, 81, 443) | [FIXES_PREPARED.md §1](../04-configuration/FIXES_PREPARED.md#1-udm-pro-port-forward-alltrahybx) |
|
||||
| Alltra/HYBX 502 | Verify backends (2500–2502, 2503–2505, 5201, 5202); fix NPMplus or deploy | [FIXES_PREPARED.md §2](../04-configuration/FIXES_PREPARED.md#2-alltrahybx-502-failures-required) |
|
||||
| Validators / block production | Run validator fix; ensure 4/5 active | [FULL_FIXES_PREPARED.md §1](../04-configuration/FULL_FIXES_PREPARED.md) |
|
||||
| Stuck tx / Sentry / RPC nodes | Per FULL_FIXES_PREPARED §§2–4 | [FULL_FIXES_PREPARED.md](../04-configuration/FULL_FIXES_PREPARED.md) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Optional fixes (scripts from project root)
|
||||
|
||||
From repo root (`/home/intlc/projects/proxmox`):
|
||||
|
||||
```bash
|
||||
# NPMplus certs (remaining Alltra/HYBX)
|
||||
FIRST_ONLY=1 NPM_URL=https://192.168.11.167:81 bash scripts/request-npmplus-certificates.sh
|
||||
NPM_URL=https://192.168.11.167:81 bash scripts/request-npmplus-certificates.sh
|
||||
|
||||
# Explorer SSL
|
||||
# NPMplus UI → Proxy Hosts → explorer.d-bis.org → SSL tab → request/renew
|
||||
|
||||
# Env permissions
|
||||
bash scripts/security/secure-env-permissions.sh
|
||||
|
||||
# Shellcheck (optional)
|
||||
bash scripts/verify/run-shellcheck.sh --optional
|
||||
|
||||
# Full verification
|
||||
bash scripts/verify/run-full-verification.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Quick checklist
|
||||
|
||||
- [ ] **Explorer from this machine:** hosts entry present → curl https://explorer.d-bis.org/ returns 200
|
||||
- [ ] **Explorer from Windows browser:** Windows hosts has `192.168.11.140 explorer.d-bis.org` (or use UDM Pro hairpin)
|
||||
- [ ] **Explorer from all LAN:** UDM Pro NAT loopback enabled (optional)
|
||||
- [ ] **Explorer from internet:** UDM Pro 76.53.10.36:80/443 → 192.168.11.167
|
||||
- [ ] **Other required:** Alltra/HYBX port forward and 502 fixes per FIXES_PREPARED / FULL_FIXES_PREPARED
|
||||
- [ ] **Optional:** NPMplus certs, Explorer SSL, env permissions, shellcheck, full verification
|
||||
@@ -16,6 +16,8 @@ This directory contains network infrastructure documentation.
|
||||
- **[EDGE_PORT_VERIFICATION_RUNBOOK.md](EDGE_PORT_VERIFICATION_RUNBOOK.md)** ⭐⭐ - Verify 76.53.10.36:80/443 from internet
|
||||
- **[E2E_CLOUDFLARE_DOMAINS_RUNBOOK.md](E2E_CLOUDFLARE_DOMAINS_RUNBOOK.md)** ⭐⭐⭐ - E2E for all Cloudflare domains (ACCEPT_ANY_DNS=1 when Option B)
|
||||
- **[E2E_RPC_EDGE_LIMITATION.md](E2E_RPC_EDGE_LIMITATION.md)** - When edge blocks RPC POST; Option B / ACCEPT_ANY_DNS
|
||||
- **[EXPLORER_PUBLIC_URL_UNREACHABLE_FIX.md](EXPLORER_PUBLIC_URL_UNREACHABLE_FIX.md)** - explorer.d-bis.org timeout: DNS vs NAT hairpin / tunnel / port forward
|
||||
- **[FIX_ALL_ISSUES_RUNBOOK.md](FIX_ALL_ISSUES_RUNBOOK.md)** - Single runbook: explorer timeout (hosts, hairpin), required/optional fixes, script
|
||||
- **[NETWORK_STATUS.md](NETWORK_STATUS.md)** ⭐⭐ - Current network status and configuration
|
||||
- **[NGINX_ARCHITECTURE_RPC.md](NGINX_ARCHITECTURE_RPC.md)** ⭐ - NGINX RPC architecture
|
||||
- **[CLOUDFLARE_NGINX_INTEGRATION.md](CLOUDFLARE_NGINX_INTEGRATION.md)** ⭐ - Cloudflare + NGINX integration
|
||||
|
||||
Reference in New Issue
Block a user