github.com/nxtrace/NTrace-core@v1.3.1-0.20240513132635-39169291e8c9/README.md (about) 1 <div align="center"> 2 3 <img src="asset/logo.png" height="200px" alt="NextTrace Logo"/> 4 5 </div> 6 7 <h1 align="center"> 8 <br>NextTrace<br> 9 </h1> 10 11 <h4 align="center">An open source visual routing tool that pursues light weight, developed using Golang.</h4> 12 13 --------------------------------------- 14 15 <h6 align="center">HomePage: www.nxtrace.org</h6> 16 17 <p align="center"> 18 <a href="https://github.com/nxtrace/Ntrace-V1/actions"> 19 <img src="https://img.shields.io/github/actions/workflow/status/nxtrace/Ntrace-V1/build.yml?branch=main&style=flat-square" alt="Github Actions"> 20 </a> 21 <a href="https://goreportcard.com/report/github.com/nxtrace/Ntrace-V1"> 22 <img src="https://goreportcard.com/badge/github.com/nxtrace/Ntrace-V1?style=flat-square"> 23 </a> 24 <a href="https://www.nxtrace.org/downloads"> 25 <img src="https://img.shields.io/github/release/nxtrace/Ntrace-V1/all.svg?style=flat-square"> 26 </a> 27 </p> 28 29 ## IAAS Sponsor 30 31 <div style="text-align: center;"> 32 <a href="https://dmit.io"> 33 <img src="https://assets.nxtrace.org/dmit.svg" width="170.7" height="62.9"> 34 </a> 35 36 <a href="https://misaka.io" > 37 <img src="https://assets.nxtrace.org/misaka.svg" width="170.7" height="62.9"> 38 </a> 39 40 <a href="https://portal.saltyfish.io" > 41 <img src="https://assets.nxtrace.org/snapstack.svg" width="170.7" height="62.9"> 42 </a> 43 </div> 44 45 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. 46 47 ## How To Use 48 49 Document Language: English | [简体中文](README_zh_CN.md) 50 51 ⚠️ Please note: We welcome PR submissions from the community, but please submit your PRs to the [NTrace-V1](https://github.com/nxtrace/NTrace-V1) repository instead of [NTrace-core](https://github.com/nxtrace/NTrace-core) repository.<br> 52 Regarding the NTrace-V1 and NTrace-core repositories:<br> 53 Both will largely remain consistent with each other. All development work is done within the NTrace-V1 repository. The NTrace-V1 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-V1 repository serves as a "beta" or "testing" version.<br> 54 Please note, there are exceptions to this synchronization. If a version of NTrace-V1 encounters a serious bug, NTrace-core will skip that flawed version and synchronize directly to the next version that resolves the issue. 55 56 ### Automated Install 57 58 * Linux 59 * One-click installation script 60 61 ```shell 62 curl nxtrace.org/nt |bash 63 ``` 64 * Arch Linux AUR installation command 65 * Directly download bin package (only supports amd64) 66 67 ```shell 68 yay -S nexttrace-bin 69 ``` 70 * The AUR builds are maintained by ouuan 71 * Linuxbrew's installation command 72 73 Same as the macOS Homebrew's installation method (homebrew-core version only supports amd64) 74 * Deepin installation command 75 76 ```shell 77 apt install nexttrace 78 ``` 79 * Termux installation command 80 81 ```shell 82 pkg install nexttrace-enhanced 83 ``` 84 85 * macOS 86 * macOS Homebrew's installation command 87 * Homebrew-core version 88 89 ```shell 90 brew install nexttrace 91 ``` 92 * This repository's ACTIONS automatically built version (updates faster) 93 94 ```shell 95 brew tap nxtrace/nexttrace && brew install nxtrace/nexttrace/nexttrace 96 ``` 97 * The homebrew-core build is maintained by chenrui333, please note that this version's updates may lag behind the repository Action automatically version 98 99 * Windows 100 * Windows Scoop installation command 101 * Scoop-extras version 102 103 ```powershell 104 scoop bucket add extras && scoop install extras/nexttrace 105 ``` 106 107 * Scoop-extra is maintained by soenggam 108 109 Please note, the repositories for all of the above installation methods 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. 110 111 ### Manual Install 112 * Download the precompiled executable 113 114 For users not covered by the above methods, please go directly to [Release](https://www.nxtrace.org/downloads) to download the compiled binary executable. 115 116 * `Release` provides compiled binary executables for many systems and different architectures. If none are available, you can compile it yourself. 117 * 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. 118 119 * Install from source 120 121 After installing Go >= 1.20 yourself, you can use the following command to install 122 123 ```shell 124 go install github.com/nxtrace/NTrace-core@latest 125 ``` 126 *because of the version constraints conflict, you can not install `NTrace-V1` by this* 127 After installation, the executable is in the `$GOPATH/bin` directory. If you have not set `GOPATH`, it is in the `$HOME/go/bin` directory. 128 The binary file name is consistent with the project name. You need to replace the `nexttrace` command below with `NTrace-core`. 129 If you want to be consistent with the commands below, you can rename the binary after executing the `go install` command 130 ```shell 131 mv $GOPATH/bin/NTrace-core $GOPATH/bin/nexttrace 132 ``` 133 134 ### Get Started 135 136 `NextTrace` uses the `ICMP` protocol to perform TraceRoute requests by default, which supports both `IPv4` and `IPv6` 137 138 ```bash 139 # IPv4 ICMP Trace 140 nexttrace 1.0.0.1 141 # URL 142 nexttrace http://example.com:8080/index.html?q=1 143 144 # Form printing 145 nexttrace --table 1.0.0.1 146 147 # An Output Easy to Parse 148 nexttrace --raw 1.0.0.1 149 nexttrace --json 1.0.0.1 150 151 # IPv4/IPv6 Resolve Only, and automatically select the first IP when there are multiple IPs 152 nexttrace --ipv4 g.co 153 nexttrace --ipv6 g.co 154 155 # IPv6 ICMP Trace 156 nexttrace 2606:4700:4700::1111 157 158 # Disable Path Visualization With the -M parameter 159 nexttrace koreacentral.blob.core.windows.net 160 # MapTrace URL: https://api.nxtrace.org/tracemap/html/c14e439e-3250-5310-8965-42a1e3545266.html 161 162 # Disable MPLS display using the --disable-mpls / -e parameter or the NEXTTRACE_DISABLEMPLS environment variable 163 nexttrace --disable-mpls example.com 164 export NEXTTRACE_DISABLEMPLS=1 165 ``` 166 167 PS: The routing visualization drawing module was written by [@tsosunchia](https://github.com/tsosunchia), and the specific code can be viewed at [tsosunchia/traceMap](https://github.com/tsosunchia/traceMap). 168 169 Note that in LeoMoeAPI 2.0, due to the addition of geographical location data, **we have deprecated the online query part of the OpenStreetMap API in the traceMap plugin and are using location information from our own database**. 170 171 The routing visualization function requires the geographical coordinates of each Hop, but third-party APIs generally do not provide this information, so this function is currently only supported when used with LeoMoeAPI. 172 173 `NextTrace` now supports quick testing, and friends who have a one-time backhaul routing test requirement can use it 174 175 ```bash 176 # IPv4 ICMP Fast Test (Beijing + Shanghai + Guangzhou + Hangzhou) in China Telecom / Unicom / Mobile / Education Network 177 nexttrace --fast-trace 178 179 # You can also use TCP SYN for testing 180 nexttrace --fast-trace --tcp 181 182 # You can also quickly test through a customized IP/DOMAIN list file 183 nexttrace --file /path/to/your/iplist.txt 184 # CUSTOMIZED IP DOMAIN LIST FILE FORMAT 185 ## One IP/DOMAIN per line + space + description information (optional) 186 ## forExample: 187 ## 106.37.67.1 BEIJING-TELECOM 188 ## 240e:928:101:31a::1 BEIJING-TELECOM 189 ## bj.10086.cn BEIJING-MOBILE 190 ## 2409:8080:0:1::1 191 ## 223.5.5.5 192 ``` 193 194 `NextTrace` already supports route tracing for specified Network Devices 195 196 ```bash 197 # Use eth0 network interface 198 nexttrace --dev eth0 2606:4700:4700::1111 199 200 # Use eth0 network interface's IP 201 # 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) 202 nexttrace --source 204.98.134.56 9.9.9.9 203 ``` 204 205 `NextTrace` can also use `TCP` and `UDP` protocols to perform `Traceroute` requests, but `UDP` protocols only supports `IPv4` now 206 207 ```bash 208 # TCP SYN Trace 209 nexttrace --tcp www.bing.com 210 211 # You can specify the port by yourself [here is 443], the default port is 80 212 nexttrace --tcp --port 443 2001:4860:4860::8888 213 214 # UDP Trace 215 nexttrace --udp 1.0.0.1 216 217 nexttrace --udp --port 53 1.0.0.1 218 ``` 219 220 `NextTrace` also supports some advanced functions, such as ttl control, concurrent probe packet count control, mode switching, etc. 221 222 ```bash 223 # Send 2 probe packets per hop 224 nexttrace --queries 2 www.hkix.net 225 226 # No concurrent probe packets, only one probe packet is sent at a time 227 nexttrace --parallel-requests 1 www.hkix.net 228 229 # Start Trace with TTL of 5, end at TTL of 10 230 nexttrace --first 5 --max-hops 10 www.decix.net 231 # In addition, an ENV is provided to set whether to hide the destination IP 232 export NEXTTRACE_ENABLEHIDDENDSTIP=1 233 234 # Turn off the IP reverse parsing function 235 nexttrace --no-rdns www.bbix.net 236 237 # Set the payload size to 1024 bytes 238 nexttrace --psize 1024 example.com 239 240 # Feature: print Route-Path diagram 241 # Route-Path diagram example: 242 # AS6453 Tata Communication「Singapore『Singapore』」 243 # ╭╯ 244 # ╰AS9299 Philippine Long Distance Telephone Co.「Philippines『Metro Manila』」 245 # ╭╯ 246 # ╰AS36776 Five9 Inc.「Philippines『Metro Manila』」 247 # ╭╯ 248 # ╰AS37963 Aliyun「ALIDNS.COM『ALIDNS.COM』」 249 nexttrace --route-path www.time.com.my 250 251 # Disable color output 252 nexttrace --nocolor 1.1.1.1 253 # or use ENV 254 export NO_COLOR=1 255 ``` 256 257 `NextTrace` supports users to select their own IP API (currently supports: `LeoMoeAPI`, `IP.SB`, `IPInfo`, `IPInsight`, `IPAPI.com`, `Ip2region`, `IPInfoLocal`, `CHUNZHEN`) 258 259 ```bash 260 # You can specify the IP database by yourself [IP-API.com here], if not specified, LeoMoeAPI will be used 261 nexttrace --data-provider ip-api.com 262 ## 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 263 ## If necessary, you can clone this project, add the token provided by ipinfo or IPInsight and compile it yourself 264 ## 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) 265 ## For the offline database Ip2region, you can download it manually and rename it to ip2region.db, or let NextTrace download it automatically 266 ## Fill the token to: ipgeo/tokens.go 267 ## Please be aware: Due to the serious abuse of IP.SB, you will often be not able to query IP data from this source 268 ## 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 269 270 # 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 271 export NEXTTRACE_CHUNZHENURL=http://127.0.0.1:2060 272 ## You can use https://github.com/freshcn/qqwry to build your own Pure-FTPd IP database service 273 274 # You can also specify the default IP database by setting an environment variable 275 export NEXTTRACE_DATAPROVIDER=ipinfo 276 ``` 277 278 `NextTrace` supports mixed parameters and shortened parameters 279 280 ```bash 281 Example: 282 nexttrace --data-provider IPAPI.com --max-hops 20 --tcp --port 443 --queries 5 --no-rdns 1.1.1.1 283 nexttrace -tcp --queries 2 --parallel-requests 1 --table --route-path 2001:4860:4860::8888 284 285 Equivalent to: 286 nexttrace -d ip-api.com -m 20 -T -p 443 -q 5 -n 1.1.1.1 287 nexttrace -T -q 2 --parallel-requests 1 -t -P 2001:4860:4860::8888 288 ``` 289 290 ### IP Database 291 292 #### We use [bgp.tools](https://bgp.tools) as a data provider for routing tables. 293 294 NextTrace BackEnd is now open-source. 295 296 https://github.com/sjlleo/nexttrace-backend 297 298 NextTrace `LeoMoeAPI` now utilizes the Proof of Work (POW) mechanism to prevent abuse, where NextTrace introduces the powclient library as a client-side component. Both the POW CLIENT and SERVER are open source, and everyone is welcome to use them. (Please direct any POW module-related questions to the corresponding repositories) 299 300 - [GitHub - tsosunchia/powclient: Proof of Work CLIENT for NextTrace](https://github.com/tsosunchia/powclient) 301 - [GitHub - tsosunchia/powserver: Proof of Work SERVER for NextTrace](https://github.com/tsosunchia/powserver) 302 303 All NextTrace IP geolocation `API DEMO` can refer to [here](https://github.com/nxtrace/NTrace-core/blob/main/ipgeo/) 304 305 ### For full usage list, please refer to the usage menu 306 307 ```shell 308 Usage: nexttrace [-h|--help] [-4|--ipv4] [-6|--ipv6] [-T|--tcp] [-U|--udp] 309 [-F|--fast-trace] [-p|--port <integer>] [-q|--queries 310 <integer>] [--parallel-requests <integer>] [-m|--max-hops 311 <integer>] [-d|--data-provider 312 (Ip2region|ip2region|IP.SB|ip.sb|IPInfo|ipinfo|IPInsight|ipinsight|IPAPI.com|ip-api.com|IPInfoLocal|ipinfolocal|chunzhen|LeoMoeAPI|leomoeapi|disable-geoip)] 313 [--pow-provider (api.nxtrace.org|sakura)] [-n|--no-rdns] 314 [-a|--always-rdns] [-P|--route-path] [-r|--report] [--dn42] 315 [-o|--output] [-t|--table] [--raw] [-j|--json] [-c|--classic] 316 [-f|--first <integer>] [-M|--map] [-e|--disable-mpls] 317 [-v|--version] [-s|--source "<value>"] [-D|--dev "<value>"] 318 [-z|--send-time <integer>] [-i|--ttl-time <integer>] 319 [--timeout <integer>] [--psize <integer>] 320 [_positionalArg_nexttrace_32 "<value>"] [--dot-server 321 (dnssb|aliyun|dnspod|google|cloudflare)] [-g|--language 322 (en|cn)] [--file "<value>"] [-C|--nocolor] 323 324 Arguments: 325 326 -h --help Print help information 327 -4 --ipv4 Use IPv4 only 328 -6 --ipv6 Use IPv6 only 329 -T --tcp Use TCP SYN for tracerouting (default port 330 is 80) 331 -U --udp Use UDP SYN for tracerouting (default port 332 is 53) 333 -F --fast-trace One-Key Fast Trace to China ISPs 334 -p --port Set the destination port to use. It is 335 either initial udp port value for 336 "default"method (incremented by each 337 probe, default is 33434), or initial seq 338 for "icmp" (incremented as well, default 339 from 1), or some constantdestination port 340 for other methods (with default of 80 for 341 "tcp", 53 for "udp", etc.) 342 -q --queries Set the number of probes per each hop. 343 Default: 3 344 --parallel-requests Set ParallelRequests number. It should be 345 1 when there is a multi-routing. Default: 346 18 347 -m --max-hops Set the max number of hops (max TTL to be 348 reached). Default: 30 349 -d --data-provider Choose IP Geograph Data Provider [IP.SB, 350 IPInfo, IPInsight, IP-API.com, Ip2region, 351 IPInfoLocal, CHUNZHEN, disable-geoip]. 352 Default: LeoMoeAPI 353 --pow-provider Choose PoW Provider [api.nxtrace.org, sakura] 354 For China mainland users, please use 355 sakura. Default: api.nxtrace.org 356 -n --no-rdns Do not resolve IP addresses to their 357 domain names 358 -a --always-rdns Always resolve IP addresses to their 359 domain names 360 -P --route-path Print traceroute hop path by ASN and 361 location 362 -r --report output using report mode 363 --dn42 DN42 Mode 364 -o --output Write trace result to file 365 (RealTimePrinter ONLY) 366 -t --table Output trace results as table 367 --raw An Output Easy to Parse 368 -j --json Output trace results as JSON 369 -c --classic Classic Output trace results like 370 BestTrace 371 -f --first Start from the first_ttl hop (instead from 372 1). Default: 1 373 -M --map Disable Print Trace Map 374 -e --disable-mpls Disable MPLS 375 -v --version Print version info and exit 376 -s --source Use source src_addr for outgoing packets 377 -D --dev Use the following Network Devices as the 378 source address in outgoing packets 379 -z --send-time Set how many [milliseconds] between 380 sending each packet.. Useful when some 381 routers use rate-limit for ICMP messages. 382 Default: 100 383 -i --ttl-time Set how many [milliseconds] between 384 sending packets groups by TTL. Useful when 385 some routers use rate-limit for ICMP 386 messages. Default: 500 387 --timeout The number of [milliseconds] to keep probe 388 sockets open before giving up on the 389 connection.. Default: 1000 390 --psize Set the packet size (payload size). 391 Default: 52 392 --_positionalArg_nexttrace_32 IP Address or domain name 393 --dot-server Use DoT Server for DNS Parse [dnssb, 394 aliyun, dnspod, google, cloudflare] 395 -g --language Choose the language for displaying [en, 396 cn]. Default: cn 397 --file Read IP Address or domain name from file 398 -C --nocolor Disable Colorful Output 399 ``` 400 401 ## Project screenshot 402 403  404 405  406 407 ## OpenTrace 408 409 `OpenTrace` is the cross-platform `GUI` version of `NextTrace` developed by @Archeb, bringing a familiar but more powerful user experience. 410 411 This software is still in the early stages of development and may have many flaws and errors. We value your feedback. 412 413 [https://github.com/Archeb/opentrace](https://github.com/Archeb/opentrace) 414 415 ## NEXTTRACE WEB API 416 417 `NextTraceWebApi` is a web-based server implementation of `NextTrace` in the `MTR` style, offering various deployment options including `Docker`. 418 419 [https://github.com/nxtrace/nexttracewebapi](https://github.com/nxtrace/nexttracewebapi) 420 421 ## NextTraceroute 422 423 `NextTraceroute` is a root-free Android route tracing application that defaults to using the `NextTrace API`, developed by @surfaceocean. 424 425 [https://github.com/nxtrace/NextTraceroute](https://github.com/nxtrace/NextTraceroute) 426 427 ## LeoMoeAPI Credits 428 429 NextTrace focuses on Golang Traceroute implementations, and its LeoMoeAPI geolocation information is not supported by raw data, so a commercial version is not possible. 430 431 The LeoMoeAPI data is subject to copyright restrictions from multiple data sources, and is only used for the purpose of displaying the geolocation of route tracing. 432 433 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. 434 435 2. At the same time, we would like to credit isyekong for their contribution to rDNS-based calibration ideas and data. LeoMoeAPI is accelerating the development of rDNS resolution function, and has already achieved automated geolocation resolution for some backbone networks, but there are some misjudgments. 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. 436 437 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. 438 439 4. I would also like to credit FFEE_CO, TheresaQWQ, stydxm and others for their help. LeoMoeAPI has received a lot of support since its first release, so I would like to credit them all! 440 441 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. 442 443 444 ## JetBrain Support 445 446 #### This Project uses [JetBrain Open-Source Project License](https://jb.gg/OpenSourceSupport). We Proudly Develop By Goland. 447 448 <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/GoLand.png" title="" alt="GoLand logo" width="331"> 449 450 ## Credits 451 452 [IPInfo](https://ipinfo.io) Provided most of the data support for this project free of charge 453 454 [BGP.TOOLS](https://bgp.tools) Provided some data support for this project free of charge 455 456 [PeeringDB](https://www.peeringdb.com) Provided some data support for this project free of charge 457 458 [sjlleo](https://github.com/sjlleo) The perpetual leader, founder, and core contributors 459 460 [tsosunchia](https://github.com/tsosunchia) The project chair, infra maintainer, and core contributors 461 462 [Vincent Young](https://github.com/missuo) 463 464 [zhshch2002](https://github.com/zhshch2002) 465 466 [Sam Sam](https://github.com/samleong123) 467 468 [waiting4new](https://github.com/waiting4new) 469 470 [FFEE_CO](https://github.com/fkx4-p) 471 472 [bobo liu](https://github.com/fakeboboliu) 473 474 [YekongTAT](https://github.com/isyekong) 475 476 ### Others 477 478 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. 479 480 For feedback related to corrections about IP information, we currently have two channels available: 481 >- [IP 错误报告汇总帖](https://github.com/orgs/nxtrace/discussions/222) in the GITHUB ISSUES section of this project (Recommended) 482 >- This project's dedicated correction email: `correction@nxtrace.org` (Please note that this email is only for correcting IP-related information. For other feedback, please submit an ISSUE) 483 484 How to obtain the freshly baked binary executable of the latest commit? 485 > Please go to the most recent [Build & Release](https://github.com/nxtrace/Ntrace-V1/actions/workflows/build.yml) workflow in GitHub Actions. 486 487 ## Star History 488 489 [](https://star-history.com/#nxtrace/NTrace-core&Date)