# Technical Documentation: nxtrace/NTrace-core

> ℹ️ **Provenance:** Hybrid Fusion: `nxtrace/NTrace-core` (README + 1 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/nxtrace/NTrace-core) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (nxtrace/NTrace-core)

<h1 align="center">
  NextTrace
</h1>

<h4 align="center">An open source visual routing tool that pursues light weight, developed using Golang.</h4>

---

<h6 align="center">HomePage: www.nxtrace.org</h6>



## IAAS Sponsor


    <a href="https://dmit.io">
        
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;
    <a href="https://misaka.io" >
        
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;
    <a href="https://portal.saltyfish.io" >
        
    </a>


We are extremely grateful to [DMIT](https://dmit.io), [Misaka](https://misaka.io) and [SnapStack](https://portal.saltyfish.io) for providing the network infrastructure that powers this project.

## How To Use

Document Language: English | [简体中文](README_zh_CN.md)

⚠️ Please note: We welcome PR submissions from the community, but please submit your PRs to the [NTrace-dev](https://github.com/nxtrace/NTrace-dev) repository instead of [NTrace-core](https://github.com/nxtrace/NTrace-core) repository.
Regarding the NTrace-dev and NTrace-core repositories:
Both will largely remain consistent with each other. All development work is done within the NTrace-dev repository. The NTrace-dev repository releases new versions first. After running stably for an undetermined period, we will synchronize that version to NTrace-core. This means that the NTrace-dev repository serves as a "beta" or "testing" version.
Please note, there are exceptions to this synchronization. If a version of NTrace-dev encounters a serious bug, NTrace-core will skip that flawed version and synchronize directly to the next version that resolves the issue.

### Automated Install

- Debian / Ubuntu
  - Recommended: install from the official `nexttrace-debs` APT repository
    - Supports: `amd64`, `i386`, `arm64`, `armel`, `armhf`, `loong64`, `mipsel`, `mips64el`, `ppc64el`, `riscv64`, `s390x`
    - Add the repository and install the default package:
      ```shell
      sudo install -d -m 0755 /etc/apt/keyrings
      curl -fsSL -o /tmp/nexttrace-archive-keyring.gpg https://github.com/nxtrace/nexttrace-debs/releases/latest/download/nexttrace-archive-keyring.gpg
      sudo install -m 0644 /tmp/nexttrace-archive-keyring.gpg /etc/apt/keyrings/nexttrace.gpg
      rm -f /tmp/nexttrace-archive-keyring.gpg
      printf '%s\n' 'Types: deb' 'URIs: https://github.com/nxtrace/nexttrace-debs/releases/latest/download/' 'Suites: ./' 'Signed-By: /etc/apt/keyrings/nexttrace.gpg' | sudo tee /etc/apt/sources.list.d/nexttrace.sources >/dev/null
      sudo apt update
      sudo apt install nexttrace
      ```
    - Optionally install additional flavors:
      ```shell
      sudo apt install nexttrace-tiny
      sudo apt install ntr
      ```
    - Packages can be installed side by side. Commands: `nexttrace`, `nexttrace-tiny`, `ntr`

- Linux / macOS / BSD
  - One-click installation script (Full, default)

    ```shell
    curl -sL https://nxtrace.org/nt | bash
    ```

  - One-click installation script (Tiny)

    ```shell
    curl -sL https://nxtrace.org/nt | bash -s -- --flavor tiny
    ```

  - One-click installation script (NTR)

    ```shell
    curl -sL https://nxtrace.org/nt | bash -s -- --flavor ntr
    ```

  - Installed command names: Full `nexttrace`, Tiny `nexttrace-tiny`, NTR `ntr`

  - Arch Linux AUR installation command
    - Directly download bin package (only supports amd64)
      ```shell
      yay -S nexttrace-bin
      ```
    - Build from source (only supports amd64)
      ```shell
      yay -S nexttrace
      ```
    - The AUR builds are maintained by ouuan, huyz

  - Linuxbrew's installation command

    Same as the macOS Homebrew installation method. The homebrew-core formula provides the Full flavor (`nexttrace`); the `nxtrace/nexttrace` tap provides all three flavors.

  - deepin installation command
    ```shell
    apt install nexttrace
    ```
  - [x-cmd](https://www.x-cmd.com/pkg/nexttrace) installation command

    ```shell
    x env use nexttrace
    ```

  - Termux installation command
    ```shell
    pkg install root-repo
    pkg install nexttrace
    ```
  - ImmortalWrt installation command
    ```shell
    opkg install nexttrace
    ```

- macOS
  - macOS Homebrew's installation command
    - Homebrew-core version
      ```shell
      brew install nexttrace
      ```
    - `nxtrace/nexttrace` tap version (periodically synced from the latest NTrace-core release)
      ```shell
      brew tap nxtrace/nexttrace
      brew install nxtrace/nexttrace/nexttrace
      brew install nxtrace/nexttrace/nexttrace-tiny
      brew install nxtrace/nexttrace/ntr
      ```
    - The homebrew-core build is maintained by chenrui333, please note that this version's updates may lag behind the repository Action automatically version

- Windows
  - Windows WinGet installation command
    - WinGet version
      ```powershell
      winget install nexttrace
      ```
    - WinGet build maintained by Dragon1573

  - Windows Scoop installation command
    - Scoop-extras version
      ```powershell
      scoop bucket add extras && scoop install extras/nexttrace
      ```
    - Scoop-extra is maintained by soenggam

Please note:

- The `nexttrace-debs` APT repository is maintained by nxtrace and wcbing.
- Other package sources above are maintained by open-source enthusiasts. Availability and timely updates are not guaranteed. If you encounter problems, please contact the repository maintainer to solve them, or use the binary packages provided by the official build of this project.

### Manual Install

- Download the precompiled executable

  For users not covered by the above methods, please go directly to [Release](https://www.nxtrace.org/downloads) to download the compiled binary executable.
  - `Release` provides compiled binary executables for many systems and different architectures. If none are available, you can compile it yourself.
  - Some essential dependencies of this project are not fully implemented on `Windows` by `Golang`, so currently, `NextTrace` is in an experimental support phase on the `Windows` platform.

### Build Variants

Starting from this release, NextTrace is published in **three flavors** under the same tag. Choose the one that best fits your use case:

| Feature               | `nexttrace` (Full) | `nexttrace-tiny` |    `ntr`     |
| --------------------- | :----------------: | :--------------: | :----------: |
| Normal traceroute     |         ✅         |        ✅        |      —       |
| Standalone MTU (`--mtu`) |      ✅         |        ✅        |      —       |
| DNS client (`-l` / `--dns`) |     ✅       |        —         |      —       |
| CDN Speed (`--speed`) |         ✅         |        —         |      —       |
| IP annotation (`--nali`) |       ✅       |        —         |      —       |
| MTR TUI               |         ✅         |        —         | ✅ (default) |
| MTR report (`-r`)     |         ✅         |        —         |      ✅      |
| MTR wide (`-w`)       |         ✅         |        —         |      ✅      |
| MTR raw (`--raw`)     |         ✅         |        —         |      ✅      |
| Globalping (`--from`) |         ✅         |        —         |      —       |
| WebUI (`--deploy`) / MCP (`--deploy --mcp`) |        ✅         |        —         |      —       |
| Fast Trace (`-F`)     |         ✅         |        ✅        |      —       |
| Default mode          |     traceroute     |    traceroute    |   MTR TUI    |
| Binary name           |    `nexttrace`     | `nexttrace-tiny` |    `ntr`     |

> **Note:** `APT (nexttrace-debs)` and the `Homebrew tap (nxtrace/nexttrace)` provide all three flavors: **Full** (`nexttrace`), **Tiny** (`nexttrace-tiny`), and **NTR** (`ntr`). `homebrew-core`, AUR, Scoop, and other package managers currently install the **Full** (`nexttrace`) version only.

### Feature Matrix

- **`nexttrace`** — Full-featured build. Includes traceroute, the standalone DNS client and MTU modes, CDN speed test, IP annotation, MTR, Globalping, Fast Trace, WebUI, and deploy MCP.
- **`nexttrace-tiny`** — Lightweight build. Keeps normal traceroute, standalone MTU, and Fast Trace. No DNS client / CDN speed test / IP annotation / MTR / Globalping / WebUI / MCP. Suitable for embedded or minimal environments.
- **`ntr`** — MTR-focused build. Runs MTR TUI by default. No normal traceroute mode, standalone DNS client or `--mtu`, CDN speed test, IP annotation, Globalping, Fast Trace, WebUI, or MCP.

### Manual Build

Build from source with Go 1.26.5+ installed:

```bash
# Full (all features)
go build -trimpath -o dist/nexttrace -ldflags "-w -s" .

# Tiny (no DNS client, no MTR, no Globalping, no WebUI)
go build -tags flavor_tiny -trimpath -o dist/nexttrace-tiny -ldflags "-w -s" .

# NTR (MTR-only)
go build -tags flavor_ntr -trimpath -o dist/ntr -ldflags "-w -s" .
```

On macOS, source builds require Xcode Command Line Tools and cgo because TCP/UDP packet capture links against the system `libpcap`. For a native build, `go env CGO_ENABLED` must report `1`. If it reports `0`, remove any persistent override with `go env -u CGO_ENABLED`, ensure `xcode-select -p` succeeds, and build with `CGO_ENABLED=1`.

Cross-compile example:

```bash
# Linux arm64, Tiny flavor
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
  go build -tags flavor_tiny -trimpath -o dist/nexttrace-tiny_linux_arm64 -ldflags "-w -s" .
```

The `tiny` and `ntr` flavors use **compile-time build tags** to exclude modules — this is not a runtime switch. You can verify with `go version -m ` that `gin`, `globalping-cli`, and `github.com/natesales/q` are absent from `nexttrace-tiny` and `ntr`.

The `.cross_compile.sh` script supports building flavors:

```bash
./.cross_compile.sh all     # Build all three flavors for all platforms
./.cross_compile.sh full    # Build only nexttrace (Full)
./.cross_compile.sh tiny    # Build only nexttrace-tiny
./.cross_compile.sh ntr     # Build only ntr
```

### Release Assets Naming

Release binaries follow this naming convention:

```
{binary}_{os}_{arch}[v{arm}][.exe][_softfloat]
```

Examples:

- `nexttrace_linux_amd64`, `nexttrace-tiny_linux_amd64`, `ntr_linux_amd64`
- `nexttrace_darwin_universal`, `nexttrace-tiny_darwin_universal`, `ntr_darwin_universal`
- `nexttrace_windows_amd64.exe`, `ntr_windows_amd64.exe`

### Get Started

`NextTrace` uses the `ICMP` protocol to perform TraceRoute requests by default, which supports both `IPv4` and `IPv6`

```bash
# IPv4 ICMP Trace
nexttrace 1.0.0.1
# URL
nexttrace http://example.com:8080/index.html?q=1

# Table output (report mode): runs trace once and prints a final summary table
nexttrace --table 1.0.0.1

# Machine-readable output: stdout is a single JSON document
nexttrace --raw 1.0.0.1
nexttrace --json 1.0.0.1

# Realtime trace output to a custom file
nexttrace --output ./trace.log 1.0.0.1

# Realtime trace output to the default log file
nexttrace --output-default 1.0.0.1

# IPv4/IPv6 Resolve Only, and automatically select the first IP when there are multiple IPs
nexttrace --ipv4 g.co
nexttrace --ipv6 g.co

# IPv6 ICMP Trace
nexttrace 2606:4700:4700::1111

# Developer mode: set the ENV variable NEXTTRACE_DEVMODE=1 to make fatal errors panic with a stack trace
export NEXTTRACE_DEVMODE=1

# Set TTL-group interval in normal traceroute mode (default: 300ms)
nexttrace -i 300 1.1.1.1

# Disable Path Visualization With the -M parameter
nexttrace koreacentral.blob.core.windows.net
# MapTrace URL: https://api.nxtrace.org/tracemap/html/c14e439e-3250-5310-8965-42a1e3545266.html

# Disable MPLS display using the --disable-mpls / -e parameter or the NEXTTRACE_DISABLEMPLS environment variable
nexttrace --disable-mpls example.com
export NEXTTRACE_DISABLEMPLS=1
```

Normal traceroute reports why it stopped: destination reached, a terminal unreachable response (including its marker), or the configured maximum hop count. `--json` keeps the existing top-level result shape and adds optional `StopReason` with lowercase nested fields `hop`, `reason`, `responses`, and `markers`; `responses` contains human-readable descriptions while `markers` contains machine-readable codes. Classic/raw/JSON modes do not receive an extra human-readable footer. `--output` writes the same plain stop line to the log without ANSI escapes.

When multiple normal-trace output modes are selected, precedence is `--json` > `--table` > `--classic` > `--raw` > `--output` > realtime output. If a higher-priority mode overrides an explicit `--output` or `--output-default`, NextTrace reports that choice on stderr and does not create the ignored log file.

PS: The route visualization module is an independent component, You can find its source code at [nxtrace/traceMap](https://github.com/nxtrace/traceMap).  
The routing visualization function requires the geographical coordinates of each hop. It is currently available with NextTrace API, IPInfo, and IP-API.com.

#### Mandatory Configuration Steps for `Windows` Users

- **For Normal User Mode:**  
  Only **ICMP mode** can be used, and the firewall must allow `ICMP/ICMPv6` traffic.
  ```powershell
  netsh advfirewall firewall add rule name="All ICMP v4" dir=in action=allow protocol=icmpv4:any,any
  netsh advfirewall firewall add rule name="All ICMP v6" dir=in action=allow protocol=icmpv6:any,any
  ```
- **For Administrator Mode:**  
  **TCP/UDP mode** requires `WinDivert`.  
  **ICMP mode** supports `1=Socket` and `2=WinDivert` (`0=Auto`). If running in Socket mode, the firewall must allow `ICMP/ICMPv6`.  
  On `Windows`, `ICMPv6` without `--tos` (or with `--tos 0`) keeps using the native Socket send path. A non-zero `ICMPv6 --tos` requires `WinDivert` send support in addition to administrator privilege.  
  `WinDivert` can be automatically configured using the `--init` parameter, which extracts the runtime to the executable directory.

#### `NextTrace` now supports quick testing, and friends who have a one-time backhaul routing test requirement can use it

```bash
# IPv4 ICMP Fast Test (Beijing + Shanghai + Guangzhou + Hangzhou) in China Telecom / Unicom / Mobile / Education Network
nexttrace --fast-trace

# You can also use TCP SYN for testing
nexttrace --fast-trace --tcp

# You can also quickly test through a customized IP/DOMAIN list file
nexttrace --file /path/to/your/iplist.txt
# CUSTOMIZED IP DOMAIN LIST FILE FORMAT
## One IP/DOMAIN per line + space + description information (optional)
## forExample:
## 106.37.67.1 BEIJING-TELECOM
## 240e:928:101:31a::1 BEIJING-TELECOM
## bj.10086.cn BEIJING-MOBILE
## 2409:8080:0:1::1
## 223.5.5.5
```

#### `NextTrace` already supports route tracing for specified Network Devices

On macOS and Linux, `--dev` binds the requested source interface.
On Windows, `--dev` resolves the source IP from the selected device and uses that source address for ICMP/TCP/UDP probes; it does not bind WinDivert or sockets to a real egress interface, so Windows routing may still choose a different path. The standalone `--mtu` mode follows the same source-address behavior and also uses the device name for local MTU lookup.

```bash
# Use eth0 network interface
nexttrace --dev eth0 2606:4700:4700::1111

# Use eth0 network interface's IP
# When using the network interface's IP for route tracing, note that the IP type to be traced should be the same as network interface's IP type (e.g. both IPv4)
nexttrace --source 204.98.134.56 9.9.9.9
```

#### `NextTrace` can also use `TCP` and `UDP` protocols to perform `Traceroute` requests

```bash
# TCP SYN Trace
nexttrace --tcp www.bing.com

# You can specify the port by yourself [here is 443], the default port is 80
nexttrace --tcp --port 443 2001:4860:4860::8888

# UDP Trace
nexttrace --udp 1.0.0.1

# You can specify the target port yourself [here it is 5353], the default is port 33494
nexttrace --udp --port 5353 1.0.0.1

# For TCP/UDP Trace, you can specify the source port; by default, a fixed random port is used
# (If you need to use a different random source port for each packet, please set the ENV variable NEXTTRACE_RANDOMPORT, or set the source port to -1)
nexttrace --tcp --source-port 14514 www.bing.com
```

#### `NextTrace` also supports a standalone DNS client mode

The full `nexttrace` flavor provides a q-compatible DNS client through a NextTrace-owned adapter over the public packages of [natesales/q v0.19.12](https://github.com/natesales/q/releases/tag/v0.19.12). `-l` / `--dns` must be the first argument; everything after it uses q-style flags and positional arguments.

```bash
# Query MX records through an explicit plain DNS server
nexttrace -l example.com MX @1.1.1.1

# Query A records over DNS-over-TLS
nexttrace --dns example.com A @tls://one.one.one.one

# Query over DNS-over-HTTPS and emit JSON
nexttrace --dns example.com A @https://cloudflare-dns.com/dns-query --format=json

# Show the dedicated DNS client help
nexttrace --dns --help
```

- Transports: UDP/TCP, DoT, DoH, DoQ, ODoH, and DNSCrypt; DNS Stamp server forms are supported for plain DNS, DoT, DoH, and DNSCrypt.
- Output formats: `pretty`, `column`, `raw`, `json`, and `yaml`.
- Query features include multiple servers and RR types, reverse lookup, DNSSEC/EDNS, NSID, PTR lookups for A/AAAA answers, and recursive AXFR.
- Configuration follows q conventions for `~/.qrc`, `Q_DEFAULT_SERVER`, `NO_COLOR`, and `SSLKEYLOGFILE`.
- This mode exists only in the full `nexttrace` flavor. `nexttrace-tiny` and `ntr` do not include or register it.
- It is a standalone CLI workflow: it does not replace the DNS resolver used by traceroute, GeoIP/RDNS, WebUI, MCP, or other service paths.

#### `NextTrace` also supports standalone path-MTU discovery mode

```bash
# Tracepath-style UDP PMTU discovery with live hop output
nexttrace --mtu 1.1.1.1

# Reuse the normal GeoIP / RDNS knobs in mtu mode
nexttrace --mtu --data-provider IPInfo --language en 1.1.1.1

# JSON output keeps the standalone mtu schema and now includes hop.geo
nexttrace --mtu --json 1.1.1.1
```

- `--mtu` is an independent UDP-only mode. It does not reuse the normal traceroute engine.
- TTY output updates the current hop in place and adds color for hop state / PMTU highlights; redirected / piped output falls back to finalized line-by-line streaming without ANSI.
- `--mtu --json` prints only the standalone MTU JSON document on stdout.
- GeoIP, RDNS, `--data-provider`, `--language`, `--no-rdns`, `--always-rdns`, and `--dot-server` all apply to this mode.

#### `NextTrace` also supports standalone CDN speed testing mode

```bash
# Apple CDN backend (default)
nexttrace --speed

# Cloudflare backend
nexttrace --speed --speed-provider cloudflare

# Dedicated speed help
nexttrace --speed --help

# Machine-readable output
nexttrace --speed --json --non-interactive --no-metadata

# Pin to a specific candidate IP, or bind a source address / device
nexttrace --speed --endpoint 1.2.3.4
nexttrace --speed --source 192.0.2.10
nexttrace --speed --dev eth0
```

- `--speed` is available only in the full `nexttrace` flavor. `nexttrace-tiny` and `ntr` do not register it.
- Main `nexttrace --help` only exposes the top-level `--speed` entry. Detailed speed flags live under `nexttrace --speed --help`.
- Backends: `apple` (default) and `cloudflare`.
- Reused common flags: `--json`, `--language`, `--no-color`, `--dot-server`, `--timeout`, `--source`, `--dev`.
- Speed-specific flags: `--speed-provider`, `--max`, `--threads`, `--latency-count`, `--non-interactive`, `--endpoint`, `--no-metadata`.
- Default terminal output includes candidate endpoints, the selected endpoint, client/server metadata, idle latency, download/upload single-thread and multi-thread rounds, loaded latency, total traffic, warnings, and degraded status.
- `--json` prints exactly one JSON document to stdout.
- Exit codes: `0` = success, `2` = degraded completion, `1` = failure, `130` = interrupted.

#### `NextTrace` can annotate IP literals in text streams

```bash
# Annotate a single line
nexttrace --nali 1.1.1.1

# Annotate pipeline output
dig example.com +short | nexttrace --nali --data-provider IPInfo --language en
```

- `--nali` is available only in the full `nexttrace` flavor. `nexttrace-tiny` and `ntr` do not register it.
- It only annotates IPv4/IPv6 literals and reuses NextTrace GeoIP providers. CDN/CNAME matching, offline databases, update logic, and nali-specific paths are not bundled.
- Reused common flags: `--data-provider`, `--language`, `--dot-server`, `--timeout`, `--dn42`, `-4`, and `-6`.
- This text annotation mode is inspired by [zu1k/nali](https://github.com/zu1k/nali), which is licensed under the [MIT License](https://github.com/zu1k/nali/blob/master/LICENSE).

#### `NextTrace` also supports some advanced functions, such as ttl control, concurrent probe packet count control, mode switching, etc.

```bash
# Display 2 latency samples per hop
nexttrace --queries 2 www.hkix.net

# Allow up to 10 probe packets per hop to collect those samples
# (NextTrace stops earlier if it has already got the replies requested by --queries)
nexttrace --max-attempts 10 www.hkix.net
# or use the ENV variable NEXTTRACE_MAXATTEMPTS to persist across runs
export NEXTTRACE_MAXATTEMPTS=10

# No concurrent probe packets, only one probe packet is sent at a time
nexttrace --parallel-requests 1 www.hkix.net

# Start Trace with TTL of 5, end at TTL of 10
nexttrace --first 5 --max-hops 10 www.decix.net
# In addition, an ENV is provided to set whether to mask the destination IP and omit its hostname
export NEXTTRACE_ENABLEHIDDENDSTIP=1

# Turn off the IP reverse parsing function
nexttrace --no-rdns www.bbix.net

# Set the probe packet size to 1024 bytes (inclusive IP + probe headers)
nexttrace --psize 1024 example.com

# Randomize each probe packet size up to 1500 bytes
nexttrace --psize -1500 example.com

# Set the TOS / traffic class field
nexttrace -Q 46 example.com

# Feature: print Route-Path diagram
# Route-Path diagram example:
# AS6453 Tata Communication「Singapore『Singapore』」
#  ╭╯
#  ╰AS9299 Philippine Long Distance Telephone Co.「Philippines『Metro Manila』」
#  ╭╯
#  ╰AS36776 Five9 Inc.「Philippines『Metro Manila』」
#  ╭╯
#  ╰AS37963 Aliyun「ALIDNS.COM『ALIDNS.COM』」
nexttrace --route-path www.time.com.my

# Disable color output
nexttrace --no-color 1.1.1.1
# or use ENV
export NO_COLOR=1
```

#### Advanced tuning quick guide

| Flag | What it controls | Default / starting point | When to change it |
| --- | --- | --- | --- |
| `--queries` | Samples per hop in normal traceroute; explicit probe count per hop in MTR | traceroute: `3`; MTR report: `10` when omitted; MTR TUI/raw: unlimited when omitted | Raise to `5-10` on unstable paths |
| `--max-attempts` | Hard cap on probe packets per hop | auto-sized from `--queries` | Raise on lossy links when replies arrive slowly |
| `--parallel-requests` | Total in-flight probes across TTLs | `18` | Use `1` on multipath/load-balanced paths; keep `6-18` on stable links |
| `--send-time` | Gap between packets inside one TTL group | `50ms` | Raise to `100-200ms` on rate-limited devices; ignored in MTR |
| `--ttl-time` | Gap between TTL groups in traceroute; per-hop interval in MTR | traceroute: `300ms`; MTR: `1000ms` when omitted | Lower to speed up; raise on remote/rate-limited paths |
| `--timeout` | Per-probe timeout | `1000ms` | Raise to `2000-3000ms` for intercontinental or high-loss paths |
| `--psize` | Probe packet size | Protocol/IP-family minimum | Inclusive IP + probe headers; negative values randomize each probe up to `abs(value)`; sizes above the egress/path MTU may fragment on wire |
| `-Q`, `--tos` | IP TOS / traffic class | `0` | Set DSCP/TOS style marking in the IP header; on Windows only `ICMPv6` with a non-zero value requires `WinDivert` |

These probe knobs are CLI-only today; `nt_config.yaml` does not yet store them. If you want reusable profiles, keep them in shell aliases or small wrapper scripts.

```bash
# Conservative profile for multipath or ECMP networks
nexttrace --parallel-requests 1 --send-time 100 --ttl-time 500 --timeout 2000 example.com

# Faster profile for stable single-path networks
nexttrace --parallel-requests 18 --send-time 20 --ttl-time 150 example.com

# Lossy long-haul profile
nexttrace --queries 5 --max-attempts 10 --timeout 2500 example.com
```

#### `NextTrace` supports MTR (My Traceroute) continuous probing mode

```bash
# MTR mode: continuous probing with ICMP (default), refreshes table in real-time
nexttrace -t 1.1.1.1
# or equivalently:
nexttrace --mtr 1.1.1.1

# MTR mode with TCP SYN probing
nexttrace -t --tcp --port 443 www.bing.com

# MTR mode with UDP probing
nexttrace -t --udp 1.0.0.1

# Set per-hop probe interval (default: 1000ms in MTR; -z/--send-time is ignored in MTR mode)
nexttrace -t -i 500 1.1.1.1

# Limit the max probes per hop (default: infinite in TUI, 10 in report mode)
nexttrace -t -q 20 1.1.1.1

# Report mode: probe each hop N times then print a final summary (like mtr -r)
nexttrace -r 1.1.1.1       # = --mtr --report, 10 probes per hop by default
nexttrace -r -q 5 1.1.1.1  # 5 probes per hop

# Wide report: no host column truncation (like mtr -rw)
nexttrace -w 1.1.1.1       # = --mtr --report --wide

# Show PTR and IP together (PTR first, IP in parentheses) in MTR output
nexttrace --mtr --show-ips 1.1.1.1
nexttrace -r --show-ips 1.1.1.1
nexttrace -w --show-ips 1.1.1.1

# MTR raw stream mode (machine-friendly, one event per line)
nexttrace --mtr --raw 1.1.1.1
nexttrace -r --raw 1.1.1.1

# Combine with other options
nexttrace -t --tcp --max-hops 20 --first 3 --no-rdns 8.8.8.8
```

When running in a terminal (TTY), MTR mode uses an **interactive full-screen TUI**:

- **`q` / `Q`** — quit (restores terminal, no output left behind)
- **`p`** — pause probing
- **`SPACE`** — resume probing
- **`r`** — reset statistics (counters are cleared, display mode is preserved)
- **`y`** — cycle host display mode: ASN → City → Owner → Full
- **`n`** — toggle host name display:
  - default: PTR (or IP fallback) ↔ IP only
  - with `--show-ips`: PTR (IP) ↔ IP only
- **`e`** — toggle MPLS label display on/off
- **`d` / `D`** — toggle the optional history display; the default TUI remains the classic metric table
- **`g` / `G`** — in history display only, cycle History chart mode: heatmap → bars → sparkline
- The TUI header displays **source → destination**, with `--source`/`--dev` information when specified.
- When using NextTrace API and preferred API metadata is available, the preferred API IP address is shown in the header.
- Uses the **alternate screen buffer**, so your previous terminal history is preserved on exit.
- When stdin is not a TTY (e.g. piped), it falls back to a simple table refresh.

History display keeps a rolling 3-minute, timestamp-based probe history while the classic table is shown, then renders `Host`, `Last`, `Avg`, `Loss`, and `History` when toggled with `d`. The History column uses a fixed 100ms latency scale. Unicode blocks/sparklines are used by default; with `--no-color`, plain ASCII is used and timeouts are shown as `x`.

Acknowledgement: the optional MTR history display is inspired by [TraceBar](https://github.com/tracebar-app/tracebar), a macOS continuous traceroute monitor licensed under the [MIT License](https://github.com/tracebar-app/tracebar/blob/main/LICENSE).

The **report mode** (`-r`/`--report`) produces a one-shot summary after all probes complete, suitable for scripting:

```text
Start: 2025-07-14T09:12:00+08:00
HOST: myhost                    Loss%   Snt   Last    Avg   Best   Wrst  StDev
  1. one.one.one.one            0.0%    10    1.23   1.45   0.98   2.10   0.32
  2. 10.0.0.2                 100.0%    10    0.00   0.00   0.00   0.00   0.00
```

Rows shown as `(waiting for reply)` keep the same table layout; the metric cells on that row are left blank.

In non-wide report mode, NextTrace intentionally keeps the host column compact:

- only `PTR/IP` is shown
- no Geo API lookup is performed
- no ASN / owner / location fields are shown
- MPLS labels are hidden

Wide report mode (`-w` / `--wide`) keeps the current full-information behavior, including Geo-derived fields and MPLS output.

When `--raw` is used together with MTR (`--mtr`, `-r`, or `-w`), NextTrace enters **MTR raw stream mode**.

If the active data provider is `NextTrace-API` and preferred API metadata is available, NextTrace first prints one uncolored API info preamble line:

```text
[NextTrace API] preferred API IP - [2403:18c0:1001:462:dd:38ff:fe48:e0c5] - 21.33ms - DMIT.NRT
```

After that, it prints one `|`-delimited event per line:

```
4|84.17.33.106|po66-3518.cr01.nrt04.jp.misaka.io|0.27|60068|Japan|Tokyo|Tokyo||cdn77.com|35.6804|139.7690
```

Field order:

`ttl|ip|ptr|rtt|asn|country|prov|city|district|owner|lat|lng`

Timeout rows keep the same 12-column layout:

`ttl|*||||||||||`

The raw stdout contract remains exactly 12 columns. An unreachable edge in unbounded MTR is provisional: later transit evidence can reopen higher hops, and a new unreachable edge may therefore produce another stderr diagnostic. For bounded runs, the final structured `path_end` is authoritative. Structured Web/API/MCP records expose per-probe `response` and the final `path_end` instead of inferring the edge from responder-IP equality.

In MTR mode (`--mtr`, `-r`, `-w`, including `--raw`), `-i/--ttl-time` sets the **per-hop probe interval**: how long to wait between successive probes to the same hop (default: 1000ms when omitted). `-z/--send-time` is ignored in MTR mode.

> Note: `--show-ips` only takes effect in MTR mode (`--mtr`, `-r`, `-w`); otherwise it is ignored.
>
> Note: `--mtr` cannot be used together with `--table`, `--classic`, `--json`, `--output`, `--output-default`, `--route-path`, `--from`, `--fast-trace`, `--file`, or `--deploy`.

#### `NextTrace` supports users to select their own IP API (currently supports: `NextTrace-API`, `IP.SB`, `IPInfo`, `IPInsight`, `IPAPI.com`, `IPInfoLocal`, `IPDB.One`, `CHUNZHEN`)

##### LeoMoeAPI name migration

`LeoMoeAPI` is the retired name of the project's official API. The current name is **NextTrace API**, and its machine-readable `data_provider` value is `NextTrace-API`. The former `LeoMoeAPI` and `LeoMoe` values remain accepted as silent, case-insensitive compatibility aliases for existing scripts, but NextTrace always reports the canonical value. The WebSocket/PoW implementation is called **NextTrace API v3**, while the token-authenticated HTTP implementation is called **NextTrace API v4**.

```bash
# You can specify the IP database by yourself [IP-API.com here]; NextTrace API is used by default
nexttrace --data-provider ip-api.com
## Note There are frequency limits for free queries of the ipinfo and IPInsight APIs. You can purchase services from these providers to remove the limits
##      If necessary, you can clone this project, add the token provided by ipinfo or IPInsight and compile it yourself
##      Fill the token to: ipgeo/tokens.go

## Note For the offline database IPInfoLocal, please download it manually and rename it to ipinfoLocal.mmdb. (You can download it from here: https://ipinfo.io/signup?ref=free-database-downloads)
##      Current directory, nexttrace binary directory and FHS directories (Unix-like) will be searched.
##      To customize it, please use environment variables,
export NEXTTRACE_IPINFOLOCALPATH=/xxx/yyy.mmdb
## Please be aware: Due to the serious abuse of IP.SB, you will often be not able to query IP data from this source
## IP-API.com has a stricter restiction on API calls, if you can't query IP data from this source, please try again in a few minutes

# The Pure-FTPd IP database defaults to using http://127.0.0.1:2060 as the query interface. To customize it, please use environment variables
export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060
## You can use https://github.com/freshcn/qqwry to build your own Pure-FTPd IP database service

# You can also specify the default IP database by setting an environment variable
export NEXTTRACE_DATAPROVIDER=ipinfo
```

NextTrace API v3 WebSocket/PoW remains the default when no NextTrace API v4 token is available. To use the NextTrace API v4 HTTP GeoIP endpoint for the current shell session, run the setup command and paste your token:

```bash
# Token page:
# GET https://api.nxtrace.org/v4/api-tokens

nexttrace -x
```

`nexttrace -x` stores the token in temporary files: one scoped to the parent process ID, which is normally your current shell, and one same-user fallback file for wrapper commands such as `go run`. Later `nexttrace` commands first read the real `NEXTTRACE_API_V4_TOKEN`, then the parent-PID file, then the fallback file, and load the value into the process-local environment. The command does not write shell profiles, permanent environment variables, or `nt_config.yaml`.

With `NEXTTRACE_API_V4_TOKEN` set and the active provider still `NextTrace-API`, NextTrace queries `GET https://api.nxtrace.org/v4/ipGeo?ip=` with `X-NextTrace-Token: <token>`. The request has no JSON body. Successful responses are direct GeoIP JSON mapped to the normal output fields; quota metadata is exposed only in headers (`X-NextTrace-Quota-Remaining`, `X-NextTrace-Quota-Expires-At`, `X-NextTrace-Quota-Cost`, `X-NextTrace-Quota-Source`) and does not change the default output format. Error responses prefer `{"error":{"message":"..."}}`; known statuses include `400` for empty/illegal IP, `401` unauthorized, `429` quota exhausted, and `500` internal server error. NextTrace API v4 token failures do not fall back to NextTrace API v3.

#### `NextTrace` supports mixed parameters and shortened parameters

```bash
Example:
nexttrace --data-provider IPAPI.com --max-hops 20 --tcp --port 443 --queries 5 --no-rdns 1.1.1.1
nexttrace -tcp --queries 2 --parallel-requests 1 --table --route-path 2001:4860:4860::8888

Equivalent to:
nexttrace -d ip-api.com -m 20 -T -p 443 -q 5 -n 1.1.1.1
nexttrace -T -q 2 --parallel-requests 1 --table -P 2001:4860:4860::8888
```

### Globalping

[Globalping](https://globalping.io/) provides access to thousands of community-hosted probes to run network tests and measurements.

Run traceroute from a specified location by using the `--from` flag. The location field accepts continents, countries, regions, cities, ASNs, ISPs, or cloud regions.

```bash
nexttrace google.com --from Germany
nexttrace google.com --from comcast+california
```

A limit of 250 tests per hour is set for all anonymous users. To double the limit to 500 per hour please set the `GLOBALPING_TOKEN` environment variable with your token.

```bash
export GLOBALPING_TOKEN=your_token_here
```

### IP Database

We use [bgp.tools](https://bgp.tools) as a data provider for routing tables.

NextTrace BackEnd is now open-source.

https://github.com/sjlleo/nexttrace-backend

NextTrace API v3 utilizes the Proof of Work (PoW) mechanism to prevent abuse, with NextTrace using the powclient library as its client component. Both the PoW client and server are open source. Please direct PoW-related questions to their respective repositories.

- [GitHub - tsosunchia/powclient: Proof of Work CLIENT for NextTrace](https://github.com/tsosunchia/powclient)
- [GitHub - tsosunchia/powserver: Proof of Work SERVER for NextTrace](https://github.com/tsosunchia/powserver)

All NextTrace IP geolocation `API DEMO` can refer to [here](https://github.com/nxtrace/NTrace-core/blob/main/ipgeo/)

### Environment Variables

NextTrace currently reads the following environment variables. For `NEXTTRACE_*` boolean switches, only `1` and `0` are recognized; other values fall back to the built-in default. For consistency, restart NextTrace after changing them.

#### Core Runtime / Network

| Variable | Default | Description |
| --- | --- | --- |
| `NEXTTRACE_DEVMODE` | `0` | Turn fatal errors into panics with stack traces for debugging. |
| `NEXTTRACE_DEBUG` | unset | Print detected environment values while `GetEnv*` helpers parse them. |
| `NEXTTRACE_DISABLEMPLS` | `0` | Disable MPLS display globally, similar to `--disable-mpls`. |
| `NEXTTRACE_ENABLEHIDDENDSTIP` | `0` | Mask the destination IP and omit its hostname in output. |
| `NEXTTRACE_RANDOMPORT` | `0` | Use a different random source port for each TCP/UDP probe. |
| `NEXTTRACE_MAXATTEMPTS` | auto | Provide a default `--max-attempts` value when the CLI flag is not set. |
| `NEXTTRACE_ICMPMODE` | `0` | Provide a default `--icmp-mode` value (`0=auto`, `1=socket`, `2=WinDivert` on Windows). |
| `NEXTTRACE_UNINTERRUPTED` | `0` | When used together with `--raw`, rerun traceroute continuously instead of stopping after one round. |
| `NEXTTRACE_PROXY` | unset | Outbound proxy URL for HTTP / WebSocket requests used by PoW, Geo APIs, tracemap, etc. |
| `NEXTTRACE_DATAPROVIDER` | unset | Override the default IP geolocation provider (for example `ipinfo`). |

#### Service / Web / Backend

| Variable | Default | Description |
| --- | --- | --- |
| `NEXTTRACE_HOSTPORT` | `api.nxtrace.org` | Override the backend host or `host:port` used by NextTrace API v3, tracemap, and FastIP flows. |
| `NEXTTRACE_TOKEN` | unset | Pre-supplied NextTrace API v3 bearer token; when present, token fetching via PoW is skipped. |
| `NEXTTRACE_API_V4_TOKEN` | unset | NextTrace API v4 HTTP GeoIP token. When unset, NextTrace also checks the temporary token files written by `nexttrace -x`; if neither exists, NextTrace API v3 WebSocket/PoW remains active. |
| `NEXTTRACE_POWPROVIDER` | `api.nxtrace.org` | Select the PoW provider for NextTrace API v3. The built-in non-default alias is `sakura`. |
| `NEXTTRACE_DEPLOY_ADDR` | unset | Default listen address for `--deploy` when `--listen` is not provided. |
| `NEXTTRACE_DEPLOY_TOKEN` | unset | Token for `--deploy` WebUI/API/WebSocket/MCP access. CLI `--deploy-token` takes precedence. |
| `NEXTTRACE_ALLOW_CROSS_ORIGIN` | `0` | Only for `--deploy`: allow cross-origin browser access to the Web UI / API. Disabled by default for safety. |

#### IP Database / Third-Party Providers

| Variable | Default | Description |
| --- | --- | --- |
| `NEXTTRACE_IPINFOLOCALPATH` | auto search | Full path to `ipinfoLocal.mmdb` for the `IPInfoLocal` provider. |
| `NEXTTRACE_CHUNZHENURL` | `http://127.0.0.1:2060` | Base URL of the Chunzhen lookup service. |
| `NEXTTRACE_IPINFO_TOKEN` | unset | Token for the `IPInfo` provider. |
| `NEXTTRACE_IPINSIGHT_TOKEN` | unset | Token for the `IPInsight` provider. |
| `NEXTTRACE_IPAPI_BASE` | provider built-in URL | Override the base URL used by compatible IP API clients in the current implementation (`IPInfo`, `IPInsight`, `ip-api.com`). |
| `IPDBONE_BASE_URL` | `https://api.ipdb.one` | Override the IPDB.One API base URL. |
| `IPDBONE_API_ID` | unset | IPDB.One API ID. |
| `IPDBONE_API_KEY` | unset | IPDB.One API key. |
| `GLOBALPING_TOKEN` | unset | Authentication token for Globalping; raises the anonymous hourly limit when provided. |

#### Standalone DNS Client (full flavor only)

These q-compatible variables apply only to the standalone DNS client mode.

| Variable | Default | Description |
| --- | --- | --- |
| `Q_DEFAULT_SERVER` | unset | Default DNS server when neither the command line nor `~/.qrc` selects one. |
| `NO_COLOR` | unset | Disable color in DNS client output when set to any non-empty value. |
| `SSLKEYLOGFILE` | unset | Write TLS session secrets to this file when `--tls-key-log-file` is not set. The file contains sensitive key material. |

#### Config Discovery

| Variable | Default | Description |
| --- | --- | --- |
| `XDG_CONFIG_HOME` | OS / shell default | If set, NextTrace also searches `$XDG_CONFIG_HOME/nexttrace` for `nt_config.yaml`. |

### For full usage list, please refer to the usage menu

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Project screenshot





## OpenTrace

`OpenTrace` is the cross-platform `GUI` version of `NextTrace` developed by @Archeb, bringing a familiar but more powerful user experience.

This software is still in the early stages of development and may have many flaws and errors. We value your feedback.

[https://github.com/Archeb/opentrace](https://github.com/Archeb/opentrace)

## GlobalTrace

`GlobalTrace` is an open-source `Globalping x NextTrace` web traceroute project. It uses Globalping's worldwide probe network to run `MTR` measurements from multiple regions, then enriches hop IPs with the NextTrace / NTrace backbone IP database for GeoIP, ASN, and network ownership details.

Website: [https://lg.nxtrace.org](https://lg.nxtrace.org)

Project: [nxtrace/GlobalTrace](https://github.com/nxtrace/GlobalTrace)

## NextTrace Web

`NextTrace Web` is a web-based server implementation of `NextTrace` in the `MTR` style, offering various deployment options including `Docker`.

[https://github.com/nxtrace/nexttraceweb](https://github.com/nxtrace/nexttraceweb)

## Deploy WebUI and MCP

The full `nexttrace` binary can expose the local WebUI/API/WebSocket server:

```bash
nexttrace --deploy
```

MCP is a deploy submode and is exposed over the same network stack at `/mcp`:

```bash
nexttrace --deploy --mcp
nexttrace --deploy --mcp --listen 0.0.0.0:1080 --deploy-token "$TOKEN"
```

Loopback listen addresses (`127.0.0.1`, `::1`, `localhost`) are tokenless by default. External listen addresses require a token; if none is set with `--deploy-token` or `NEXTTRACE_DEPLOY_TOKEN`, NextTrace generates one and prints it to stdout. API, WebSocket, and MCP clients may use `Authorization: Bearer <token>` or `X-NextTrace-Token`; browser WebUI users can sign in at `/auth/login`.

### Register MCP in Agent clients

Start NextTrace first. The MCP endpoint is Streamable HTTP, not stdio:

```text
http://127.0.0.1:1080/mcp
```

For external listeners or manually configured tokens, pass the token in an HTTP header. Do not put deploy tokens in URL query strings.

Generic MCP client config:

```json
{
  "mcp": {
    "servers": {
      "nexttrace": {
        "url": "http://127.0.0.1:1080/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}
```

OpenClaw can save the same server definition with [`openclaw mcp set`](https://docs.openclaw.ai/cli/mcp):

```bash
openclaw mcp set nexttrace '{
  "url": "http://127.0.0.1:1080/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer <token>"
  }
}'
```

`openclaw mcp set` only saves the MCP server definition. It does not start NextTrace or verify that the endpoint is reachable, so run `nexttrace --deploy --mcp` first.

Useful first tool calls for Agents:

- `nexttrace_capabilities`
- `nexttrace_traceroute`
- `nexttrace_globalping_trace`
- `nexttrace_globalping_limits`

## NextTraceroute

`NextTraceroute` is a root-free Android route tracing application that defaults to using the `NextTrace API`, developed by @surfaceocean.  
Thank you to all the test users for your enthusiastic support. This app has successfully passed the closed testing phase and is now officially available on the Google Play Store.

[https://github.com/nxtrace/NextTraceroute](https://github.com/nxtrace/NextTraceroute)  
[](https://play.google.com/store/apps/details?id=com.surfaceocean.nexttraceroute&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1)

## NextTrace API Credits

NextTrace focuses on Golang traceroute implementations, and its NextTrace API geolocation information is not supported by raw data, so a commercial version is not possible.

The NextTrace API data is subject to copyright restrictions from multiple data sources and is only used to display traceroute geolocation.

1. We would like to credit samleong123 for providing nodes in Malaysia, TOHUNET Looking Glass for global nodes, and Ping.sx from Misaka, where more than 80% of reliable calibration data comes from ping/mtr reports.

2. At the same time, we would like to credit isyekong for their contribution to rDNS-based calibration ideas and data. NextTrace API is accelerating the development of rDNS resolution and has already achieved automated geolocation resolution for some backbone networks, though some results remain inaccurate. We hope that NextTrace will become a One-Man ISP-friendly traceroute tool in the future, and we are working on improving the calibration of these ASN micro-backbones as much as possible.

3. In terms of development, I would like to credit missuo and zhshch for their help with Go cross-compilation, design concepts and TCP/UDP Traceroute refactoring, and tsosunchia for their support on TraceMap.

4. I would also like to credit FFEE_CO, TheresaQWQ, stydxm and others for their help. NextTrace API has received a lot of support since its first release, so I would like to credit them all!

We hope you can give us as much feedback as possible on IP geolocation errors (see issue) so that it can be calibrated in the first place and others can benefit from it.

## Cloudflare Support

This project is sponsored by [Project Alexandria](http://www.cloudflare.com/oss-credits).



## AIWEN TECH Support

This project is sponsored by [AIWEN TECH](https://www.ipplus360.com). We’re pleased to enhance the accuracy and completeness of this project’s GEOIP lookups using `AIWEN TECH City-Level IP Database`, and to make it freely available to the public.



## JetBrain Support

This Project uses [JetBrain Open-Source Project License](https://jb.gg/OpenSourceSupport). We Proudly Develop By `Goland`.



## Credits

[Gubo](https://www.gubo.org) Reliable Host Recommendation Website

[IPInfo](https://ipinfo.io) Provided most of the data support for this project free of charge

[BGP.TOOLS](https://bgp.tools) Provided some data support for this project free of charge

[PeeringDB](https://www.peeringdb.com) Provided some data support for this project free of charge

[Globalping](https://globalping.io) An open-source and free project that provides global access to run network tests like traceroute

[sjlleo](https://github.com/sjlleo) The perpetual leader, founder, and core contributors

[tsosunchia](https://github.com/tsosunchia) The project chair, infra maintainer, and core contributors

[Yunlq](https://github.com/Yunlq) An active community contributor

[Vincent Young](https://github.com/missuo)

[zhshch2002](https://github.com/zhshch2002)

[Sam Sam](https://github.com/samleong123)

[waiting4new](https://github.com/waiting4new)

[FFEE_CO](https://github.com/fkx4-p)

[bobo liu](https://github.com/fakeboboliu)

[YekongTAT](https://github.com/isyekong)

### Others

- Although other third-party APIs are integrated in this project, please refer to the official website of the third-party APIs for specific TOS and AUP. If you encounter IP data errors, please contact them directly to correct them.

- For feedback related to corrections about IP information, we currently have two channels available:

  > - [IP 错误报告汇总帖](https://github.com/orgs/nxtrace/discussions/222) in the GITHUB ISSUES section of this project (Recommended)
  > - This project's dedicated correction email: `correct#nxtrace.org` (Please note that this email is only for correcting IP-related information. For other feedback, please submit an ISSUE)

- How to obtain the freshly baked binary executable of the latest commit?

  > Please go to the most recent [Build & Release](https://github.com/nxtrace/NTrace-dev/actions/workflows/build.yml) workflow in GitHub Actions.

- Common questions
  - On Windows, ICMP mode requires manual firewall allowance for ICMP/ICMPv6
  - On macOS, only ICMP mode does not require elevated privileges
  - In some cases, running multiple instances of NextTrace simultaneously may interfere with each other’s results (observed so far only in TCP mode)

## Star History

[](https://star-history.dera.page/#nxtrace/NTrace-core&type=Date)

## 2. In-Tree Documentation Chapters (nxtrace/NTrace-core)

# DNS client architecture（q v0.19.12）

## 边界

- 仅 full `nexttrace` 编译 `internal/dnsclient`；入口固定为首参数 `-l`/`--dns`。
- DNS 模式是独占终端模式，不进入 Web、MCP、`internal/service`，不替换现有 resolver。
- 直接依赖 `github.com/natesales/q v0.19.12` 的公开 `cli`、`transport`、`output`、`util`、`util/tls` 子包。
- 没有修改上游、fork、`replace`、vendor、`go:linkname` 或 companion executable，也没有复制 q root 源文件。

## 本地编排对应关系

代码行数快照：2026-07-27，adapter code commit `610d71e`，基于 `origin/main` `0bcc549`。

| q root 职责 | NextTrace adapter | 生产代码行数 |
| --- | --- | ---: |
| qrc/env、flags、位置参数、RR type、IDNA、reverse/CHAOS | `config.go` | 388 |
| DNS header、EDNS、DNSSEC、NSID、ECS、padding、cookie | `query.go` | 138 |
| DNS Stamp、server URL、协议、默认端口 | `server.go` | 291 |
| TLS 配置及 UDP/TCP/DoT/DoH/DoQ/ODoH/DNSCrypt factory | `transport.go` | 369 |
| 多服务器、timeout、ID check、PTR、输出调度 | `runner.go` + `output.go` | 645 |
| recursive AXFR | `xfr.go` | 253 |
| flavor/CLI 接线 | `cmd/dns_mode*.go` | 98 |
| **合计** |  | **2,182** |

q v0.19.12 的 `main.go`、`resolver.go`、`xfr.go` 合计 1,001 行。本 adapter 为避免 q root 的全局状态、超时竞态、路径穿越和可预判 fatal 路径，额外维护 1,181 行。

## 依赖与体积

测量快照：2026-07-27，Darwin/arm64，`go build -trimpath -ldflags '-s -w'`；adapter code commit `610d71e` 对比 `origin/main` `0bcc549`。

| flavor | 基线 bytes | 集成后 bytes | 增量 | 增幅 |
| --- | ---: | ---: | ---: | ---: |
| nexttrace | 26,999,186 | 30,359,186 | 3,360,000（3.204 MiB） | 12.44% |
| nexttrace-tiny | 11,050,210 | 11,083,234 | 33,024（0.031 MiB） | 0.30% |
| ntr | 11,050,210 | 11,083,234 | 33,024（0.031 MiB） | 0.30% |

- 按 `go list -deps .` 口径，full 编译依赖包数从 425 增至 483（+58）；链接 q 的 5 个公开包。
- tiny/ntr 编译依赖包数从 301 变为 300，`go list -deps` 与 `go version -m` 均无 `github.com/natesales/q`。其 33,024 bytes 变化来自 Go module 的全局版本选择，不是链接 q。
- 完整 Go module graph 从 105 增至 193（+88，包含上游测试/工具依赖，不等同于链接包）。
- 许可证审计以锁定版本的根 `LICENSE`/`NOTICE`，以及 Darwin/arm64、Linux/amd64、Windows/amd64 full 二进制的 `go version -m` 基线差分为准。新增实际链接模块如下；锁定版本见 `go.mod`/`go.sum`。

| 许可证 | 新增实际链接模块 |
| --- | --- |
| Unlicense | `github.com/AdguardTeam/golibs`、`github.com/ameshkov/dnscrypt/v2`、`github.com/ameshkov/dnsstamps` |
| MIT | `github.com/aymanbagabas/go-osc52/v2`、`github.com/charmbracelet/colorprofile`、`github.com/charmbracelet/lipgloss`、`github.com/charmbracelet/log`、`github.com/charmbracelet/x/ansi`、`github.com/charmbracelet/x/cellbuf`、`github.com/charmbracelet/x/term`、`github.com/clipperhouse/displaywidth`、`github.com/go-logfmt/logfmt`、`github.com/jedisct1/go-dnsstamps`、`github.com/json-iterator/go`、`github.com/lucasb-eyer/go-colorful`、`github.com/muesli/termenv`、`github.com/rivo/uniseg`、`github.com/sthorne/odoh-go`、`github.com/xo/terminfo` |
| BSD-2-Clause | `github.com/cisco/go-hpke`、`github.com/cisco/go-tls-syntax` |
| BSD-3-Clause | `github.com/cloudflare/circl`、`github.com/jessevdk/go-flags`、`github.com/miekg/dns`、`golang.org/x/exp` |
| Apache-2.0 | `github.com/modern-go/concurrent`、`github.com/modern-go/reflect2` |
| GPL-3.0 | `github.com/natesales/bgptools-go`、`github.com/natesales/q` |
| MIT AND Apache-2.0 | `gopkg.in/yaml.v3`（文件级双许可） |

- q 根许可证为 GPL-3.0；其 `transport` 目录另保留 Apache-2.0 与 MIT 派生代码告知，不表示 q 整体可在三者间任选。`github.com/clipperhouse/uax29/v2` 与 `google.golang.org/protobuf` 仅版本升级，许可证仍分别为 MIT、BSD-3-Clause。新增但只用于测试/工具链的 `golang.org/x/mod`、`golang.org/x/tools` 均为 BSD-3-Clause，不链接进发布二进制。

## 已验证语义

- q `cli.Flags` 的字段名、字段类型和完整 struct tags 有 v0.19.12 反射快照；description 中的 default-true 语义也受门禁保护。
- qrc、`Q_DEFAULT_SERVER`、`NO_COLOR`、`SSLKEYLOGFILE`、shell completion、位置参数、默认 RR types、IDNA、reverse、CHAOS。
- 非 help go-flags 解析错误保留 q 的两行 stderr（裸 parser error 与终止错误）；差分语料覆盖 unknown option 和 missing value。
- DNS header、DNSSEC/EDNS、NSID、ECS、padding、cookie、TCP fallback、TXT concat、TTL rounding、PTR cache、recursive AXFR 及取消后的连接关闭/drain。
- 本地 UDP、TCP、DoT、DoH、DoQ、ODoH、DNSCrypt 服务；各 transport 的参数映射有字段断言。
- pretty、column、raw、JSON、YAML 与官方 q v0.19.12 同语料的 stdout/stderr/退出码差分；语料还覆盖 verbose/trace、qrc/env、completion、多服务器、DNS Stamp、全部 transport、HTTP header、TLS key log、numeric RR、userinfo、parser error 和 recursive AXFR。
- q logger、颜色、默认 resolver、HTTP default transport 的作用域恢复有回归测试。
- q output 与 DNSCrypt 残留 `log.Fatal` 通过子进程测试；adapter 自有 version/AXFR 写入错误返回普通 error。

## 验证状态

- `go test ./...`、`go test -tags flavor_tiny ./...`、`go test -tags flavor_ntr ./...`、`go vet ./...`、Node Web 13 项测试通过。
- `go test -race ./internal/dnsclient ./cmd` 通过。全仓 race 仅在未修改的 `wshandle` 发现数据竞争；同一竞争已在 `origin/main` 快照复现，因此不归因于本次集成，也未越界修复。
- 官方 q v0.19.12 差分语料全部通过。
- 发布矩阵共 32 个目标、3 个 flavor：31 个本机可用目标的 93 次构建通过；62 个 tiny/ntr 产物均不含 q，31 个 full 产物均含 q v0.19.12；12 个选定 Linux 产物的 UPX 压缩通过。
- Android arm64 的 3 个 `CGO_ENABLED=1` 构建因本机缺 NDK r26d clang 未执行成功；补充 `CGO_ENABLED=0` 三 flavor 均通过，正式 PR 仍须由 CI 完成 NDK 验证。

## 与 q root 的已知语义差异

- recursive AXFR 使用 CLI 的 `--timeout` 配置 `dns.Transfer`；q root 未设置该字段，实际使用 miekg/dns 默认 2 秒。
- `--resolve-ips` 收到 `CNAME → PTR` answer 时，adapter 扫描 PTR，并按唯一 IP 查询一次；q root 强制把首条 answer 转为 PTR，可能 panic，且会重复查询相同地址。adapter 保留安全行为。
- 多 RR type/default RR type 的集合一致；adapter 固定参数顺序，q root 使用 map range，输出顺序本身不稳定。
- `--version` 标识锁定的 q 版本及 `NextTrace adapter`，不冒充官方 q release build metadata。
- 可预判的 plus flag、TLS、URL、HTTP header、DNSCrypt、AXFR 错误会返回普通 error，不复刻 q root 的 `log.Fatal`；差分测试按消息语义规范化 fatal 前缀、耗时和平台网络错误。无效 HTTP header 会在建连前失败，q root 会交给 net/http 在发送时拒绝。
- `--qid` 只接受 `-1` 或 `0..65535`；q root 会把其他整数静默截断为 `uint16`。ODoH target 会先解析 DNS Stamp 并接受解析结果为 HTTPS 的 DoH Stamp；q root 的字面 `https://` 检查会拒绝该组合。
- q v0.19.12 的 plus flag helper 会跳过 `+aa`、`+ad`、`+cd`、`+ra`、`+rd`、`+t`、`+z`；adapter 按 `cli.Flags` 的公开 long tag 正确处理这些短名称，未定义的 `+tc` 仍报错。
- adapter 将大小写不敏感的精确位置参数 `CH` 仅作为 CHAOS class marker，并继续解析后续 qname；q root 在 qname 为空时还会错误地把 `CH` 设为查询名。
- adapter 按完整 question 与全部 OPT option 计算 EDNS padding，并按服务器数、RR query 数及实际 A/AAAA PTR follow-up 数配置整体 watchdog；q root 分别按空 header 计算 padding、只按服务器数计算整体 timeout。
- adapter 正确区分 bare 数值 IPv6 scope 与 RFC 6874 `%25` zone、避免把 escaped userinfo 误判为 zone，并保留 DoH scoped IPv6 URL 的单层 `%25` 编码；同时以 `0600` 创建 TLS key log、验证 AXFR 文件组件与 root containment，并修正 q root 的 scoped IPv6 debug 格式。差分测试仅对锁定版本的该条错误 debug 行做窄归一化。

## 剩余架构风险

- q transport 没有统一 context API。adapter 的整体超时覆盖查询、PTR/Whois 后处理和输出；超时后 CLI 会返回并退出，但 TLS/HTTP/QUIC/ODoH/DNSCrypt 的底层操作只能在后台继续到自身返回，QUIC 明确使用 `context.Background()`。后台期间会继续持有 DNS 独占锁及相关全局状态；后续 `Run` 可通过自身 context 取消等待，但使用 `context.Background()` 时仍会等待底层返回。
- DNSCrypt 在 Dial/证书获取失败时仍调用 `log.Fatal`，无法由 adapter 转换为 error。q output 的写入/序列化失败也会 `log.Fatal`。
- q HTTP transport 会修改 `http.DefaultTransport`。adapter 已串行化首次 Exchange、使用 clone 并恢复全局值，但安全性依赖 DNS 模式独占运行。
- 为保持 q v0.19.12 行为，plain/DoT/DoH DNS Stamp 仍按 q root 只使用 provider/path 组装 URL；stamp 的 server address/certificate hash 没有下沉到公开 transport。DNSCrypt stamp 会完整透传。
- `qutil.UseColor`、默认 charm logger、`net.DefaultResolver` 已在调用作用域内保存/恢复；JSON naming strategy 仍是 q output 的进程级全局写入，无法从公开 API 恢复。
- recursive AXFR 取消会主动关闭并 drain transfer；TLS/HTTP/QUIC/ODoH/DNSCrypt 仍无法提供严格的底层即时取消。
- recursive AXFR 会拒绝非便携 label 并做词法 containment；它假设当前目录不受恶意本地进程并发修改，不防御本地 symlink TOCTOU。
- 超时会禁止后续 stdout/stderr 写入，但若调用方提供的 writer 已在一次写入中永久阻塞，禁用操作本身也会等待；正常终端/文件路径未发现该问题。
- 2,182 行本地编排高于 q root 1,001 行，升级时存在明显的双实现漂移成本。

## 升级协议

每次更新 q 版本必须：

1. 先审查 q 的 `main.go`、`resolver.go`、`xfr.go`。
2. 审查 `cli`、`output`、`transport`、`util`、`util/tls` 的 API 和行为差异。
3. 更新 flags 快照；任何快照变化都需人工确认映射。
4. 构建对应版本官方 q，执行本地差分语料和 fatal 子进程测试。
5. 重跑三 flavor 的 `go list -deps`、`go version -m`、体积与发布矩阵。

## Phase 2 acceptance

DNSCrypt/ODoH 隔离 smoke 已完成。2026-07-27 已人工确认接受初始 1,892 行本地编排、full +3.189 MiB、上述语义差异，以及不可拦截 fatal/非统一取消风险，允许进入正式 PR review；review 修复后为 2,182 行、full +3.204 MiB。该确认不授权 Phase 3 resolver 替换。

--- METRICS ---
- Files Extracted: 2
- Estimated Token Budget: ~13833 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/nxtrace/NTrace-core