diff options
author | cyqsimon <28627918+cyqsimon@users.noreply.github.com> | 2024-04-16 16:04:16 +0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-04-16 16:04:16 +0800 |
commit | f98c5c9cd6662eece985321d323a3e0f2fecb11d (patch) | |
tree | 7c2201834f676e82efd3459ba05f2adf77bca1e6 | |
parent | 6abfceb9f4d31e7b0fb59a415f48fed36ebccede (diff) |
Update README (#407)
* Update README
* Write changelog
-rw-r--r-- | CHANGELOG.md | 1 | ||||
-rw-r--r-- | INSTALL.md | 83 | ||||
-rw-r--r-- | README.md | 160 |
3 files changed, 145 insertions, 99 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index ca6c8b7..bc98dfd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) * CI: Configure dependabot grouping #395 - @cyqsimon * CI refactor #399 - @cyqsimon * CI: Temporarily disable UI tests #406 - @cyqsimon +* Update README #407 - @cyqsimon ## Removed 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,16 +13,9 @@ 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) - - [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) - - [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) @@ -51,113 +44,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 -``` - -### 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 +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-gnu</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 -``` -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. @@ -170,7 +132,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 @@ -186,7 +148,7 @@ bandwhich - Require privilege escalation every time. - Do this if you are an administrator of a multi-user environment. -```bash +```sh sudo bandwhich ``` |