### Deploy and Query Web API Server

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Start the built-in web server for browser UI and REST API access, and interact with the API endpoints to retrieve configuration and trace results.

```bash
nexttrace --deploy --listen 0.0.0.0:8080
export NEXTTRACE_ALLOW_CROSS_ORIGIN=1
nexttrace --deploy
curl http://localhost:1080/api/options
```

--------------------------------

### Windows Package Manager Installation

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Installation commands for Windows using WinGet and Scoop package managers.

```powershell
winget install nexttrace
```

```powershell
scoop bucket add extras && scoop install extras/nexttrace
```

--------------------------------

### Cross-Compile NextTrace

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Example of cross-compiling the tiny flavor for Linux arm64 architecture.

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

--------------------------------

### Automated Linux Installation

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Various methods to install NextTrace on Linux distributions using shell commands, including APT, AUR, and package managers like x-cmd and opkg.

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

```shell
curl -fsSL https://github.com/nxtrace/nexttrace-debs/releases/latest/download/nexttrace-archive-keyring.gpg | sudo tee /etc/apt/keyrings/nexttrace.gpg >/dev/null
echo "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
```

```shell
yay -S nexttrace-bin
```

```shell
yay -S nexttrace
```

```shell
apt install nexttrace
```

```shell
x env use nexttrace
```

```shell
pkg install root-repo
pkg install nexttrace
```

```shell
opkg install nexttrace
```

--------------------------------

### Configure NextTrace Probe Profiles

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Examples of using CLI flags to adjust probe behavior for specific network conditions like multipath, high-speed, or lossy connections. These settings are currently CLI-only and should be managed via shell aliases.

```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
```

--------------------------------

### macOS Homebrew Installation

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Installation commands for macOS using Homebrew, providing both the core version and the frequently updated version from the repository.

```shell
brew install nexttrace
```

```shell
brew tap nxtrace/nexttrace && brew install nxtrace/nexttrace/nexttrace
```

--------------------------------

### GET /api/options

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Retrieves the available configuration options, supported protocols, and data providers for the traceroute engine.

```APIDOC
## GET /api/options

### Description
Fetches the configuration schema, including supported protocols, available geolocation data providers, and default traceroute parameters.

### Method
GET

### Endpoint
/api/options

### Parameters
None

### Response
#### Success Response (200)
- **protocols** (array) - List of supported network protocols (icmp, udp, tcp)
- **dataProviders** (array) - List of available IP geolocation providers
- **defaultOptions** (object) - Default values for traceroute parameters like queries, max_hops, and timeout_ms

#### Response Example
{
  "protocols": ["icmp", "udp", "tcp"],
  "dataProviders": ["LeoMoeAPI", "IP.SB", "IPInsight"],
  "defaultOptions": {
    "protocol": "icmp",
    "queries": 3,
    "max_hops": 30,
    "timeout_ms": 1000
  }
}
```

--------------------------------

### Establish Real-time WebSocket Trace

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Connects to the WebSocket endpoint to receive real-time updates for trace hops. It handles different message types including start, hop, MTR raw data, and completion events.

```javascript
const ws = new WebSocket('ws://localhost:1080/ws/trace');

ws.onopen = () => {
  ws.send(JSON.stringify({
    target: "1.1.1.1",
    protocol: "icmp",
    queries: 3,
    max_hops: 30,
    data_provider: "LeoMoeAPI",
    language: "en",
    mode: "single"
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "start": console.log("Trace started:", msg.data); break;
    case "hop": console.log(`Hop ${msg.data.ttl}:`, msg.data.attempts); break;
    case "mtr_raw": console.log("MTR event:", msg.data); break;
    case "complete": console.log("Trace complete:", msg.data); ws.close(); break;
    case "error": console.error("Error:", msg.error, "Status:", msg.status); break;
  }
};
```

--------------------------------

### Basic Route Tracing with NextTrace

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Demonstrates how to perform basic route tracing using NextTrace, specifying the network interface or source IP address. It supports both IPv4 and IPv6.

```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 CLI Usage and Configuration

Source: https://github.com/nxtrace/ntrace-core/blob/main/README_zh_CN.md

This snippet displays the full help menu and available command-line arguments for the NextTrace utility. It covers network protocol selection, hop limits, data provider configuration, and output formatting options.

```shell
nexttrace [-h|--help] [--init] [-4|--ipv4] [-6|--ipv6] [-T|--tcp] [-U|--udp] [-F|--fast-trace] [-p|--port <integer>] [--icmp-mode <integer>] [-q|--queries <integer>] [--max-attempts <integer>] [--parallel-requests <integer>] [-m|--max-hops <integer>] [-d|--data-provider (IP.SB|ip.sb|IPInfo|ipinfo|IPInsight|ipinsight|IPAPI.com|ip-api.com|IPInfoLocal|ipinfolocal|chunzhen|LeoMoeAPI|leomoeapi|ipdb.one|disable-geoip)] [--pow-provider (api.nxtrace.org|sakura)] [-n|--no-rdns] [-a|--always-rdns] [-P|--route-path] [--dn42] [-o|--output "<value>"] [-O|--output-default] [--table] [--raw] [-j|--json] [-c|--classic] [-f|--first <integer>] [-M|--map] [-e|--disable-mpls] [-V|--version] [-s|--source "<value>"] [--source-port <integer>] [-D|--dev "<value>"] [--listen "<value>"] [--deploy] [-z|--send-time <integer>] [-i|--ttl-time <integer>] [--timeout <integer>] [--psize <integer>] [--dot-server (dnssb|aliyun|dnspod|google|cloudflare)] [-g|--language (en|cn)] [-C|--no-color] [--from "<value>"] [-t|--mtr] [-r|--report] [-w|--wide] [--show-ips] [-y|--ipinfo <integer>] [--file "<value>"] [TARGET "<value>"]
```

--------------------------------

### Go Library IP Geolocation Sources

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Demonstrates how to use different IP geolocation providers (LeoMoeAPI, IPInfo, ip-api.com, IPInfoLocal) with configurable timeouts and languages. It also shows how to disable geolocation and configure DoT servers.

```go
package main

import (
    "fmt"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
)

func main() {
    ip := "8.8.8.8"
    timeout := 5 * time.Second
    lang := "en"
    maptrace := true  // Include coordinates for map generation

    // LeoMoeAPI (default, requires websocket connection)
    leoSource := ipgeo.GetSource("LeoMoeAPI")
    geo, err := leoSource(ip, timeout, lang, maptrace)
    if err == nil {
        fmt.Printf("LeoMoeAPI: %s, %s, %s (AS%s) - %s\n",
            geo.Country, geo.Prov, geo.City, geo.Asnumber, geo.Owner)
    }

    // IPInfo provider
    ipinfoSource := ipgeo.GetSource("IPInfo")
    geo, _ = ipinfoSource(ip, timeout, lang, maptrace)

    // IP-API.com provider
    ipapiSource := ipgeo.GetSource("ip-api.com")
    geo, _ = ipapiSource(ip, timeout, lang, maptrace)

    // Local IPInfo database (requires ipinfoLocal.mmdb file)
    localSource := ipgeo.GetSource("IPInfoLocal")
    geo, _ = localSource(ip, timeout, lang, maptrace)

    // Disable geolocation entirely
    disabledSource := ipgeo.GetSource("disable-geoip")
    geo, _ = disabledSource(ip, timeout, lang, maptrace)
    // Returns empty IPGeoData{}

    // Get source with DoT server configuration
    dotSource := ipgeo.GetSourceWithGeoDNS("LeoMoeAPI", "cloudflare")
    geo, _ = dotSource(ip, timeout, lang, maptrace)
}

```

--------------------------------

### Build NextTrace from Source

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Commands to compile NextTrace binaries using Go. Supports different build tags to create full, tiny, or MTR-focused flavors.

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

# Tiny (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" .
```

--------------------------------

### Go Library Real-time Printer Callback

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Explains how to configure callbacks for real-time hop output as results are discovered during tracing.

```APIDOC
## Go Library Real-time Printer Callback

Configure callbacks for real-time hop output as results are discovered during tracing.

```go
package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
    "github.com/nxtrace/NTrace-core/trace"
)

func main() {
    config := trace.Config{
        Context:         context.Background(),
        DstIP:           net.ParseIP("1.1.1.1"),
        MaxHops:         30,
        NumMeasurements: 3,
        Timeout:         time.Second,
        IPGeoSource:     ipgeo.GetSource("LeoMoeAPI"),
        Lang:            "en",

        // Called for each TTL as results arrive
        RealtimePrinter: func(res *trace.Result, ttl int) {
            if ttl < 1 || ttl > len(res.Hops) {
                return
            }
            hops := res.Hops[ttl-1]
            for _, hop := range hops {
                if hop.Success && hop.Address != nil {
                    fmt.Printf("[TTL %d] %s (%.2fms)\n",
                        ttl, hop.Address.String(),
                        float64(hop.RTT)/float64(time.Millisecond)) 
                } else {
                    fmt.Printf("[TTL %d] *\n", ttl)
                }
            }
        },

        // Called asynchronously for batch updates
        AsyncPrinter: func(res *trace.Result) {
            fmt.Printf("Async update: %d total hops so far\n", len(res.Hops))
        },
    }

    result, err := trace.Traceroute(trace.ICMPTrace, config)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("\nFinal: %d hops traced\n", len(result.Hops))
}
```
```

--------------------------------

### Configure DNS and Display Options

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Customize hostname resolution using DNS-over-TLS, toggle reverse DNS lookups, set output languages, and control visual formatting.

```bash
nexttrace --dot-server cloudflare example.com
nexttrace --no-rdns 1.1.1.1
nexttrace --language en 1.1.1.1
nexttrace --no-color 1.1.1.1
export NO_COLOR=1
nexttrace --disable-mpls example.com
```

--------------------------------

### Basic Route Tracing

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Demonstrates how to perform basic route tracing using NextTrace, specifying the network interface or source IP address.

```APIDOC
## Basic Route Tracing

### Description
Perform route tracing using a specified network interface or source IP address.

### Method
`nexttrace` command with arguments.

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```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
```

### Response
#### Success Response (200)
Output showing the trace route hops.

#### Response Example
(Output varies based on network conditions)
```

--------------------------------

### Configure Network Interfaces and Sources

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Specify outgoing network interfaces or source IP addresses for traceroute packets, essential for multi-homed system environments.

```bash
nexttrace --dev eth0 2606:4700:4700::1111
nexttrace --source 204.98.134.56 9.9.9.9
nexttrace --tcp --source 192.168.1.100 --source-port 12345 example.com
```

--------------------------------

### Execute Fast Trace and Globalping

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Perform quick connectivity tests to ISP endpoints or leverage the Globalping network to trace from remote geographic locations.

```bash
nexttrace --fast-trace
nexttrace --fast-trace --tcp
nexttrace --file /path/to/iplist.txt
nexttrace google.com --from Germany
export GLOBALPING_TOKEN=your_token_here
nexttrace google.com --from japan
```

--------------------------------

### Go TCP/UDP Traceroute Configuration

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Illustrates how to perform TCP SYN and UDP traceroutes using the `trace.Traceroute` function. This snippet shows configuring `trace.Config` for different protocols, specifying destination ports, and utilizing various IP geolocation services. Error handling for trace failures is also demonstrated.

```go
package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
    "github.com/nxtrace/NTrace-core/trace"
)

func main() {
    targetIP := net.ParseIP("93.184.216.34") // example.com

    // TCP SYN trace to port 443
    tcpConfig := trace.Config{
        Context:          context.Background(),
        DstIP:            targetIP,
        DstPort:          443,
        MaxHops:          30,
        NumMeasurements:  3,
        ParallelRequests: 18,
        Timeout:          time.Second,
        IPGeoSource:      ipgeo.GetSource("IPInfo"),
        RDNS:             true,
        Lang:             "en",
    }

    result, err := trace.Traceroute(trace.TCPTrace, tcpConfig)
    if err != nil {
        fmt.Printf("TCP trace failed: %v\n", err)
        return
    }

    fmt.Printf("TCP trace completed with %d hops\n", len(result.Hops))

    // UDP trace to custom port
    udpConfig := trace.Config{
        Context:          context.Background(),
        DstIP:            net.ParseIP("8.8.8.8"),
        DstPort:          53,
        MaxHops:          30,
        NumMeasurements:  3,
        Timeout:          time.Second,
        IPGeoSource:      ipgeo.GetSource("LeoMoeAPI"),
    }

    udpResult, err := trace.Traceroute(trace.UDPTrace, udpConfig)
    if err != nil {
        fmt.Printf("UDP trace failed: %v\n", err)
        return
    }

    fmt.Printf("UDP trace completed with %d hops\n", len(udpResult.Hops))
}
```

--------------------------------

### Run Fast Network Tests

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Commands for quick backhaul routing tests using ICMP or TCP SYN protocols.

```bash
nexttrace --fast-trace
nexttrace --fast-trace --tcp
nexttrace --file /path/to/your/iplist.txt
```

--------------------------------

### Go Library Real-time Printer Callback

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Shows how to configure callbacks for real-time hop output during traceroute. The `RealtimePrinter` is called for each discovered hop, and `AsyncPrinter` for batch updates.

```go
package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
    "github.com/nxtrace/NTrace-core/trace"
)

func main() {
    config := trace.Config{
        Context:         context.Background(),
        DstIP:           net.ParseIP("1.1.1.1"),
        MaxHops:         30,
        NumMeasurements: 3,
        Timeout:         time.Second,
        IPGeoSource:     ipgeo.GetSource("LeoMoeAPI"),
        Lang:            "en",

        // Called for each TTL as results arrive
        RealtimePrinter: func(res *trace.Result, ttl int) {
            if ttl < 1 || ttl > len(res.Hops) {
                return
            }
            hops := res.Hops[ttl-1]
            for _, hop := range hops {
                if hop.Success && hop.Address != nil {
                    fmt.Printf("[TTL %d] %s (%.2fms)\n",
                        ttl, hop.Address.String(),
                        float64(hop.RTT)/float64(time.Millisecond)) 
                } else {
                    fmt.Printf("[TTL %d] *\n", ttl)
                }
            }
        },

        // Called asynchronously for batch updates
        AsyncPrinter: func(res *trace.Result) {
            fmt.Printf("Async update: %d total hops so far\n", len(res.Hops))
        },
    }

    result, err := trace.Traceroute(trace.ICMPTrace, config)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("\nFinal: %d hops traced\n", len(result.Hops))
}

```

--------------------------------

### Go Library IP Geolocation Sources

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Demonstrates how to use different geolocation providers for IP address information lookup with configurable timeout and language settings.

```APIDOC
## Go Library IP Geolocation Sources

Use different geolocation providers for IP address information lookup with configurable timeout and language.

```go
package main

import (
    "fmt"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
)

func main() {
    ip := "8.8.8.8"
    timeout := 5 * time.Second
    lang := "en"
    maptrace := true  // Include coordinates for map generation

    // LeoMoeAPI (default, requires websocket connection)
    leoSource := ipgeo.GetSource("LeoMoeAPI")
    geo, err := leoSource(ip, timeout, lang, maptrace)
    if err == nil {
        fmt.Printf("LeoMoeAPI: %s, %s, %s (AS%s) - %s\n",
            geo.Country, geo.Prov, geo.City, geo.Asnumber, geo.Owner)
    }

    // IPInfo provider
    ipinfoSource := ipgeo.GetSource("IPInfo")
    geo, _ = ipinfoSource(ip, timeout, lang, maptrace)

    // IP-API.com provider
    ipapiSource := ipgeo.GetSource("ip-api.com")
    geo, _ = ipapiSource(ip, timeout, lang, maptrace)

    // Local IPInfo database (requires ipinfoLocal.mmdb file)
    localSource := ipgeo.GetSource("IPInfoLocal")
    geo, _ = localSource(ip, timeout, lang, maptrace)

    // Disable geolocation entirely
    disabledSource := ipgeo.GetSource("disable-geoip")
    geo, _ = disabledSource(ip, timeout, lang, maptrace)
    // Returns empty IPGeoData{}

    // Get source with DoT server configuration
    dotSource := ipgeo.GetSourceWithGeoDNS("LeoMoeAPI", "cloudflare")
    geo, _ = dotSource(ip, timeout, lang, maptrace)
}
```
```

--------------------------------

### Environment Variables Reference

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Lists and explains the environment variables used to configure NextTrace behavior for persistent settings.

```APIDOC
## Environment Variables Reference

Configure NextTrace behavior through environment variables for persistent settings.

```bash
# Core runtime settings
export NEXTTRACE_DEVMODE=1              # Enable stack traces on fatal errors
export NEXTTRACE_DEBUG=1                # Print environment parsing debug info
export NEXTTRACE_DISABLEMPLS=1          # Disable MPLS display globally
export NEXTTRACE_ENABLEHIDDENDSTIP=1    # Mask destination IP in output
export NEXTTRACE_RANDOMPORT=1           # Use random source port per probe
export NEXTTRACE_MAXATTEMPTS=10         # Default max-attempts value
export NEXTTRACE_ICMPMODE=1             # ICMP mode: 0=auto, 1=socket, 2=WinDivert
export NEXTTRACE_UNINTERRUPTED=1        # Continuous raw traceroute mode
export NEXTTRACE_PROXY=http://proxy:8080  # HTTP proxy for API requests

# IP geolocation settings
export NEXTTRACE_DATAPROVIDER=ipinfo    # Default data provider
export NEXTTRACE_IPINFOLOCALPATH=/path/to/ipinfoLocal.mmdb
export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060
export NEXTTRACE_IPINFO_TOKEN=your_token
export NEXTTRACE_IPINSIGHT_TOKEN=your_token

# Backend and API settings
export NEXTTRACE_HOSTPORT=api.nxtrace.org  # Override backend host
export NEXTTRACE_TOKEN=your_token          # Pre-supplied API token
export NEXTTRACE_POWPROVIDER=sakura        # PoW provider (China users)

# Web deployment settings
export NEXTTRACE_DEPLOY_ADDR=0.0.0.0:8080
export NEXTTRACE_ALLOW_CROSS_ORIGIN=1

# Third-party integrations
export GLOBALPING_TOKEN=your_token      # Globalping authentication
export IPDBONE_BASE_URL=https://api.ipdb.one
export IPDBONE_API_ID=your_id
export IPDBONE_API_KEY=your_key
```
```

--------------------------------

### Configure Advanced Probe Settings

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Fine-tune traceroute behavior by adjusting query counts, parallelism, timeouts, and packet sizes to accommodate various network conditions.

```bash
nexttrace --queries 5 www.example.net
nexttrace --max-attempts 10 www.example.net
nexttrace --parallel-requests 1 www.example.net
nexttrace --first 5 --max-hops 10 www.example.net
nexttrace --timeout 2000 1.1.1.1
nexttrace --psize 1024 example.com
nexttrace -Q 46 example.com
nexttrace -z 100 example.com
nexttrace -i 200 example.com
```

--------------------------------

### WS /ws/trace

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Establishes a WebSocket connection for real-time, streaming traceroute results.

```APIDOC
## WS /ws/trace

### Description
Connect to this endpoint to receive real-time updates as each hop is discovered. Supports 'single' trace mode and 'mtr' continuous probing mode.

### Method
WebSocket (Upgrade)

### Endpoint
/ws/trace

### Request Body (Initial Message)
- **target** (string) - Required - Destination host.
- **mode** (string) - Optional - 'single' or 'mtr'.
- **protocol** (string) - Optional - Protocol to use.

### Response
#### Events
- **start** - Emitted when the trace begins.
- **hop** - Emitted when a new hop is discovered.
- **mtr_raw** - Emitted for continuous MTR events.
- **complete** - Emitted when the trace finishes.
```

--------------------------------

### Automated Build Script Usage

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Using the provided cross-compile script to build specific or all flavors.

```bash
./.cross_compile.sh all
./.cross_compile.sh full
./.cross_compile.sh tiny
./.cross_compile.sh ntr
```

--------------------------------

### Environment Variables Reference

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Lists and explains environment variables used to configure NextTrace behavior, including core runtime settings, IP geolocation, backend/API settings, web deployment, and third-party integrations.

```bash
# Core runtime settings
export NEXTTRACE_DEVMODE=1              # Enable stack traces on fatal errors
export NEXTTRACE_DEBUG=1                # Print environment parsing debug info
export NEXTTRACE_DISABLEMPLS=1          # Disable MPLS display globally
export NEXTTRACE_ENABLEHIDDENDSTIP=1    # Mask destination IP in output
export NEXTTRACE_RANDOMPORT=1           # Use random source port per probe
export NEXTTRACE_MAXATTEMPTS=10         # Default max-attempts value
export NEXTTRACE_ICMPMODE=1             # ICMP mode: 0=auto, 1=socket, 2=WinDivert
export NEXTTRACE_UNINTERRUPTED=1        # Continuous raw traceroute mode
export NEXTTRACE_PROXY=http://proxy:8080  # HTTP proxy for API requests

# IP geolocation settings
export NEXTTRACE_DATAPROVIDER=ipinfo    # Default data provider
export NEXTTRACE_IPINFOLOCALPATH=/path/to/ipinfoLocal.mmdb
export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060
export NEXTTRACE_IPINFO_TOKEN=your_token
export NEXTTRACE_IPINSIGHT_TOKEN=your_token

# Backend and API settings
export NEXTTRACE_HOSTPORT=api.nxtrace.org  # Override backend host
export NEXTTRACE_TOKEN=your_token          # Pre-supplied API token
export NEXTTRACE_POWPROVIDER=sakura        # PoW provider (China users)

# Web deployment settings
export NEXTTRACE_DEPLOY_ADDR=0.0.0.0:8080
export NEXTTRACE_ALLOW_CROSS_ORIGIN=1

# Third-party integrations
export GLOBALPING_TOKEN=your_token      # Globalping authentication
export IPDBONE_BASE_URL=https://api.ipdb.one
export IPDBONE_API_ID=your_id
export IPDBONE_API_KEY=your_key

```

--------------------------------

### Go Traceroute Functionality with ICMP

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Demonstrates the core `trace.Traceroute` function for performing an ICMP traceroute. It shows how to configure tracing parameters using `trace.Config`, including destination IP, port, hop limits, and reverse DNS lookup. The output processing displays hop details, including IP address, hostname, RTT, and geographical information.

```go
package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
    "github.com/nxtrace/NTrace-core/trace"
)

func main() {
    // Parse target IP
    targetIP := net.ParseIP("1.1.1.1")

    // Create trace configuration
    config := trace.Config{
        Context:          context.Background(),
        DstIP:            targetIP,
        DstPort:          80,                          // For TCP/UDP
        MaxHops:          30,
        NumMeasurements:  3,                           // Samples per hop
        ParallelRequests: 18,
        Timeout:          time.Second,
        BeginHop:         1,
        RDNS:             true,                        // Enable reverse DNS
        AlwaysWaitRDNS:   false,
        IPGeoSource:      ipgeo.GetSource("LeoMoeAPI"),
        Lang:             "en",
        RealtimePrinter:  nil,                         // Set for live output
    }

    // Execute ICMP traceroute
    result, err := trace.Traceroute(trace.ICMPTrace, config)
    if err != nil {
        fmt.Printf("Trace failed: %v\n", err)
        return
    }

    // Process results
    for _, hops := range result.Hops {
        for _, hop := range hops {
            if hop.Success && hop.Address != nil {
                fmt.Printf("TTL %d: %s (%s) - %.2fms\n",
                    hop.TTL,
                    hop.Address.String(),
                    hop.Hostname,
                    float64(hop.RTT)/float64(time.Millisecond)) 
                if hop.Geo != nil {
                    fmt.Printf("  Location: %s, %s, %s (AS%s)\n",
                        hop.Geo.Country, hop.Geo.Prov, hop.Geo.City, hop.Geo.Asnumber)
                }
            } else {
                fmt.Printf("TTL %d: * (timeout)\n", hop.TTL)
            }
        }
    }

    // Access trace map URL if generated
    if result.TraceMapUrl != "" {
        fmt.Printf("Trace Map: %s\n", result.TraceMapUrl)
    }
}
```

--------------------------------

### Path-MTU Discovery Mode

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Explains how to use NextTrace in standalone path-MTU discovery mode, including options for GeoIP, RDNS, and JSON output.

```APIDOC
## Path-MTU Discovery Mode

### Description
Perform path-MTU discovery using a tracepath-style UDP approach with live hop output or JSON formatting.

### Method
`nexttrace` command with the `--mtu` flag.

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

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

# JSON output includes hop.geo
nexttrace --mtu --json 1.1.1.1
```

### Response
#### Success Response (200)
Output detailing the path MTU discovery results, either live hop updates or a JSON document.

#### Response Example
```json
{
  "example": "(JSON output varies based on network conditions and options)"
}
```

### Notes
- `--mtu` is an independent UDP-only mode.
- TTY output updates hops in place; redirected output provides line-by-line streaming.
- `--mtu --json` prints only the MTU JSON document.
- GeoIP, RDNS, `--data-provider`, `--language`, `--no-rdns`, `--always-rdns`, and `--dot-server` apply to this mode.
```

--------------------------------

### Basic NextTrace Command Usage

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Common commands for performing traceroute, outputting to JSON, and configuring network diagnostic parameters.

```bash
nexttrace 1.0.0.1
nexttrace --table 1.0.0.1
nexttrace --json 1.0.0.1
nexttrace --output ./trace.log 1.0.0.1
nexttrace --ipv6 2606:4700:4700::1111
```

--------------------------------

### NextTrace: Output Formatting and Control

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Demonstrates options for controlling NextTrace output, such as disabling reverse DNS lookups, setting probe packet size, TOS field, route-path diagrams, and color output.

```bash
# 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
```

--------------------------------

### Go Context for Traceroute Cancellation

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Demonstrates using Go's `context` package with `trace.TracerouteWithContext` to manage timeouts and cancellations for traceroute operations. This allows for graceful termination of long-running traces, preventing resource leaks and providing feedback on the reason for termination (timeout or cancellation).

```go
package main

import (
    "context"
    "fmt"
    "net"
    "time"

    "github.com/nxtrace/NTrace-core/ipgeo"
    "github.com/nxtrace/NTrace-core/trace"
)

func main() {
    // Create context with 30-second timeout
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    config := trace.Config{
        DstIP:           net.ParseIP("1.1.1.1"),
        MaxHops:         30,
        NumMeasurements: 3,
        Timeout:         time.Second,
        IPGeoSource:     ipgeo.GetSource("LeoMoeAPI"),
    }

    // Use TracerouteWithContext for explicit context passing
    result, err := trace.TracerouteWithContext(ctx, trace.ICMPTrace, config)
    if err != nil {
        if ctx.Err() == context.DeadlineExceeded {
            fmt.Println("Trace timed out after 30 seconds")
        } else if ctx.Err() == context.Canceled {
            fmt.Println("Trace was cancelled")
        } else {
            fmt.Printf("Trace error: %v\n", err)
        }
        return
    }

    fmt.Printf("Trace completed: %d hops discovered\n", len(result.Hops))
}
```

--------------------------------

### TCP and UDP Traceroute with NextTrace

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Explains how to use NextTrace with TCP and UDP protocols for traceroute requests. It covers specifying ports, source ports, and different protocol options.

```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
```

--------------------------------

### POST /api/trace

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Initiates a network traceroute to a specified target using various protocols and configuration options.

```APIDOC
## POST /api/trace

### Description
Performs a traceroute to the target host. Supports ICMP and TCP protocols with configurable hop limits, timeouts, and data providers.

### Method
POST

### Endpoint
/api/trace

### Parameters
#### Request Body
- **target** (string) - Required - The destination IP or hostname.
- **protocol** (string) - Optional - The protocol to use (icmp, tcp, udp). Default: icmp.
- **queries** (integer) - Optional - Number of queries per hop.
- **max_hops** (integer) - Optional - Maximum number of hops to trace.
- **timeout_ms** (integer) - Optional - Timeout in milliseconds.
- **port** (integer) - Optional - Target port for TCP/UDP protocols.
- **ipv4_only** (boolean) - Optional - Force IPv4 resolution.
- **data_provider** (string) - Optional - The geolocation data provider to use.

### Request Example
{
  "target": "1.1.1.1",
  "protocol": "icmp",
  "queries": 3,
  "max_hops": 30
}

### Response
#### Success Response (200)
- **target** (string) - The target address.
- **hops** (array) - List of hop objects containing TTL, IP, and geolocation data.
- **trace_map_url** (string) - URL to the generated trace visualization.

#### Response Example
{
  "target": "1.1.1.1",
  "hops": [{"ttl": 1, "attempts": [{"ip": "192.168.1.1", "rtt_ms": 1.23}]}]
}
```

--------------------------------

### Configure Output Formats

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Control how traceroute results are displayed, including machine-readable formats like JSON or raw streams, and visual path diagrams.

```bash
nexttrace --json 1.0.0.1
nexttrace --table 1.0.0.1
nexttrace --output ./trace.log 1.0.0.1
nexttrace --route-path www.time.com.my
```

--------------------------------

### Perform Path MTU Discovery

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Execute tracepath-style UDP path MTU discovery to identify the maximum transmission unit along the network path.

```bash
nexttrace --mtu 1.1.1.1
nexttrace --mtu --json 1.1.1.1
```

--------------------------------

### TCP and UDP Traceroute

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Illustrates how to use NextTrace with TCP and UDP protocols for traceroute requests, including port specification and source port control.

```APIDOC
## TCP and UDP Traceroute

### Description
Utilize TCP or UDP protocols for traceroute requests, with options to specify ports and source ports.

### Method
`nexttrace` command with `--tcp` or `--udp` flags.

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

# Specify TCP port (default is 80)
nexttrace --tcp --port 443 2001:4860:4860::8888

# UDP Trace
nexttrace --udp 1.0.0.1

# Specify UDP port (default is 33494)
nexttrace --udp --port 5353 1.0.0.1

# Specify source port for TCP/UDP trace
nexttrace --tcp --source-port 14514 www.bing.com
```

### Response
#### Success Response (200)
Output detailing the traceroute results using the specified protocol.

#### Response Example
(Output varies based on network conditions)
```

--------------------------------

### Path-MTU Discovery Mode with NextTrace

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Details the standalone path-MTU discovery mode in NextTrace, which uses UDP. It covers live hop output, GeoIP integration, and JSON output format.

```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
```

--------------------------------

### Run NextTrace in MTR Continuous Probing Mode

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Commands to execute NextTrace in MTR mode for real-time network monitoring. Supports various protocols, custom intervals, and report generation formats.

```bash
# MTR mode: continuous probing with ICMP
nexttrace -t 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
nexttrace -t -i 500 1.1.1.1

# Report mode: probe each hop N times then print a final summary
nexttrace -r -q 5 1.1.1.1

# MTR raw stream mode for machine-friendly output
nexttrace --mtr --raw 1.1.1.1
```

--------------------------------

### Perform TCP Trace with Custom Port

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Initiates a TCP-based trace to a specific target and port. This request includes configuration options like IPv4-only enforcement and RDNS settings.

```bash
curl -X POST http://localhost:1080/api/trace \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "protocol": "tcp",
    "port": 443,
    "ipv4_only": true,
    "disable_rdns": false,
    "data_provider": "IPInfo"
  }'
```

--------------------------------

### Advanced NextTrace Functions: TTL, Queries, Parallelism

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

Covers advanced NextTrace options including controlling the number of queries per hop, maximum attempts, parallel request handling, and TTL range.

```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
```

--------------------------------

### Run Continuous MTR Probing

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Perform ongoing network path analysis with real-time statistics. Includes interactive TUI controls and report generation modes.

```bash
nexttrace -t 1.1.1.1
nexttrace -r -q 5 1.1.1.1
nexttrace --mtr --raw 1.1.1.1
```

--------------------------------

### Perform Basic Network Traceroute

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Execute network route tracing to a target using various protocols like ICMP, TCP, or UDP. Supports domain names, URLs, and specific IP versions.

```bash
nexttrace 1.0.0.1
nexttrace example.com
nexttrace --ipv4 google.com
nexttrace --tcp --port 443 www.google.com
nexttrace --udp --port 5353 1.0.0.1
```

--------------------------------

### Configure IP Geolocation Providers

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Specify the data source for IP geolocation information. Allows switching between various providers or disabling lookups entirely.

```bash
nexttrace --data-provider IPInfo 1.1.1.1
nexttrace --data-provider ip-api.com 1.1.1.1
nexttrace --data-provider disable-geoip 1.1.1.1
```

--------------------------------

### Perform Network Trace via REST API

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Executes a network trace request by sending a POST request to the /api/trace endpoint. It supports various parameters such as target, protocol, hop limits, and data providers.

```bash
curl -X POST http://localhost:1080/api/trace \
  -H "Content-Type: application/json" \
  -d '{
    "target": "1.1.1.1",
    "protocol": "icmp",
    "queries": 3,
    "max_hops": 30,
    "timeout_ms": 1000,
    "data_provider": "LeoMoeAPI",
    "language": "en"
  }'
```

--------------------------------

### Configure Windows Firewall for ICMP

Source: https://github.com/nxtrace/ntrace-core/blob/main/README.md

PowerShell commands to allow ICMP traffic on Windows for normal user mode execution.

```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
```

--------------------------------

### POST /api/cache/clear

Source: https://context7.com/nxtrace/ntrace-core/llms.txt

Clears the internal cache of the NTrace service.

```APIDOC
## POST /api/cache/clear

### Description
Clears all internal cached data used by the traceroute service.

### Method
POST

### Endpoint
/api/cache/clear
```