xykt/NetQuality: a network quality check script for VPS owners and China-facing hosts

What NetQuality measures and who it is written for

NetQuality is a Shell script that inspects the network position and quality of the machine it runs on. The README describes seven modules: BGP information, local policy, access information, three-carrier TCP large-packet latency, three-carrier return routes, domestic speed tests, and international interconnection. The basic data comes from the BGP.TOOLS and BGP.HE.NET databases, and the return route module is built on NextTrace, with IP geolocation and line labelling data supplied by the NextTrace API.

The audience is narrow but concrete. Someone who has just bought a VPS and wants to know which carrier it is actually on, where traffic returns through, and how it behaves toward mainland China will get more out of this than a general sysadmin. The README is explicit that the return latency module covers 31 provinces, municipalities and autonomous regions in mainland China, split across China Telecom, China Unicom and China Mobile. That is the centre of the project. The global speed and latency tests exist, but they read as a secondary layer around the China-focused measurement.

How the script is structured and where its data comes from

The repository is small. The top level holds net.sh, plus ref/, res/, .github/, LICENSE, README.md and README_EN.md. The script is distributed as a remote file that is piped into bash, so the version you run is whatever the server returns at that moment rather than a pinned artefact in the repository.

The data flow has three external dependencies worth naming. BGP and access data come from the BGP.TOOLS and BGP.HE.NET databases. Return route tracing and the IP geolocation and line labels attached to it come from NextTrace and its official API. Speed testing toward mainland China, including the Greater Bay Area, uses SPEEDTEST.NET, and the README states that Speedtest CLI is currently the only usable command-line three-carrier speed test tool in mainland China. That sentence is doing a lot of work: it means the speed module is not replaceable with a self-hosted alternative today.

Because the script is a single Shell file, there is no daemon, no database, and no long-running process. Each run is a fresh probe. That keeps deployment trivial and also means there is no history unless you capture the output yourself, which is what the JSON mode exists for.

Installing NetQuality and running a first check

There is no package to install. The README's convenience mode launches an interactive menu, and the advanced mode takes flags directly. On a Linux host, the interactive entry point is:

bash <(curl -Ls https://Check.Place) -N

Running it opens the ScriptMenu interface shown in the README, where you pick the NetQuality test. If you prefer flags, the default run checks both stacks and prints a report:

bash <(curl -Ls https://Net.Check.Place)

For a single stack, the README gives -4 and -6. A latency-only run uses -P, and the full route mode uses -R with an optional mainland province name or abbreviation:

bash <(curl -Ls https://Net.Check.Place) -R 广西

The README notes that -R without an argument defaults to Beijing, Shanghai and Guangdong. For machine-readable output, -j produces JSON, and -o writes the report to a file whose format follows the extension:

bash <(curl -Ls https://Net.Check.Place) -j
bash <(curl -Ls https://Net.Check.Place) -o /path/to/file.json

Two flags matter before the first run in a locked-down environment. -n skips OS detection and dependency installation, and -y installs dependencies automatically. If you do not want the script to generate an online report, -p disables that feature. Docker is supported for platforms the script does not run on natively, including Windows:

docker run --rm --net=host -it xykt/netquality

The README notes that Docker runs accept the same run parameters, inserted before the && in the Linux one-liner. The --net=host flag is required because the measurements describe the host's actual network path; a bridged container would measure the wrong thing.

The dependency on external endpoints is the real limitation

Every interesting number in the report is produced by something outside the script. BGP and access data come from third-party databases. Route labelling comes from the NextTrace API. Speed figures come from SPEEDTEST.NET. If any of those endpoints is unreachable from the host you are testing, the corresponding chapter degrades or disappears, and the README's changelog shows this is not hypothetical: a 2025/04/20 entry records a fix for mainland IPs failing to fetch script resources, and a 2025/07/30 entry records replacing all HTTP requests with HTTPS.

There is a second, quieter limitation. The script pipes a remote URL into bash. That is the documented install path, and it means the code you execute is not the code in the repository at a known commit. For a one-off diagnostic on a machine you own, that is a normal trade-off in this corner of the tooling world. On a production host with a change-control process, it is a reason to fetch net.sh, read it, and run the local copy instead. The README documents -p for disabling online report generation, which addresses privacy of the results, not provenance of the script.

Finally, NetQuality is a point-in-time probe. It has no scheduling, no alerting and no baseline comparison. If your question is whether latency to a region got worse last Tuesday, this tool will not answer it.

How it compares with running NextTrace and Speedtest CLI yourself

The obvious alternative is to assemble the same picture from the underlying tools. NextTrace is a standalone traceroute implementation with its own CLI, and the NetQuality README credits the NextTrace project for the return route testing and states that the IP geolocation and line labelling data in the fifth module comes from the NextTrace official API. Speedtest CLI is the other building block, and the README describes it as the only currently usable command-line three-carrier speed test tool in mainland China.

The difference is aggregation and interpretation rather than raw capability. Running NextTrace against a target gives you a route; NetQuality runs the route test across carriers and provinces, folds repeated route information together (a 2025/04/21 changelog entry), and lays the result out against BGP and access data so the path makes sense in one view. What you give up is control: with the raw tools you choose the exact targets, the probe count and the output format, and you can script them into your own pipeline. NetQuality chooses those for you and adds a rendering layer. If you already have a traceroute pipeline, NetQuality is a second opinion, not a replacement.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived and the last push was on 2026-09-01. The README's changelog runs from the initial release on 2025/03/12 through entries in 2025 and a 2026/01/15 fix for non-conforming JSON. That cadence suggests the script is still being corrected, but the changelog also shows the shape of maintenance: compatibility fixes for macOS, a fix for an occasional hang in the three-carrier return route test, a fix for mainland IPs failing to fetch resources. These are the kinds of defects you inherit.

Upgrading is unusual because there is no version to upgrade. The documented invocation fetches the script from a URL each time, so you are always on the latest revision and there is no rollback path described in the README. Teams that need reproducibility should vendor net.sh at a known state rather than depending on the remote fetch.

The licence is AGPL-3.0, shown by the badge in the README and the LICENSE file at the repository root. AGPL is a strong copyleft licence with a network-use clause, which matters if you plan to modify the script and expose it as a service. The README does not discuss commercial use, redistribution or hosted deployments, and this is not legal advice; if you intend to build on it commercially, read the licence text and get proper advice. The README does list server sponsors and an email address for sponsorship enquiries, which indicates the project accepts commercial support, but that is separate from licensing terms.

Editorial conclusion

Adopt NetQuality if you are evaluating a VPS or a China-facing network path and want BGP, upstream, three-carrier latency, return routes and speed test data in one report, including JSON for later analysis. Skip it if you need continuous monitoring, a stable machine-readable API, or if your paths are not China-relevant, since several modules lean on mainland test endpoints and third-party services. Before relying on it, check which chapters need root, which external endpoints it contacts, and whether the -p privacy mode is required in your environment.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. xykt/NetQuality on GitHub