Skip to content

Commit aae1d09

Browse files
committed
Add tunnel domain setup guide and diagnostic hints for 0% pass rate
GUIDE.md: Add section 3.6 explaining NS delegation setup required for --domain flag, with DNS record examples, verification commands, and common mistakes table. Update dnstt-client download URLs to match renamed release assets. scan.go: Show actionable hints when steps fail at 0% (resolve/tunnel NS setup, ping ICMP blocked, e2e server not running).
1 parent 315a5bd commit aae1d09

2 files changed

Lines changed: 84 additions & 8 deletions

File tree

GUIDE.md

Lines changed: 64 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,8 @@ findns همه این‌ها را به صورت خودکار تست می‌کند
4646
**ویندوز:**
4747
```powershell
4848
# دانلود از صفحه Release:
49-
# https://github.com/SamNet-dev/findns/releases/latest/download/dnstt-client-windows-amd64.exe
50-
# فایل را کنار findns.exe بگذارید و نامش را تغییر دهید:
51-
52-
rename dnstt-client-windows-amd64.exe dnstt-client.exe
49+
# https://github.com/SamNet-dev/findns/releases/latest/download/dnstt-client.exe
50+
# فایل را کنار findns.exe بگذارید — همین!
5351
```
5452

5553
<div dir="rtl">
@@ -72,9 +70,9 @@ rename dnstt-client-windows-amd64.exe dnstt-client.exe
7270
**لینوکس:**
7371
```bash
7472
# دانلود
75-
curl -LO https://github.com/SamNet-dev/findns/releases/latest/download/dnstt-client-linux-amd64
76-
chmod +x dnstt-client-linux-amd64
77-
mv dnstt-client-linux-amd64 dnstt-client
73+
curl -LO https://github.com/SamNet-dev/findns/releases/latest/download/dnstt-client-linux
74+
chmod +x dnstt-client-linux
75+
mv dnstt-client-linux dnstt-client
7876

7977
# گذاشتن کنار findns (ساده‌ترین روش):
8078
mv dnstt-client /path/to/findns/
@@ -414,6 +412,65 @@ findns local --list-ranges
414412

415413
---
416414

415+
## 3.6. تنظیم دامنه تانل (مهم — قبل از اسکن بخوانید)
416+
417+
فلگ `--domain` در findns یک دامنه معمولی نیست — باید یک **ساب‌دامین با NS delegation** به سرور DNSTT/Slipstream شما باشد. بدون این تنظیم، مرحله `resolve/tunnel` همیشه 0% خواهد بود.
418+
419+
### چطور تنظیم کنیم؟
420+
421+
فرض کنید دامنه شما `example.com` است و سرور DNSTT روی آی‌پی `1.2.3.4` اجرا می‌شود. باید دو رکورد DNS در پنل دامنه (Cloudflare، Namecheap و ...) اضافه کنید:
422+
423+
</div>
424+
425+
```
426+
نوع نام مقدار
427+
────── ────────────── ──────────────
428+
NS t.example.com ns.example.com
429+
A ns.example.com 1.2.3.4
430+
```
431+
432+
<div dir="rtl">
433+
434+
**توضیح:**
435+
- رکورد **NS**: می‌گوید "برای هر چیزی درباره `t.example.com`، از سرور `ns.example.com` بپرس"
436+
- رکورد **A**: می‌گوید "`ns.example.com` روی آی‌پی `1.2.3.4` است"
437+
438+
بعد از تنظیم، سرور DNSTT شما تمام کوئری‌های DNS برای `t.example.com` را دریافت می‌کند و ترافیک تانل از آن عبور می‌کند.
439+
440+
### تست صحت تنظیم
441+
442+
قبل از اسکن با findns، مطمئن شوید تنظیم درست است:
443+
444+
</div>
445+
446+
```bash
447+
# تست با Google DNS (باید NS record برگرداند):
448+
nslookup -type=NS t.example.com 8.8.8.8
449+
450+
# یا با dig:
451+
dig t.example.com NS @8.8.8.8
452+
453+
# جواب صحیح باید شامل ns.example.com باشد.
454+
# اگر "NXDOMAIN" یا "no answer" گرفتید = تنظیم اشتباه است.
455+
```
456+
457+
<div dir="rtl">
458+
459+
### اشتباهات رایج
460+
461+
| اشتباه | نتیجه |
462+
|--------|-------|
463+
| استفاده از دامنه اصلی (`--domain example.com`) به جای ساب‌دامین | resolve/tunnel فیل می‌شود چون NS دامنه اصلی به registrar اشاره می‌کند نه سرور شما |
464+
| فقط A record برای `t.example.com` بدون NS delegation | resolve/tunnel فیل می‌شود چون NS وجود ندارد |
465+
| NS تنظیم شده ولی سرور DNSTT روشن نیست | resolve/tunnel ممکن است پاس شود (NS وجود دارد) ولی e2e فیل می‌شود |
466+
| استفاده از `t.example.com` به صورت واقعی (دامنه تست) | resolve/tunnel فیل می‌شود — باید دامنه خودتان باشد |
467+
468+
> **اگر resolve/tunnel برای تمام resolverها فیل شد (0%):** مشکل از resolverها نیست — مشکل از تنظیم DNS دامنه شماست. تنظیم NS delegation را بررسی کنید.
469+
470+
> **اگر سرور DNSTT ندارید:** بدون `--domain` اسکن کنید. فقط مراحل ping/resolve/nxdomain اجرا می‌شود و resolverهای سالم را پیدا می‌کنید.
471+
472+
---
473+
417474
## 4. اسکن کامل (scan) - دستور اصلی
418475

419476
دستور scan مهم‌ترین و پیشنهادی‌ترین دستور است. تمام مراحل تست را به ترتیب اجرا می‌کند و فقط resolverهایی که همه مراحل را پاس کنند در خروجی نهایی می‌آیند.

cmd/scan.go

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -276,7 +276,26 @@ func printSummary(report scanner.ChainReport, topN int, totalTime time.Duration)
276276
fmt.Fprintf(w, " %s%s%s\n", colorDim, strings.Repeat("\u2500", 50), colorReset)
277277

278278
if len(report.Passed) == 0 {
279-
fmt.Fprintf(w, "\n %s\u2718 No resolvers passed all steps%s\n\n", colorRed, colorReset)
279+
fmt.Fprintf(w, "\n %s\u2718 No resolvers passed all steps%s\n", colorRed, colorReset)
280+
// Print diagnostic hints for common failure patterns
281+
for _, step := range report.Steps {
282+
if step.Passed == 0 && step.Tested > 0 {
283+
switch step.Name {
284+
case "resolve/tunnel", "doh/resolve/tunnel":
285+
fmt.Fprintf(w, "\n %s\u26a0 Hint: resolve/tunnel had 0%% pass rate.%s\n", colorYellow, colorReset)
286+
fmt.Fprintf(w, " %sThis usually means your tunnel domain's NS delegation is not set up correctly.%s\n", colorDim, colorReset)
287+
fmt.Fprintf(w, " %sVerify with: nslookup -type=NS <your-domain> 8.8.8.8%s\n", colorDim, colorReset)
288+
fmt.Fprintf(w, " %sYou need NS + glue A records pointing to your DNSTT server.%s\n", colorDim, colorReset)
289+
fmt.Fprintf(w, " %sSee: https://github.com/SamNet-dev/findns/blob/main/GUIDE.md#-تنظیم-دامنه-تانل-مهم--قبل-از-اسکن-بخوانید%s\n", colorDim, colorReset)
290+
case "ping":
291+
fmt.Fprintf(w, "\n %s\u26a0 Hint: ping had 0%% pass rate. Try --skip-ping (ICMP may be blocked).%s\n", colorYellow, colorReset)
292+
case "e2e/dnstt", "e2e/slipstream", "doh/e2e":
293+
fmt.Fprintf(w, "\n %s\u26a0 Hint: e2e had 0%% pass rate. Make sure your tunnel server is running.%s\n", colorYellow, colorReset)
294+
}
295+
break // Only show hint for the first failing step
296+
}
297+
}
298+
fmt.Fprintln(w)
280299
return
281300
}
282301

0 commit comments

Comments
 (0)