diff options
| -rw-r--r-- | .github/dependabot.yml | 10 | ||||
| -rw-r--r-- | .github/workflows/ci.yaml | 155 | ||||
| -rw-r--r-- | .github/workflows/release.yaml | 47 | ||||
| -rw-r--r-- | CHANGELOG.md | 14 | ||||
| -rw-r--r-- | Cargo.lock | 34 | ||||
| -rw-r--r-- | Cargo.toml | 17 | ||||
| -rw-r--r-- | Cross.toml | 2 | ||||
| -rw-r--r-- | INSTALL.md | 83 | ||||
| -rw-r--r-- | README.md | 194 | ||||
| -rw-r--r-- | res/bandwhich-inkscape.svg | 481 | ||||
| -rw-r--r-- | res/bandwhich.svg | 1 | ||||
| -rw-r--r-- | src/display/components/display_bandwidth.rs | 12 | ||||
| -rw-r--r-- | src/display/components/snapshots/bandwhich__display__components__display_bandwidth__tests__bandwidth_formatting.snap | 1497 | ||||
| -rw-r--r-- | src/tests/cases/mod.rs | 1 | ||||
| -rw-r--r-- | src/tests/cases/test_utils.rs | 2 |
15 files changed, 1602 insertions, 948 deletions
diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 6560351..c6dcf29 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -9,3 +9,13 @@ updates: dependencies: patterns: - "*" + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: monthly + open-pull-requests-limit: 30 + groups: + github-actions: + patterns: + - "*" + diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 19fbac6..8e01f19 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -22,21 +22,93 @@ jobs: id: get_msrv run: rg '^\s*rust-version\s*=\s*"(\d+(\.\d+){0,2})"' --replace 'msrv=$1' Cargo.toml >> "$GITHUB_OUTPUT" + check-fmt: + name: Check code formatting + runs-on: ubuntu-latest + needs: get-msrv + strategy: + fail-fast: false + matrix: + rust: + - ${{ needs.get-msrv.outputs.msrv }} + - stable + - nightly + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install Rust + uses: dtolnay/rust-toolchain@master + with: + toolchain: ${{ matrix.rust }} + components: rustfmt + + - name: Check formatting + run: cargo fmt --all -- --check + test: - name: test + name: Test on each target needs: get-msrv env: + # use sccache + # It's too much of a hassle to set up sccache in cross. + # See https://github.com/cross-rs/cross/wiki/Recipes#sccache. + SCCACHE_GHA_ENABLED: ${{ matrix.cargo == 'cargo' && 'true' || 'false'}} + RUSTC_WRAPPER: ${{ matrix.cargo == 'cargo' && 'sccache' || '' }} # Emit backtraces on panics. RUST_BACKTRACE: 1 runs-on: ${{ matrix.os }} strategy: fail-fast: false matrix: - os: [ubuntu-latest, macos-latest, windows-latest] + build: + - android-aarch64 + - linux-aarch64-gnu + - linux-aarch64-musl + - linux-armv7-gnueabihf + - linux-armv7-musleabihf + - linux-x64-gnu + - linux-x64-musl + - macos-aarch64 + - macos-x64 + - windows-x64-msvc rust: - ${{ needs.get-msrv.outputs.msrv }} - stable - nightly + include: + - os: ubuntu-latest # default + - cargo: cargo # default; overwrite with `cross` if necessary + - build: android-aarch64 + target: aarch64-linux-android + cargo: cross + - build: linux-aarch64-gnu + target: aarch64-unknown-linux-gnu + cargo: cross + - build: linux-aarch64-musl + target: aarch64-unknown-linux-musl + cargo: cross + - build: linux-armv7-gnueabihf + target: armv7-unknown-linux-gnueabihf + cargo: cross + - build: linux-armv7-musleabihf + target: armv7-unknown-linux-musleabihf + cargo: cross + - build: linux-x64-gnu + target: x86_64-unknown-linux-gnu + - build: linux-x64-musl + target: x86_64-unknown-linux-musl + - build: macos-aarch64 + # Go back ot `macos-latest` after migration is complete + # See https://github.blog/changelog/2024-04-01-macos-14-sonoma-is-generally-available-and-the-latest-macos-runner-image/. + os: macos-14 + target: aarch64-apple-darwin + - build: macos-x64 + os: macos-14 + target: x86_64-apple-darwin + - build: windows-x64-msvc + os: windows-latest + target: x86_64-pc-windows-msvc steps: - name: Checkout repository uses: actions/checkout@v4 @@ -45,26 +117,31 @@ jobs: uses: dtolnay/rust-toolchain@master with: toolchain: ${{ matrix.rust }} - components: rustfmt, clippy - - - name: Install Cross on Ubuntu - if: matrix.os == 'ubuntu-latest' - # The latest realese of `cross` is not able to build/link for `aarch64-linux-android` + targets: ${{ matrix.target }} + components: clippy + + - name: Set up sccache + # It's too much of a hassle to set up sccache in cross. + # See https://github.com/cross-rs/cross/wiki/Recipes#sccache. + if: matrix.cargo == 'cargo' + uses: mozilla-actions/sccache-action@v0.0.4 + + - name: Install cross + if: matrix.cargo == 'cross' + # The latest release of `cross` is not able to build/link for `aarch64-linux-android` # See: https://github.com/cross-rs/cross/issues/1222 # This is fixed on `main` but not yet released. To avoid a breakage somewhen in the future # pin the cross revision used to the latest HEAD at 04/2024. - # Remove the git source and revision once cross 0.3 is released. - run: cargo install --git https://github.com/cross-rs/cross.git --rev 085092c cross - - - name: Check formatting - run: cargo fmt --all -- --check + # Go back to taiki-e/install-action once cross 0.3 is released. + uses: taiki-e/cache-cargo-install-action@v1 + with: + tool: cross + git: https://github.com/cross-rs/cross.git + rev: 085092c - name: Build - run: cargo build --verbose - - - name: Build target aarch64-linux-android - if: matrix.os == 'ubuntu-latest' - run: cross build --target aarch64-linux-android --verbose + id: build + run: ${{ matrix.cargo }} build --verbose --target ${{ matrix.target }} # This is useful for debugging problems when the expected build artifacts # (like shell completions and man pages) aren't generated. @@ -72,7 +149,7 @@ jobs: shell: bash run: | # it's probably okay to assume no spaces? - STDERR_FILES=$(find "./target/debug" -name stderr | grep bandwhich) + STDERR_FILES=$(find "./target/debug" -name stderr | grep bandwhich || true) for FILE in $STDERR_FILES; do echo "::group::$FILE" cat "$FILE" @@ -80,15 +157,10 @@ jobs: done - name: Run clippy - run: cargo clippy --all-targets --all-features -- -D warnings - - - name: Install cargo-insta - uses: taiki-e/install-action@v2 - with: - tool: cargo-insta + run: ${{ matrix.cargo }} clippy --all-targets --target ${{ matrix.target }} -- -D warnings - name: Install npcap on Windows - # PRs from other repositories cannot not be trusted with repository secrets + # PRs from other repositories cannot be trusted with repository secrets if: matrix.os == 'windows-latest' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) env: NPCAP_OEM_URL: ${{ secrets.NPCAP_OEM_URL }} @@ -98,7 +170,7 @@ jobs: # see https://stackoverflow.com/a/1674950/5637701 & "$env:TEMP/npcap-oem.exe" /S - - name: Run tests using cargo-insta + - name: Run tests id: run_tests # npcap is needed to run tests on Windows, so unfortunately we cannot run tests # on PRs from other repositories @@ -106,34 +178,21 @@ jobs: env: # make insta generate new snapshots in CI INSTA_UPDATE: new - run: cargo insta test --color=never + run: ${{ matrix.cargo }} test --all-targets --target ${{ matrix.target }} - name: Upload snapshots of failed tests if: ${{ failure() && steps.run_tests.outcome == 'failure' }} - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: ${{ matrix.os }}-${{ matrix.rust }}-failed_snapshots path: '**/*.snap.new' - - name: Upload android binary - if: ${{ matrix.os == 'ubuntu-latest' && ( success() || steps.build.outcome == 'success' ) }} - uses: actions/upload-artifact@v3 - with: - name: aarch64-linux-android-${{ matrix.rust }} - path: target/aarch64-linux-android/debug/bandwhich - - - name: Upload unix binary - if: ${{ matrix.os != 'windows-latest' && ( success() || steps.build.outcome == 'success' ) }} - uses: actions/upload-artifact@v3 - with: - name: ${{ matrix.os }}-${{ matrix.rust }} - path: target/debug/bandwhich - - - name: Upload windows binary - if: ${{ matrix.os == 'windows-latest' && ( success() || steps.build.outcome == 'success' ) }} - uses: actions/upload-artifact@v3 + - name: Upload binaries + if: ${{ success() || steps.build.outcome == 'success' }} + uses: actions/upload-artifact@v4 with: - name: ${{ matrix.os }}-${{ matrix.rust }} + name: ${{ matrix.target }}-${{ matrix.rust }} path: | - target/debug/bandwhich.exe - target/debug/bandwhich.pdb + target/${{ matrix.target }}/debug/bandwhich + target/${{ matrix.target }}/debug/bandwhich.exe + target/${{ matrix.target }}/debug/bandwhich.pdb diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 630cadd..7831491 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -52,25 +52,45 @@ jobs: strategy: matrix: build: - - aarch64-linux-android + - android-aarch64 + - linux-aarch64-gnu + - linux-aarch64-musl + - linux-armv7-gnueabihf + - linux-armv7-musleabihf - linux-x64-gnu - linux-x64-musl + - macos-aarch64 - macos-x64 - windows-x64-msvc include: + - os: ubuntu-latest # default - cargo: cargo # default; overwrite with `cross` if necessary - - build: aarch64-linux-android - os: ubuntu-latest + - build: android-aarch64 target: aarch64-linux-android cargo: cross + - build: linux-aarch64-gnu + target: aarch64-unknown-linux-gnu + cargo: cross + - build: linux-aarch64-musl + target: aarch64-unknown-linux-musl + cargo: cross + - build: linux-armv7-gnueabihf + target: armv7-unknown-linux-gnueabihf + cargo: cross + - build: linux-armv7-musleabihf + target: armv7-unknown-linux-musleabihf + cargo: cross - build: linux-x64-gnu - os: ubuntu-latest target: x86_64-unknown-linux-gnu - build: linux-x64-musl - os: ubuntu-latest target: x86_64-unknown-linux-musl + - build: macos-aarch64 + # Go back ot `macos-latest` after migration is complete + # See https://github.blog/changelog/2024-04-01-macos-14-sonoma-is-generally-available-and-the-latest-macos-runner-image/. + os: macos-14 + target: aarch64-apple-darwin - build: macos-x64 - os: macos-latest + os: macos-14 target: x86_64-apple-darwin - build: windows-x64-msvc os: windows-latest @@ -86,13 +106,18 @@ jobs: toolchain: stable targets: ${{ matrix.target }} - - name: Install musl-tools - if: matrix.target == 'x86_64-unknown-linux-musl' - run: sudo apt-get install -y --no-install-recommends musl-tools - - name: Install cross if: matrix.cargo == 'cross' - run: cargo install --git https://github.com/cross-rs/cross.git --rev 085092c cross + # The latest release of `cross` is not able to build/link for `aarch64-linux-android` + # See: https://github.com/cross-rs/cross/issues/1222 + # This is fixed on `main` but not yet released. To avoid a breakage somewhen in the future + # pin the cross revision used to the latest HEAD at 04/2024. + # Go back to taiki-e/install-action once cross 0.3 is released. + uses: taiki-e/cache-cargo-install-action@v1 + with: + tool: cross + git: https://github.com/cross-rs/cross.git + rev: 085092c - name: Build release binary shell: bash diff --git a/CHANGELOG.md b/CHANGELOG.md index 514557b..debb559 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,19 +13,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) * Remove unnecessary logging synchronisation #381 - @cyqsimon * Apply suggestions from new clippy lint clippy::assigning_clones #382 - @cyqsimon * Fix IPv6 socket detect logic #383 - @cyqsimon -* Support build for `target_os`` `android` #384 - @flxo +* Support build for `target_os` `android` #384 - @flxo +* Fix Windows FP discrepancy issue in test #400 - @cyqsimon ## Added * CI: include generated assets in release archive #359 - @cyqsimon * Add PID column to the process table #379 - @notjedi * CI: add builds for target `aarch64-linux-android` #384 - @flxo +* CI: Keep GitHub Actions up to date with GitHub's Dependabot #403 - @cclauss +* CI: Enable more cross-compiled builds #401 - @cyqsimon +* CI: use sccache to speed up CI #408 - @cyqsimon ## Changed * CI: strip release binaries for all targets #358 - @cyqsimon * Bump MSRV to 1.74 (required by clap 4.5; see #373) * CI: Configure dependabot grouping #395 - @cyqsimon +* CI refactor #399 - @cyqsimon +* CI: Temporarily disable UI tests #406 - @cyqsimon +* Update README #407 - @cyqsimon +* Update usage in README #409 - @cyqsimon + +## Removed + +* CI: Remove musl-tools install step #402 - @cyqsimon ## [0.22.2] - 2024-01-28 @@ -120,18 +120,18 @@ dependencies = [ [[package]] name = "anyhow" -version = "1.0.81" +version = "1.0.82" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0952808a6c2afd1aa8947271f3a60f1a6763c7b912d210184c5149b5cf147247" +checksum = "f538837af36e6f6a9be0faa67f9a314f8119e4e4b5867c6ab40ed60360142519" dependencies = [ "backtrace", ] [[package]] name = "async-trait" -version = "0.1.79" +version = "0.1.80" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a507401cad91ec6a857ed5513a2073c82a9b9048762b885bb98655b306964681" +checksum = "c6fa2087f2753a7da8cc1c0dbfcf89579dd57458e36769de5ac750b4671737ca" dependencies = [ "proc-macro2", "quote", @@ -297,9 +297,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" [[package]] name = "chrono" -version = "0.4.37" +version = "0.4.38" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8a0d04d43504c61aa6c7531f1871dd0d418d91130162063b789da00fd7057a5e" +checksum = "a21f936df1771bf62b77f047b726c4625ff2e8aa607c01ec06e5a05bd8463401" dependencies = [ "android-tzdata", "iana-time-zone", @@ -353,9 +353,9 @@ dependencies = [ [[package]] name = "clap_complete" -version = "4.5.1" +version = "4.5.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "885e4d7d5af40bfb99ae6f9433e292feac98d452dcb3ec3d25dfe7552b77da8c" +checksum = "dd79504325bf38b10165b02e89b4347300f855f273c4cb30c4a3209e6583275e" dependencies = [ "clap", ] @@ -1471,9 +1471,9 @@ dependencies = [ [[package]] name = "ratatui" -version = "0.26.1" +version = "0.26.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bcb12f8fbf6c62614b0d56eb352af54f6a22410c3b079eb53ee93c7b97dd31d8" +checksum = "a564a852040e82671dc50a37d88f3aa83bbc690dfc6844cfe7a2591620206a80" dependencies = [ "bitflags 2.4.2", "cassowary", @@ -1571,9 +1571,9 @@ checksum = "b833d8d034ea094b1ea68aa6d5c740e0d04bad9d16568d08ba6f76823a114316" [[package]] name = "rstest" -version = "0.18.2" +version = "0.19.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "97eeab2f3c0a199bc4be135c36c924b6590b88c377d416494288c14f2db30199" +checksum = "9d5316d2a1479eeef1ea21e7f9ddc67c191d497abc8fc3ba2467857abbb68330" dependencies = [ "futures", "futures-timer", @@ -1583,9 +1583,9 @@ dependencies = [ [[package]] name = "rstest_macros" -version = "0.18.2" +version = "0.19.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d428f8247852f894ee1be110b375111b586d4fa431f6c46e64ba5a0dcccbe605" +checksum = "04a9df72cc1f67020b0d63ad9bfe4a323e459ea7eb68e03bd9824db49f9a4c25" dependencies = [ "cfg-if", "glob", @@ -1798,12 +1798,12 @@ dependencies = [ [[package]] name = "stability" -version = "0.1.1" +version = "0.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ebd1b177894da2a2d9120208c3386066af06a488255caabc5de8ddca22dbc3ce" +checksum = "2ff9eaf853dec4c8802325d8b6d3dffa86cc707fd7a1a4cdbf416e13b061787a" dependencies = [ "quote", - "syn 1.0.109", + "syn 2.0.48", ] [[package]] @@ -20,9 +20,14 @@ repository = "https://github.com/imsnif/bandwhich" rust-version = "1.74.0" description = "Display current network utilization by process, connection and remote IP/hostname" +[features] +default = [] +# UI tests temporarily disabled by default, until big refactor is done +ui_test = [] + [dependencies] -anyhow = { version = "1.0.81", features = ["backtrace"] } -async-trait = "0.1.79" +anyhow = { version = "1.0.82", features = ["backtrace"] } +async-trait = "0.1.80" chrono = "0.4" clap-verbosity-flag = "2.2.0" clap = { version = "4.5.4", features = ["derive"] } @@ -34,7 +39,7 @@ log = "0.4.21" once_cell = "1.19.0" pnet = "0.34.0" pnet_macros_support = "0.34.0" -ratatui = "0.26.1" +ratatui = "0.26.2" resolv-conf = "0.7.0" simplelog = "0.12.2" thiserror = "1.0.58" @@ -58,13 +63,13 @@ insta = "1.38.0" packet-builder = { version = "0.7.0", git = "https://github.com/cyqsimon/packet_builder.git", branch = "patch-update" } pnet_base = "0.34.0" regex = "1.10.4" -rstest = "0.18.2" +rstest = "0.19.0" [build-dependencies] -anyhow = "1.0.81" +anyhow = "1.0.82" clap = { version = "4.5.4", features = ["derive"] } clap-verbosity-flag = "2.2.0" -clap_complete = "4.5.1" +clap_complete = "4.5.2" clap_mangen = "0.2.20" derivative = "2.2.0" strum = { version = "0.26.2", features = ["derive"] } diff --git a/Cross.toml b/Cross.toml new file mode 100644 index 0000000..07a5627 --- /dev/null +++ b/Cross.toml @@ -0,0 +1,2 @@ +[build.env] +passthrough = ["BANDWHICH_GEN_DIR"] diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..e3e438b --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,83 @@ +# Installation + +- [Installation](#installation) + - [Arch Linux](#arch-linux) + - [Exherbo Linux](#exherbo-linux) + - [Nix/NixOS](#nixnixos) + - [Void Linux](#void-linux) + - [Fedora](#fedora) + - [macOS/Linux (using Homebrew)](#macoslinux-using-homebrew) + - [macOS (using MacPorts)](#macos-using-macports) + - [FreeBSD](#freebsd) + - [Cargo](#cargo) + +## Arch Linux + +``` +pacman -S bandwhich +``` + +## Exherbo Linux + +`bandwhich` is available in [rust repository](https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/sys-apps/bandwhich), and can be installed via `cave`: + +``` +cave resolve -x repository/rust +cave resolve -x bandwhich +``` + +## Nix/NixOS + +`bandwhich` is available in [`nixpkgs`](https://github.com/nixos/nixpkgs/blob/master/pkgs/tools/networking/bandwhich/default.nix), and can be installed, for example, with `nix-env`: + +``` +nix-env -iA nixpkgs.bandwhich +``` + +## Void Linux + +``` +xbps-install -S bandwhich +``` + +## Fedora + +`bandwhich` is available in [COPR](https://copr.fedorainfracloud.org/coprs/atim/bandwhich/), and can be installed via DNF: + +``` +sudo dnf copr enable atim/bandwhich -y && sudo dnf install bandwhich +``` + +## macOS/Linux (using Homebrew) + +``` +brew install bandwhich +``` + +## macOS (using MacPorts) + +``` +sudo port selfupdate +sudo port install bandwhich +``` + +## FreeBSD + +``` +pkg install bandwhich +``` + +or + +``` +cd /usr/ports/net-mgmt/bandwhich && make install clean +``` + +## Cargo + +Regardless of OS, you can always fallback to the Rust package manager, `cargo`. +For installation instructions of the Rust toolchain, see [here](https://www.rust-lang.org/tools/install). + +``` +cargo install bandwhich +``` @@ -13,22 +13,15 @@ This is a CLI utility for displaying current network utilization by process, con - [Installation](#installation) - [Downstream packaging status](#downstream-packaging-status) - [Download a prebuilt binary](#download-a-prebuilt-binary) - - [Arch Linux](#arch-linux) - - [Nix/NixOS](#nixnixos) - - [Void Linux](#void-linux) - - [Fedora](#fedora) - - [macOS/Linux (using Homebrew)](#macoslinux-using-homebrew) - - [macOS (using MacPorts)](#macos-using-macports) - - [FreeBSD](#freebsd) - - [Building from source using `cargo`](#building-from-source-using-cargo) - - [OpenWRT](#openwrt) + - [Building from source](#building-from-source) + - [Cross-compiling](#cross-compiling) + - [Android](#android) - [Post install (Linux)](#post-install-linux) - [1. `setcap`](#1-setcap) - [Capabilities explained](#capabilities-explained) - [2. `sudo` (or alternative)](#2-sudo-or-alternative) - [Post install (Windows)](#post-install-windows) - [Usage](#usage) - - [raw\_mode](#raw_mode) - [Contributing](#contributing) - [License](#license) @@ -50,104 +43,82 @@ For more details, see [The Future of Bandwhich #275](https://github.com/imsnif/b ### Downstream packaging status +For detailed instructions for each platform, see [INSTALL.md](INSTALL.md). + <a href="https://repology.org/project/bandwhich/versions"> <img src="https://repology.org/badge/vertical-allrepos/bandwhich.svg?columns=3" alt="Packaging status"> </a> ### Download a prebuilt binary -If you're on `android` or `linux`, you can download the generic binary from the [releases](https://github.com/imsnif/bandwhich/releases) - -### Arch Linux - -``` -pacman -S bandwhich -``` - -### Nix/NixOS - -`bandwhich` is available in [`nixpkgs`](https://github.com/nixos/nixpkgs/blob/master/pkgs/tools/networking/bandwhich/default.nix), and can be installed, for example, with `nix-env`: - -``` -nix-env -iA nixpkgs.bandwhich -``` - -### Void Linux - -``` -xbps-install -S bandwhich -``` - -### Fedora - -`bandwhich` is available in [COPR](https://copr.fedorainfracloud.org/coprs/atim/bandwhich/), and can be installed via DNF: - -``` -sudo dnf copr enable atim/bandwhich -y && sudo dnf install bandwhich -``` - -### macOS/Linux (using Homebrew) - -``` -brew install bandwhich -``` - -### macOS (using MacPorts) +We offer several generic binaries in [releases](https://github.com/imsnif/bandwhich/releases) for various OSes. + +<table> + <thead> + <th>OS</th><th>Architecture</th><th>Support</th><th>Usage</th> + </thead> + <tbody> + <tr> + <td>Android</td><td>aarch64</td><td>Best effort</td> + <td> + <p>All modern Android devices.</p> + <p>Note that this is a pure binary file, not an APK suitable for general usage.</p> + </td> + </tr> + <tr> + <td rowspan="3">Linux</td><td>aarch64</td><td>Full</td> + <td>64-bit ARMv8+ (servers, some modern routers, RPi-4+).</td> + </tr> + <tr> + <td>armv7hf</td><td>Best effort</td><td>32-bit ARMv7 (older routers, pre-RPi-4).</td> + </tr> + <tr> + <td>x64</td><td>Full</td> + <td>Most Linux desktops & servers.</td> + </tr> + <tr> + <td rowspan="2">MacOS</td><td>aarch64</td><td rowspan="2">Full</td> + <td>Apple silicon Macs (2021+).</td> + </tr> + <tr> + <td>x64</td> + <td>Intel Macs (pre-2021).</td> + </tr> + <tr> + <td>Windows</td><td>x64</td><td>Full</td> + <td>Most Windows desktops & servers.</td> + </tr> + </tbody> +</table> + +## Building from source -``` -sudo port selfupdate -sudo port install bandwhich -``` - -### FreeBSD - -``` -pkg install bandwhich -``` - -or - -``` -cd /usr/ports/net-mgmt/bandwhich && make install clean +```sh +git clone https://github.com/imsnif/bandwhich.git +cd bandwhich +cargo build --release ``` -### Building from source using `cargo` +For the up-to-date minimum supported Rust version, please refer to the `rust-version` field in [Cargo.toml](Cargo.toml). -`bandwhich` can be installed using the Rust package manager, `cargo`. -It might be in your distro repositories if you're on linux, or you can install it via [rustup](https://rustup.rs/). -You can find additional installation instructions [here](https://doc.rust-lang.org/book/ch01-01-installation.html). +### Cross-compiling -The minimum supported Rust version is **1.70.0**. +Cross-compiling for alternate targets is supported via [cross](https://github.com/cross-rs/cross). Here's the rough procedure: -``` -cargo install bandwhich -``` +1. Check the target architecture. If on Linux, you can use `uname -m`. +2. Lookup [rustc platform support](https://doc.rust-lang.org/rustc/platform-support.html) for the corresponding target triple. +3. [Install `cross`](https://github.com/cross-rs/cross#installation). +4. Run `cross build --release --target <TARGET_TRIPLE>`. -#### Building from source for Android (`aarch64-linux-android`) +#### Android -Building for target `aarch64-linux-android` is supported via [cross](https://github.com/cross-rs/cross). Until [#1222](https://github.com/cross-rs/cross/issues/1222) is solved, use the latest HEAD: +Until [cross-rs/cross#1222](https://github.com/cross-rs/cross/issues/1222) is solved, use the latest HEAD: ```sh cargo install --git https://github.com/cross-rs/cross.git cross cross build --release --target aarch64-linux-android ``` -Kindly be aware that this process generates a pure binary file and not an APK suitable for installation on any arbitrary Android device. - -The Android support for bandwhich beyond its build is *not* endorsed by this project and may be unstable or non-functional. - -### OpenWRT - -To install `bandwhich` on OpenWRT, you'll need to compile a binary that would fit its processor architecture. This might mean you would have to cross compile if, for example, you're working on an `x86_64` and the OpenWRT is installed on an `arm7`. -Here is an example of cross compiling in this situation: - -- Check the processor architecture of your router by using `uname -m` -- Clone the bandwhich repository `git clone https://github.com/imsnif/bandwhich` -- Install `cross` using `cargo install cross` -- build the `bandwhich` package using `cross build --target armv7-unknown-linux-musleabihf` -- Copy the binary files from `target/armv7-unknown-linux-musleabihf/debug/bandwhich` to the router using `scp` by running `scp bandwhich root@192.168.1.1:~/` (here, 192.168.1.1 would be the IP address of your router). -- Finally enter the router using ssh and run the binary directly with `./bandwhich` - ## Post install (Linux) Since `bandwhich` sniffs network packets, it requires elevated privileges. @@ -160,7 +131,7 @@ On Linux, there are two main ways to accomplish this: - This is the **recommended** setup **for single user machines**, or **if all users are trusted**. - This is **not recommended** if you want to **ensure users cannot see others' traffic**. -```bash +```sh # assign capabilities sudo setcap cap_sys_ptrace,cap_dac_read_search,cap_net_raw,cap_net_admin+ep $(command -v bandwhich) # run as unprivileged user @@ -176,7 +147,7 @@ bandwhich - Require privilege escalation every time. - Do this if you are an administrator of a multi-user environment. -```bash +```sh sudo bandwhich ``` @@ -197,31 +168,24 @@ You might need to first install [npcap](https://npcap.com/#download) for capturi ## Usage ``` -USAGE: - bandwhich [FLAGS] [OPTIONS] - -FLAGS: - -a, --addresses Show remote addresses table only - -c, --connections Show connections table only - -h, --help Prints help information - -n, --no-resolve Do not attempt to resolve IPs to their hostnames - -p, --processes Show processes table only - -r, --raw Machine friendlier output - -s, --show-dns Show DNS queries - -t, --total-utilization Show total (cumulative) usages - -V, --version Prints version information - -OPTIONS: - -i, --interface <interface> The network interface to listen on, eg. eth0 - -d, --dns-server <dns-server> A dns server ip to use instead of the system default -``` - -## raw_mode - -`bandwhich` also supports an easier-to-parse mode that can be piped or redirected to a file. For example, try: - -``` -bandwhich --raw | grep firefox +Usage: bandwhich [OPTIONS] + +Options: + -i, --interface <INTERFACE> The network interface to listen on, eg. eth0 + -r, --raw Machine friendlier output + -n, --no-resolve Do not attempt to resolve IPs to their hostnames + -s, --show-dns Show DNS queries + -d, --dns-server <DNS_SERVER> A dns server ip to use instead of the system default + --log-to <LOG_TO> Enable debug logging to a file + -v, --verbose... Increase logging verbosity + -q, --quiet... Decrease logging verbosity + -p, --processes Show processes table only + -c, --connections Show connections table only + -a, --addresses Show remote addresses table only + -u, --unit-family <UNIT_FAMILY> Choose a specific family of units [default: bin-bytes] [possible values: bin-bytes, bin-bits, si-bytes, si-bits] + -t, --total-utilization Show total (cumulative) usages + -h, --help Print help (see more with '--help') + -V, --version Print version ``` ## Contributing diff --git a/res/bandwhich-inkscape.svg b/res/bandwhich-inkscape.svg new file mode 100644 index 0000000..a126bc3 --- /dev/null +++ b/res/bandwhich-inkscape.svg @@ -0,0 +1,481 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + width="112.77547mm" + height="105.83332mm" + viewBox="0 0 112.77548 105.83332" + version="1.1" + id="svg1" + inkscape:version="1.3 (0e150ed6c4, 2023-07-21)" + sodipodi:docname="bandwhich.svg" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg"> + <sodipodi:namedview + id="namedview1" + pagecolor="#ffffff" + bordercolor="#eeeeee" + borderopacity="1" + inkscape:showpageshadow="0" + inkscape:pageopacity="0" + inkscape:pagecheckerboard="true" + inkscape:deskcolor="#d1d1d1" + inkscape:document-units="px" + showborder="false" + borderlayer="false" + inkscape:zoom="1.4069592" + inkscape:cx="187.28333" + inkscape:cy="114.0758" + inkscape:window-width="1920" + inkscape:window-height="1005" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" + inkscape:current-layer="layer1" /> + <defs + id="defs1"> + <inkscape:path-effect + effect="powermask" + id="path-effect502" + is_visible="true" + lpeversion="1" + uri="#mask-powermask-path-effect502" + invert="false" + hide_mask="false" + background="false" + background_color="#ffffffff" /> + <inkscape:path-effect + effect="powermask" + id="path-effect130" + is_visible="true" + lpeversion="1" + uri="#mask-powermask-path-effect130" + invert="false" + hide_mask="false" + background="false" + background_color="#ffffffff" /> + <filter + id="mask-powermask-path-effect76_inverse" + inkscape:label="filtermask-powermask-path-effect76" + style="color-interpolation-filters:sRGB" + height="100" + width="100" + x="-50" + y="-50"> + <feColorMatrix + id="mask-powermask-path-effect76_primitive1" + values="1" + type="saturate" + result="fbSource |
