{"id":18711025,"url":"https://github.com/zoxc/crusader","last_synced_at":"2025-04-05T14:03:40.667Z","repository":{"id":41474543,"uuid":"499642096","full_name":"Zoxc/crusader","owner":"Zoxc","description":"A network throughput and latency tester.","archived":false,"fork":false,"pushed_at":"2024-10-03T22:35:56.000Z","size":3409,"stargazers_count":141,"open_issues_count":11,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T13:04:56.202Z","etag":null,"topics":["latency","network","throughput"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zoxc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-03T20:25:46.000Z","updated_at":"2025-03-23T20:18:45.000Z","dependencies_parsed_at":"2024-10-30T05:50:55.410Z","dependency_job_id":null,"html_url":"https://github.com/Zoxc/crusader","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zoxc%2Fcrusader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zoxc%2Fcrusader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zoxc%2Fcrusader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zoxc%2Fcrusader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zoxc","download_url":"https://codeload.github.com/Zoxc/crusader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345850,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["latency","network","throughput"],"created_at":"2024-11-07T12:36:33.127Z","updated_at":"2025-04-05T14:03:40.646Z","avatar_url":"https://github.com/Zoxc.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Crusader Network Tester\n\n[![GitHub Release](https://img.shields.io/github/v/release/Zoxc/crusader)](https://github.com/Zoxc/crusader/releases)\n[![Docker Hub](https://img.shields.io/badge/container-dockerhub-blue)](https://hub.docker.com/r/zoxc/crusader)\n[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Zoxc/crusader/blob/master/LICENSE-MIT)\n[![Apache](https://img.shields.io/badge/license-Apache-blue.svg)](https://github.com/Zoxc/crusader/blob/master/LICENSE-APACHE)\n\n![Crusader Results Screenshot](./media/Crusader-Result.png)\n\nThe **Crusader Network Tester** measures network rates and latency\nin the presence of upload and download traffic.\nIt also incorporates a continuous latency tester for\nmonitoring background responsiveness.\nIt produces plots of the traffic rates, latency and packet loss.\nCrusader uses TCP and UDP ports 35481 (only) for its tests.\nThe remote web server option uses TCP port 35482.\nLocal server discovery uses UDP port 35483.\n\n**Pre-built binaries** for Windows, Mac, Linux,\nand Android are available on the\n[Releases](https://github.com/Zoxc/crusader/releases) page.\nThe GUI is not prebuilt for Linux and must be built from source.\nA **Docker container** for running the server may be found on\n[dockerhub](https://hub.docker.com/r/zoxc/crusader).\n\n**Status:** The latest Crusader release version is shown above.\n  The pre-built binaries always provide the latest version.\n  See the [CHANGELOG.md](./CHANGELOG.md) file for details.\n\n## Crusader GUI\n\nA test run requires two separate computers,\nboth running Crusader:\na **server** that listens for connections, and\na **client** that initiates the test.\n\nThe Crusader GUI incorporates both the server and\nthe client and allows you to interact with results.\nTo use it, download the proper binary from the\n[Releases](https://github.com/Zoxc/crusader/releases) page.\n\nWhen you open the `crusader-gui` you see this window.\nEnter the address of another computer that's\nrunning the Crusader server, then click **Start test**.\nWhen the test is complete, the **Result** tab shows a\nchart like the second image below.\n(An easy way to run the server is to download a copy\nof the Crusader GUI\nto another computer, start it, then choose the **Server** tab.)\n\n![Crusader Client Screenshot](./media/Crusader-Client.png)\n\nThe Crusader GUI has five tabs:\n\n* **Client tab**\n  Runs the Crusader client program.\n  The options shown above are described in the\n  [Command-line options](./#command-line-options) section.\n\n* **Server tab**\n  Runs the Crusader server, listening for connections from other clients\n\n* **Remote tab**\n  Starts a webserver (default port 35482).\n  A browser that connects to that port can initiate\n  a test to a Crusader server.\n  \n* **Monitor tab**\n  Continually displays the latency to the selected\n  Crusader server until stopped.\n\n* **Result tab**\n  Displays the result of the most recent client run\n\n## The Result Tab\n\n![Crusader Results Screenshot](./media/Crusader-Result.png)\n\nA Crusader test creates three bursts of traffic.\nBy default, it generates ten seconds each of\ndownload only, upload only, then bi-directional traffic.\nEach burst is separated by several seconds of idle time.\n\nThe Crusader Result tab displays the results of the test with\nthree plots (see image above):\n\n* The **Throughput** plot shows the bursts of traffic.\nGreen is download (from server to client),\nblue is upload, and\nthe purple line is the instantaneous\nsum of the download plus upload.\n\n* The **Latency** plot shows the corresponding latency.\nGreen shows the  (uni-directional) time from the server to the client.\nBlue is the (uni-directional) time from the client to the server.\nBlack shows the sum from the client to the server\nand back (round-trip time).\n\n* The **Packet Loss** plot has green and blue marks\nthat indicate times when packets were lost.\n\n## Running Crusader from the command line\n\n### Server\n\nTo host a Crusader server, run this on the _server_ machine:\n\n```sh\ncrusader serve\n```\n\n### Client\n\nTo start a test, run this on the _client machine_:\n\n```sh\ncrusader test \u003cserver-ip\u003e\n```\n\n### Remote\n\nTo host a web server that provides remote control of a Crusader client,\nrun the command below, then connect to\n`http://ip-of-the-crusader-device:35482`\n\n```sh\ncrusader remote\n```\n\n### Options for the `test` command\n\n**Usage: crusader test [OPTIONS] \\\u003cSERVER\u003e**\n\n**Arguments:** \\\u003cSERVER\u003e\n\n**Options:**\n\n* **`--download`**\n          Run a download test\n* **`--upload`**\n          Run an upload test\n* **`--bidirectional`**\n          Run a test doing both download and upload\n* **`--idle`**\n          Run a test only measuring latency. The duration is specified by `grace_duration`\n* **`--port \u003cPORT\u003e`**\n          Specifies the TCP and UDP port used by the server\n          [default: 35481]\n* **`--streams \u003cSTREAMS\u003e`**\n          The number of TCP connections used to generate\n           traffic in a single direction\n          [default: 16]\n* **`--stream-stagger \u003cSECONDS\u003e`**\n          The delay between the start of each stream\n          [default: 0.0]\n* **`--load-duration \u003cSECONDS\u003e`**\n          The duration in which traffic is generated\n          [default: 5.0]\n* **`--grace-duration \u003cSECONDS\u003e`**\n          The idle time between each test\n          [default: 1.0]\n* **`--latency-sample-interval \u003cMILLISECONDS\u003e`**\n          [default: 5.0]\n* **`--throughput-sample-interval \u003cMILLISECONDS\u003e`**\n          [default: 20.0]\n* **`--plot-transferred`**\n          Plot transferred bytes\n* **`--plot-split-throughput`**\n          Plot upload and download separately and plot streams\n* **`--plot-max-throughput \u003cBPS\u003e`**\n          Sets the axis for throughput to at least this value.\n          SI units are supported so `100M` would specify 100 Mbps\n* **`--plot-max-latency \u003cMILLISECONDS\u003e`**\n          Sets the axis for latency to at least this value\n* **`--plot-width \u003cPIXELS\u003e`**\n* **`--plot-height \u003cPIXELS\u003e`**\n* **`--plot-title \u003cPLOT_TITLE\u003e`**\n* **`--latency-peer-address \u003cLATENCY_PEER_ADDRESS\u003e`**\n          Specifies another server (peer) which will\n          also measure the latency to the server independently of the client\n* **`--latency-peer`**\n          Use another server (peer) which will also measure the latency to the server independently of the client\n* **`--out-name \u003cOUT_NAME\u003e`**\n          The filename prefix used for the test result raw data and plot filenames\n* **`-h, --help`**\n          Print help (see a summary with '-h')\n\n## Building Crusader from source\n\nUse [pre-built binaries](https://github.com/Zoxc/crusader/releases)\nfor everyday tests if available.\n\nTo develop or debug Crusader, use the commands below\nto build the full set of binaries.\nExecutables will be placed in `src/target/release`\n\n### Required dependencies\n\n* A Rust and C toolchain.\n\n### Additional dependencies for `crusader-gui`\n\nDevelopment packages for:\n\n* `fontconfig`\n\nTo install these on Ubuntu:\n\n```sh\nsudo apt install libfontconfig1-dev\n```\n\n### Building\n\nTo build the `crusader` command line executable:\n\n```sh\ncd src\ncargo build -p crusader --release\n```\n\nTo build both command line and GUI executables:\n\n```sh\ncd src\ncargo build --release\n```\n\nTo build a docker container running the server:\n\n```sh\ncd docker\ndocker build .. -t crusader -f server-static.Dockerfile\n```\n\n## Troubleshooting\n\n* On macOS, the first time you double-click\n  the pre-built `crusader` or `crusader-gui` icon,\n  the OS requires you to use **System Preferences -\u003e Security**\n  to permit Crusader to run.\n  \n* Crusader requires that TCP and UDP ports 35481 are open for its tests.\n  Crusader also uses ports 35482 for the remote webserver\n  and port 35483 for discovering other Crusader Servers.\n  Check that your firewall is letting those ports through.\n\n* The [Releases](https://github.com/Zoxc/crusader/releases) page\n  has pre-built binaries.\n  You can build your own using the instructions above.\n  \n* Create a debug build by using `cargo build`\n  (instead of `cargo build --release`).\n  Binaries are saved in the _src/target/debug_ directory\n\n* Current binaries display the full commit hash in the log files.\n  To get the git commit hash of the current checkout,\n  use `git rev-parse HEAD`.\n  \n* 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\n  or TCP incompatibilities between OSes.\n  It's likely benign if you see throughput and latency drop\n  to idle values after the tests in the graph.\n\n* The up and down latency measurement rely on symmetric stable latency\nmeasurements to the server.\nThese values may be wrong if those assumption don't hold on test startup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoxc%2Fcrusader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoxc%2Fcrusader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoxc%2Fcrusader/lists"}