Diving into a hidden macOS tool - networkQuality
Getting Started with networkQuality
The networkQuality tool is a built-in tool released in macOS Monterey that can help diagnose network issues and measure network performance. In this post, we'll go over how to use the networkQuality tool and some of its key features.
Running the Default Tests
To access the Network Quality tool, open the Terminal app on your Mac and enter the following command:
networkQuality -v
This command starts the tool and performs the default set of tests, displaying the results in the Terminal window.
Example output:
==== SUMMARY ====
Uplink capacity: 44.448 Mbps (Accuracy: High)
Downlink capacity: 162.135 Mbps (Accuracy: High)
Responsiveness: Low (73 RPM) (Accuracy: High)
Idle Latency: 50.125 milliseconds (Accuracy: High)
Interface: en0
Uplink bytes transferred: 69.921 MB
Downlink bytes transferred: 278.340 MB
Uplink Flow count: 16
Downlink Flow count: 12
Start: 13/05/2023, 15:04:13
End: 13/05/2023, 15:04:27
OS Version: Version 13.3.1 (a) (Build 22E772610a)
Usage:
USAGE: networkQuality [-C <configuration_url>] [-c] [-h] [-I <network interface name>] [-k] [-p] [-r host] [-s] [-v]
-C: override Configuration URL or path (with scheme file://)
-c: Produce computer-readable output
-h: Show help (this message)
-I: Bind test to interface (e.g., en0, pdp_ip0,...)
-k: Disable certificate validation
-p: Use Private Relay
-r: Connect to host or IP, overriding DNS for initial config request
-s: Run tests sequentially instead of parallel upload/download
-v: Verbose output
Using Private Relay
The Network Quality tool also supports Apple's Private Relay feature, which encrypts and routes all network traffic through two separate servers for added privacy and security. To use Private Relay with the tool, you can add the "-p" flag to the command:
networkQuality -v -p
Customizing the Configuration
You can customize the configuration used by the Network Quality tool. By default, the tool requests a configuration file from Apple everytime via https://mensura.cdn-apple.com/api/v1/gm/config. However, you can specify a different Configuration URL using the -C flag.
Apple's default config:
{ "version": 1,
"test_endpoint": "uklon6-edge-bx-031.aaplimg.com",
"urls": {
"small_https_download_url": "https://mensura.cdn-apple.com/api/v1/gm/small",
"large_https_download_url": "https://mensura.cdn-apple.com/api/v1/gm/large",
"https_upload_url": "https://mensura.cdn-apple.com/api/v1/gm/slurp",
"small_download_url": "https://mensura.cdn-apple.com/api/v1/gm/small",
"large_download_url": "https://mensura.cdn-apple.com/api/v1/gm/large",
"upload_url": "https://mensura.cdn-apple.com/api/v1/gm/slurp"
}
}
Apple's test_endpoint changes on each request, selecting a different nearby server to reduce latency and distributing their server load.
For example, if you have a custom configuration file located at https://networkquality.example.com/config, you can use the following command to run the Network Quality tool with your custom configuration:
networkQuality -v -C https://networkquality.example.com/config
This command starts the tool and performs the tests using the configuration specified in the custom configuration file.
Creating Your Own Server
If you want to set up your own server for the Network Quality tool, you can find documentation on how to do so on the project's GitHub page at https://github.com/network-quality/server. This allows you to customize the tool to your specific needs and run it on your own infrastructure.
Go Server: https://github.com/network-quality/goserver
Conclusion
The networkQuality tool in macOS is a powerful tool for measuring the performance of your network connection. The fact you can run the test via Apple Private Relay without iCloud+ is a neat feature. Next steps for me will be to self-host my own server which will be a good way to test network speeds locally.
networkQuality Wiki/Community: https://github.com/network-quality/community/wiki
IPPM Responsiveness Draft RFC: https://www.ietf.org/archive/id/draft-cpaasch-ippm-responsiveness-00.html
