mirror of
https://github.com/imsnif/bandwhich.git
synced 2026-02-08 17:49:19 +08:00
cyqsimon
@@ -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
|
||||
|
||||
|
||||
83
INSTALL.md
Normal file
83
INSTALL.md
Normal file
@@ -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
|
||||
```
|
||||
158
README.md
158
README.md
@@ -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)
|
||||
We offer several generic binaries in [releases](https://github.com/imsnif/bandwhich/releases) for various OSes.
|
||||
|
||||
### Arch Linux
|
||||
<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>
|
||||
|
||||
```
|
||||
pacman -S bandwhich
|
||||
## Building from source
|
||||
|
||||
```sh
|
||||
git clone https://github.com/imsnif/bandwhich.git
|
||||
cd bandwhich
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### Exherbo Linux
|
||||
For the up-to-date minimum supported Rust version, please refer to the `rust-version` field in [Cargo.toml](Cargo.toml).
|
||||
|
||||
`bandwhich` is available in [rust repository](https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/sys-apps/bandwhich), and can be installed via `cave`:
|
||||
### Cross-compiling
|
||||
|
||||
```
|
||||
cave resolve -x repository/rust
|
||||
cave resolve -x bandwhich
|
||||
```
|
||||
Cross-compiling for alternate targets is supported via [cross](https://github.com/cross-rs/cross). Here's the rough procedure:
|
||||
|
||||
### Nix/NixOS
|
||||
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>`.
|
||||
|
||||
`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`:
|
||||
#### Android
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### Building from source using `cargo`
|
||||
|
||||
`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).
|
||||
|
||||
The minimum supported Rust version is **1.70.0**.
|
||||
|
||||
```
|
||||
cargo install bandwhich
|
||||
```
|
||||
|
||||
#### Building from source for Android (`aarch64-linux-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
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user