diff --git a/README.md b/README.md index 8a7c110..d964aa1 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,13 @@ ![Crusader Results Screenshot](./media/Crusader-Result.png) -The **Crusader Network Tester** measures network rates and latency +The **Crusader Network Tester** measures network throughput, latency and packet loss in the presence of upload and download traffic. It also incorporates a continuous latency tester for monitoring background responsiveness. -It produces plots of the traffic rates, latency and packet loss. -Crusader uses TCP and UDP ports 35481 (only) for its tests. + +Crusader makes throughput measurements using TCP on port 35481 +and latency tests using UDP port 35481. The remote web server option uses TCP port 35482. Local server discovery uses UDP port 35483. @@ -20,11 +21,13 @@ Local server discovery uses UDP port 35483. and Android are available on the [Releases](https://github.com/Zoxc/crusader/releases) page. The GUI is not prebuilt for Linux and must be built from source. -A **Docker container** for running the server may be found on -[dockerhub](https://hub.docker.com/r/zoxc/crusader). + +**Documentation** See the [Documentation](#documentation) +section below. **Status:** The latest Crusader release version is shown above. - The pre-built binaries always provide the latest version. + The [pre-built binaries](https://github.com/Zoxc/crusader/releases) + always provide the latest version. See the [CHANGELOG.md](./CHANGELOG.md) file for details. ## Crusader GUI @@ -44,9 +47,10 @@ Enter the address of another computer that's running the Crusader server, then click **Start test**. When the test is complete, the **Result** tab shows a chart like the second image below. -(An easy way to run the server is to download a copy -of the Crusader GUI -to another computer, start it, then choose the **Server** tab.) + +An easy way to use Crusader is to download +the Crusader GUI onto two computers, then +start the server on one computer, and the client on the other. ![Crusader Client Screenshot](./media/Crusader-Client.png) @@ -55,7 +59,7 @@ The Crusader GUI has five tabs: * **Client tab** Runs the Crusader client program. The options shown above are described in the - [Command-line options](./#command-line-options) section. + [Command-line options](./docs/CLI.md) page. * **Server tab** Runs the Crusader server, listening for connections from other clients @@ -99,169 +103,17 @@ and back (round-trip time). * The **Packet Loss** plot has green and blue marks that indicate times when packets were lost. -## Running Crusader from the command line - -### Server - -To host a Crusader server, run this on the _server_ machine: - -```sh -crusader serve -``` - -### Client - -To start a test, run this on the _client machine_: - -```sh -crusader test -``` - -### Remote - -To host a web server that provides remote control of a Crusader client, -run the command below, then connect to -`http://ip-of-the-crusader-device:35482` - -```sh -crusader remote -``` - -### Options for the `test` command - -**Usage: crusader test [OPTIONS] \** - -**Arguments:** \ - -**Options:** - -* **`--download`** - Run a download test -* **`--upload`** - Run an upload test -* **`--bidirectional`** - Run a test doing both download and upload -* **`--idle`** - Run a test only measuring latency. The duration is specified by `grace_duration` -* **`--port `** - Specifies the TCP and UDP port used by the server - [default: 35481] -* **`--streams `** - The number of TCP connections used to generate - traffic in a single direction - [default: 16] -* **`--stream-stagger `** - The delay between the start of each stream - [default: 0.0] -* **`--load-duration `** - The duration in which traffic is generated - [default: 5.0] -* **`--grace-duration `** - The idle time between each test - [default: 1.0] -* **`--latency-sample-interval `** - [default: 5.0] -* **`--throughput-sample-interval `** - [default: 20.0] -* **`--plot-transferred`** - Plot transferred bytes -* **`--plot-split-throughput`** - Plot upload and download separately and plot streams -* **`--plot-max-throughput `** - Sets the axis for throughput to at least this value. - SI units are supported so `100M` would specify 100 Mbps -* **`--plot-max-latency `** - Sets the axis for latency to at least this value -* **`--plot-width `** -* **`--plot-height `** -* **`--plot-title `** -* **`--latency-peer-address `** - Specifies another server (peer) which will - also measure the latency to the server independently of the client -* **`--latency-peer`** - Use another server (peer) which will also measure the latency to the server independently of the client -* **`--out-name `** - The filename prefix used for the test result raw data and plot filenames -* **`-h, --help`** - Print help (see a summary with '-h') - -## Building Crusader from source - -Use [pre-built binaries](https://github.com/Zoxc/crusader/releases) -for everyday tests if available. - -To develop or debug Crusader, use the commands below -to build the full set of binaries. -Executables will be placed in `src/target/release` +For more details, see the +[Understanding Crusader Results](./docs/RESULTS.md) page. -### Required dependencies - -* A Rust and C toolchain. - -### Additional dependencies for `crusader-gui` - -Development packages for: - -* `fontconfig` - -To install these on Ubuntu: - -```sh -sudo apt install libfontconfig1-dev -``` - -### Building - -To build the `crusader` command line executable: - -```sh -cd src -cargo build -p crusader --release -``` - -To build both command line and GUI executables: - -```sh -cd src -cargo build --release -``` - -To build a docker container running the server: - -```sh -cd docker -docker build .. -t crusader -f server-static.Dockerfile -``` - -## Troubleshooting - -* On macOS, the first time you double-click - the pre-built `crusader` or `crusader-gui` icon, - the OS requires you to use **System Preferences -> Security** - to permit Crusader to run. - -* Crusader requires that TCP and UDP ports 35481 are open for its tests. - Crusader also uses ports 35482 for the remote webserver - and port 35483 for discovering other Crusader Servers. - Check that your firewall is letting those ports through. - -* The [Releases](https://github.com/Zoxc/crusader/releases) page - has pre-built binaries. - You can build your own using the instructions above. - -* Create a debug build by using `cargo build` - (instead of `cargo build --release`). - Binaries are saved in the _src/target/debug_ directory - -* Current binaries display the full commit hash in the log files. - To get the git commit hash of the current checkout, - use `git rev-parse HEAD`. - -* The message `Warning: Load termination timed out. There may be residual untracked traffic in the background.` is not harmful. It may happen due to the TCP termination being lost - or TCP incompatibilities between OSes. - It's likely benign if you see throughput and latency drop - to idle values after the tests in the graph. +## Documentation -* The up and down latency measurement rely on symmetric stable latency -measurements to the server. -These values may be wrong if those assumption don't hold on test startup. +* [This README](./README.md) +* [Understanding Crusader Results](./docs/RESULTS.md) +* [Local Testing](./docs/LOCAL_TESTS.md) +* [Command-line Options](./docs/CLI.md) +* [Building Crusader from source](./docs/BUILDING.md) +* [Troubleshooting](./docs/TROUBLESHOOTING.md) +* [Docker container](https://hub.docker.com/r/zoxc/crusader) + for the server is available on + [dockerhub](https://hub.docker.com/r/zoxc/crusader). diff --git a/docs/BUILDING.md b/docs/BUILDING.md new file mode 100644 index 0000000..e23ba86 --- /dev/null +++ b/docs/BUILDING.md @@ -0,0 +1,50 @@ +# Building Crusader from source + +Reminder: [Pre-built binaries](https://github.com/Zoxc/crusader/releases) +are available for everyday tests. + +## Required dependencies + +* A Rust and C toolchain. +* `fontconfig` (optional, required for `crusader-gui`) + +_Note:_ To install `fontconfig` on Ubuntu: + +```sh +sudo apt install libfontconfig1-dev +``` + +## Building Crusader + +To develop or debug Crusader, use the commands below +to build the full set of binaries. +Executables are placed in _src/target/release_ + +To build the `crusader` command line executable: + +```sh +cd src +cargo build -p crusader --release +``` + +To build both command line and GUI executables: + +```sh +cd src +cargo build --release +``` + +## Debug build + +Create a debug build by using `cargo build` +(instead of `cargo build --release`). +Binaries are saved in the _src/target/debug_ directory + +## Docker + +To build a docker container that runs the server: + +```sh +cd docker +docker build .. -t crusader -f server-static.Dockerfile +``` diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 0000000..7ba7cf9 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,101 @@ +# Running Crusader from the command line + +## Server + +To host a Crusader server, run this on the _server_ machine: + +```sh +crusader serve +``` + +## Client + +To start a test, run this on the _client machine_. +See the [command-line options](#options-for-the-test-command) below for details. + +```sh +crusader test +``` + +## Remote + +To host a web server that provides remote control of a Crusader client, +run the command below, then connect to +`http://ip-of-the-crusader-device:35482` + +```sh +crusader remote +``` + +## Plot + +Crusader creates a `.png` file from a `.crr` file using `crusader plot path-to-crr-file` +The resulting `.png` is saved in the same directory as the input file. + +## Export + +Crusader exports raw data samples from a `.crr` file +into a `.json` file using `crusader export path-to-crr-file` +The resulting `.json` is saved in the same directory as the input file. + +## Options for the `test` command + +**Usage: `crusader test [OPTIONS] `** + +**Arguments:** `` address of a Crusader server + +**Options:** + +* **`--download`** + Run a download test +* **`--upload`** + Run an upload test +* **`--bidirectional`** + Run a test doing both download and upload +* **`--idle`** + Run a test, only measuring latency without inducing traffic. + The duration is specified by `grace_duration` +* **`--port `** + Specify the TCP and UDP port used by the server + [default: 35481] +* **`--streams `** + The number of TCP connections used to generate + traffic in a single direction + [default: 8] +* **`--stream-stagger `** + The delay between the start of each stream + [default: 0.0] +* **`--load-duration `** + The duration in which traffic is generated + [default: 10.0] +* **`--grace-duration `** + The idle time between each test + [default: 2.0] +* **`--latency-sample-interval `** + [default: 5.0] +* **`--throughput-sample-interval `** + [default: 60.0] +* **`--plot-transferred`** + Plot transferred bytes +* **`--plot-split-throughput`** + Plot upload and download separately and plot streams +* **`--plot-max-throughput `** + Set the axis for throughput to at least this value. + SI units are supported so `100M` would specify 100 Mbps +* **`--plot-max-latency `** + Set the axis for latency to at least this value +* **`--plot-width `** +* **`--plot-height `** +* **`--plot-title `** +* **`--latency-peer-address `** + Address of another Crusader server (the "peer") which + concurrently measures the latency to the server and reports + the values to the client +* **`--latency-peer`** + Trigger the client to instruct a peer (another Crusader server) + to begin measuring the latency to the main server + and report the latency back +* **`--out-name `** + The filename prefix used for the raw data and plot filenames +* **`-h, --help`** + Print help (see a summary with '-h') diff --git a/docs/LOCAL_TESTS.md b/docs/LOCAL_TESTS.md new file mode 100644 index 0000000..8c25e5f --- /dev/null +++ b/docs/LOCAL_TESTS.md @@ -0,0 +1,88 @@ +# Local network testing with Crusader + +**Background:** +The Crusader Network Tester measures network throughput +and latency in the presence of upload and download traffic +and produces plots of the traffic rates, latency and packet loss. + +## Making local tests + +To test the equipment between two points on your network, +Crusader requires two computers, +one acting as a server, the other as a client. + +The Crusader program can act as both client and server. +Install the latest pre-built binary of +[Crusader](https://github.com/Zoxc/crusader/releases) +on two separate computers. Then: + +1. Connect one of those computers to your router's LAN port using an + Ethernet cable. + Start the Crusader program on it, then click the **Server** tab. See the + [screen shot](../media/Crusader-Server.png). + Click **Start server** and look for the + address(es) where the Crusader Server is listening. + (Note: The Crusader binary can also run on a small + computer such as a Raspberry Pi. + A Pi4 acting as a server can easily support 1Gbps speeds.) +2. Connect the other computer either by Ethernet, Wi-fi, + or some other adapter. + Run the Crusader program and click the Client tab. See the + [screen shot](../media/Crusader-Client.png). + Enter the address of a Crusader Server into the GUI, + and click **Start test** +3. When the test completes, you'll see charts of three bursts of traffic: + Download, Upload, and Bidirectional, + along with the latency during that activity. + See the + [Crusader README](../README.md) and + [Understanding Crusader Results](./RESULTS.md) + for details. + +**Note:** The Crusader program has both a GUI and a command-line binary. +Both act as a client or a server. +These instructions tell how to run the client on a laptop. +You may find it convenient to run the server on a remote computer. +Get both binaries from the +[Releases page](https://github.com/Zoxc/crusader/releases). + +## What can we learn? + +Your local router, Wi-fi, and other network equipment +all affect your total performance. +Even with very high speed internet service, +if the router is max'ed out it can hold back your throughput. +And you're stuck with whatever latency the router and +other local equipment create - it's added to any latency from your ISP network. +In particular: + +* Ethernet-to-Ethernet connections tend to be good: + high throughput with low latency. + But you should always check your network. + On a 1Gbps network, typical results are above 950 mbps, + and less than a dozen milliseconds of latency. +* Wi-fi has a reputation for "being slow". + This often is a result of the Wi-fi drivers injecting + hundreds of milliseconds of latency. + In addition, wireless connections will always have lower + throughput than wired connections. +* Many powerline adapters (that provide an Ethernet connection + between two AC outlets) may have high specifications, + but in practice are known to give limited throughput + and have high latency. + +Running a Crusader test between computers on the local network measures +the performance of that portion of the network. + +## Why is this important? + +These test results, in themselves, are not important. +If you are satisfied with you network's performance, +then these numerical results don't matter. + +But if you are experiencing problems, +these tests help divide the troubleshooting problem in two. + +* If the local network is running fine, performance problems must be elsewhere. +* But if the local performance is not what you expected, + that could explain the problem diff --git a/docs/RESULTS.md b/docs/RESULTS.md new file mode 100644 index 0000000..8c3d705 --- /dev/null +++ b/docs/RESULTS.md @@ -0,0 +1,80 @@ +# Understanding Crusader Results + +The Crusader GUI provides a compact summary of the test data. +Here are some hints for evaluating the results. + +## Result window + +![Result with statistics](../media/Crusader-Result-with-stats.png) + +Crusader tests the connection using three bursts of traffic. +The Throughput, Latency, and Packet loss are shown in the charts. +In the image above notice: + +* **Hovering over a chart** shows crosshairs that give the throughput + or latency of that point in the chart. + In the screen shot above, the Down latency + peaks around 250 ms. +* **Hovering over, or clicking the ⓘ symbol** opens a window that displays + a summary of the measurements. + See the description below for details. +* **Clicking a legend** ("color") in the charts shows/hides + the associated graph. + In the screen shot above, the Latency's "Round-trip" legend has been clicked, + hiding the (black) round-trip trace, + and showing only the Up and Down latency plots. +* The **Save to results** button saves two files: a plot (as `.png`) + and the data (as `.crr`) to the _crusader-results_ directory + in the user _home directory_. +* The **Open from results** button opens a `.crr` file + from the _crusader-results_ directory. +* The **Save** button opens a file dialog to save the current `.crr` file. +* The **Open** button opens a file dialog to select a `.crr` file to open. +* The **Export plot** button opens a file dialog to save a `.png` file. + +## Numerical Summary Windows + +The Crusader GUI displays charts showing Throughput, Latency, +and Packet loss. +The ⓘ symbol opens a window showing a numerical summary of the charted data. + +### Throughput + +description + +* Download - Steady state throughput, ignoring any startup transients, + during the Download portion of the test +* Upload - Steady state throughput, ignoring any startup transients, + during the Upload portion of the test +* Bidirectional - Sum of the Download and Upload throughputs + during the Bidirectional portion of the test. + Also displays the individual Download and Upload throughputs. +* Streams - number of TCP connections used in each direction +* Stream Stagger - The delay between the start of each stream +* Throughput sample interval - Interval between throughput measurements + +### Latency + +description + +Crusader smooths all the latency samples over a 400 ms window. +The values shown in the window display the maximum of those smoothed values. +This emphasizes the peaks of latency. + +* Download - Summarizes the round-trip latency during the + Download portion of the test. + Also displays the measured one-way delay for Download (from server to client) + and Upload (client to server) +* Upload - Summarizes the latency for the Upload portion of the test +* Bidirectional - Summarizes the latency for the Bidirectional portion of the test +* Idle latency - Measured latency when no traffic is present. +* Latency sample interval - Interval between latency measurements + +### Packet loss + +description + +* Download - Summarizes packet loss during the Download portion of the test +* Upload - Summarizes packet loss during the Upload portion of the test +* Bidirectional - Summarizes packet loss during the Bidirectional + portion of the test diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..f441cb1 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,27 @@ +# Troubleshooting + +* Crusader requires that TCP and UDP ports 35481 are open for its tests. + Crusader also uses ports 35482 for the remote webserver + and port 35483 for discovering other Crusader Servers. + Check that your firewall is letting those ports through. + +* On macOS, the first time you double-click + the pre-built `crusader` or `crusader-gui` icon, + the OS refuses to let it run. + You must use **System Preferences -> Privacy & Security** + to approve Crusader to run. + +* The message + `Warning: Load termination timed out. There may be residual untracked traffic in the background.` + is not harmful. + It may happen due to the TCP termination being lost + or TCP incompatibilities between OSes. + It's likely benign if you see throughput and latency drop + to idle values after the tests in the graph. + +* The up and down latency measurements rely on symmetric stable latency + measurements to the server. + These values may be wrong if those assumption don't hold on test startup. + +* The up and down latency measurement may slowly get out of sync due to + clock drift. Clocks are currently only synchronized on test startup. diff --git a/media/Crusader Screen Shots.md b/media/Crusader Screen Shots.md index ef3c330..143240d 100644 --- a/media/Crusader Screen Shots.md +++ b/media/Crusader Screen Shots.md @@ -1,23 +1,49 @@ -# Crusader Screen Shots +# Verify Crusader Screen Shots -This page is useful to check the appearance of the screen shots. -Use this process: get an image (screen shot) then -trim off the drop shadow that the Mac captures. -Then save the image in the _media_ directory. -This page helps verify that the image retains the window border, -but not the additional drop shadow. +This page is useful for checking the appearance of screen shots. +Capture the screen shots (Cmd-Shift-5 on macOS) and save with filenames +like "Client.png", "Server.png", etc., one for each of the tabs. + +Run the `batch_add_border.sh` script - it finds all these files, +removes the drop shadow and adds "Crusader-" to each result file. + +Remove the original files before committing to git. ## Client + ![Options](./Crusader-Client.png) ## Server -![Options](./Crusader-Server.png) + +![Server](./Crusader-Server.png) ## Remote -![Options](./Crusader-Remote.png) + +![Remote](./Crusader-Remote.png) ## Monitor -![Options](./Crusader-Monitor.png) + +![Monitor](./Crusader-Monitor.png) ## Result -![Options](./Crusader-Result.png) + +![Result](./Crusader-Result.png) + +## Result with stats + +![Options](./Crusader-Result-with-stats.png) + +## Throughput popup + +![Throughput](./Crusader-Throughput.png) +description + +## Latency popup + +![Latency](./Crusader-Latency.png) +description + +## Packet loss popup + +![Packet Loss](./Crusader-Loss.png) +description diff --git a/media/Crusader-Client.png b/media/Crusader-Client.png index 810e9b7..7fd5a67 100644 Binary files a/media/Crusader-Client.png and b/media/Crusader-Client.png differ diff --git a/media/Crusader-Latency.png b/media/Crusader-Latency.png new file mode 100644 index 0000000..648ebca Binary files /dev/null and b/media/Crusader-Latency.png differ diff --git a/media/Crusader-Loss.png b/media/Crusader-Loss.png new file mode 100644 index 0000000..20dc958 Binary files /dev/null and b/media/Crusader-Loss.png differ diff --git a/media/Crusader-Monitor.png b/media/Crusader-Monitor.png index b46d347..7104eca 100644 Binary files a/media/Crusader-Monitor.png and b/media/Crusader-Monitor.png differ diff --git a/media/Crusader-Remote.png b/media/Crusader-Remote.png index 2bdab2a..329aad2 100644 Binary files a/media/Crusader-Remote.png and b/media/Crusader-Remote.png differ diff --git a/media/Crusader-Result-with-stats.png b/media/Crusader-Result-with-stats.png new file mode 100644 index 0000000..e0ba650 Binary files /dev/null and b/media/Crusader-Result-with-stats.png differ diff --git a/media/Crusader-Result.png b/media/Crusader-Result.png index 298f17b..c1588d4 100644 Binary files a/media/Crusader-Result.png and b/media/Crusader-Result.png differ diff --git a/media/Crusader-Server.png b/media/Crusader-Server.png index 6fee5aa..600dd6d 100644 Binary files a/media/Crusader-Server.png and b/media/Crusader-Server.png differ diff --git a/media/Crusader-Throughput.png b/media/Crusader-Throughput.png new file mode 100644 index 0000000..cc7b45d Binary files /dev/null and b/media/Crusader-Throughput.png differ diff --git a/media/batch_add_border.sh b/media/batch_add_border.sh new file mode 100644 index 0000000..96baa3b --- /dev/null +++ b/media/batch_add_border.sh @@ -0,0 +1,58 @@ +#!/bin/bash + +# add_border.sh - This script uses ImageMagick to process +# macOS screen shots for publication + +# Usage: +# 1. Take screen shots (Cmd-Shift-5) on macOS +# 2. Save the file with a name that would be a good suffix (e.g. Remote.png) +# 3. Run this script. The script outputs modified files prefixed with "Crusader-" +# 4. Discard the original files + +# The script does the following - for the .png files in the directory: +# - find all .png files that don't begin with "Crusader" +# - remove the transparent area/drop shadow from a macOS screen shot +# - shrink the image to the size of the image +# - draw a grey border 1 px wide around the window. +# - save the resulting file as "Crusader-....png" +# Thanks, ChatGPT + +# Get the directory where the script is located +script_dir="$(dirname "$0")" + +# Define the border size (1 pixel) and colors +border_size=1 +border_color="gray" +background_color="white" + +# Loop through all .png files +for input_file in "$script_dir"/[a-zA-Z]*.png; do + # Check if the file actually exists (in case no files match) + if [ ! -f "$input_file" ]; then + continue + fi + + # Ignore files that already start with "Crusader" + if [[ $(basename "$input_file") == Crusader* ]]; then + echo "Skipping: $input_file" + continue + fi + + # Output file name (prepend "Crusader-" to the original file name) + output_file="$script_dir/Crusader-$(basename "$input_file")" + + # Process the image: + # 1. Remove the alpha channel (transparency) by filling with white + # 2. Trim the image to its non-transparent content + # 3. Add a 1-pixel grey border + magick "$input_file" \ + -alpha off \ + -trim \ + -bordercolor $border_color \ + -border ${border_size}x${border_size} \ + "$output_file" + + echo "Processed: $input_file -> $output_file" +done + +echo "All matching .png files processed."