English | 简体中文
# Installation Guide This guide covers all installation methods for RustNet across different platforms. > **Tip:** For an at-a-glance view of which distributions package RustNet and which version each carries, see [RustNet on Repology](https://repology.org/project/rustnet/versions). ## Table of Contents - [Installing from Release Packages](#installing-from-release-packages) - [macOS DMG Installation](#macos-dmg-installation) - [Windows MSI Installation](#windows-msi-installation) - [Windows Chocolatey Installation](#windows-chocolatey-installation) - [Linux Package Installation](#linux-package-installation) - [FreeBSD Installation](#freebsd-installation) - [Android (Termux) Installation](#android-termux-installation) - [Install via Cargo](#install-via-cargo) - [Building from Source](#building-from-source) - [Using Docker](#using-docker) - [Prerequisites](#prerequisites) - [Permissions Setup](#permissions-setup) - [GeoIP Databases (Optional)](#geoip-databases-optional) - [Troubleshooting](#troubleshooting) ## Installing from Release Packages Pre-built packages are available for each release on the [GitHub Releases](https://github.com/domcyrus/rustnet/releases) page. ### macOS DMG Installation > ** Prefer Homebrew?** If you have Homebrew installed, using `brew install` is easier and avoids Gatekeeper bypass steps. See [Homebrew Installation](#homebrew-installation) for instructions. 1. **Download** the appropriate DMG for your architecture: - `Rustnet_macOS_AppleSilicon.dmg` for Apple Silicon Macs (M1/M2/M3) - `Rustnet_macOS_Intel.dmg` for Intel-based Macs 2. **Open the DMG** and drag Rustnet.app to your Applications folder 3. **Bypass Gatekeeper** (for unsigned builds): - When you first try to open RustNet, macOS will block it because the app is not signed - Go to **System Settings → Privacy & Security** - Scroll down to find the message about RustNet being blocked - Click **"Open Anyway"** to allow the application to run - You may need to confirm this choice when launching the app again 4. **Run RustNet**: - Double-click Rustnet.app to launch it in a Terminal window with sudo - Or run from command line: `sudo /Applications/Rustnet.app/Contents/MacOS/rustnet` 5. **Optional: Create a symlink for shell access**: ```bash # Create a symlink so you can run 'rustnet' from anywhere sudo ln -s /Applications/Rustnet.app/Contents/MacOS/rustnet /usr/local/bin/rustnet # Now you can run from any terminal: sudo rustnet ``` 6. **Optional: Setup BPF permissions** (to avoid needing sudo): - Install Wireshark's BPF permission helper: `brew install --cask wireshark-chmodbpf` - Log out and back in for group changes to take effect - See the [Permissions Setup](#permissions-setup) section for detailed instructions ### Windows MSI Installation 1. **Install Npcap Runtime** (required for packet capture): - Download from https://npcap.com/dist/ - Run the installer and select **"WinPcap API compatible mode"** 2. **Download and install** the appropriate MSI package: - `Rustnet_Windows_64-bit.msi` for 64-bit Windows - `Rustnet_Windows_32-bit.msi` for 32-bit Windows 3. **Run the installer** and follow the installation wizard 4. **Run RustNet**: - Open Command Prompt or PowerShell - Run: `rustnet.exe` - If Npcap is not installed or not in WinPcap compatible mode, RustNet will display a helpful error message with installation instructions - Note: Depending on your Npcap installation settings, you may or may not need Administrator privileges ### Windows Chocolatey Installation The easiest way to install RustNet on Windows is via [Chocolatey](https://community.chocolatey.org/packages/rustnet): ```powershell # Run in Administrator PowerShell choco install rustnet ``` **Note:** You still need to install [Npcap](https://npcap.com) separately with "WinPcap API compatible mode" enabled. ### Linux Package Installation #### Ubuntu PPA (Recommended for Ubuntu 25.10 Questing and 26.04 LTS Resolute) The easiest way to install RustNet on Ubuntu is via the official PPA. The PPA publishes builds for the following Ubuntu series: - Ubuntu 25.10 (Questing Quokka) - Ubuntu 26.04 LTS (Resolute Raccoon) ```bash # Add the RustNet PPA sudo add-apt-repository ppa:domcyrus/rustnet # Update package list sudo apt update # Install rustnet sudo apt install rustnet # Run with sudo sudo rustnet # Optional: Grant capabilities to run without sudo (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' /usr/bin/rustnet rustnet ``` **Important:** The PPA supports only the two series listed above (Ubuntu 25.10 Questing and 26.04 LTS Resolute) because the build requires Rust 1.88+ (used for let-chains in the project). Earlier Ubuntu versions don't ship a recent enough `rustc` in their repositories. For older Ubuntu versions, use the [.deb packages](#debianubuntu-deb-packages) from GitHub releases or [build from source](#building-from-source). #### Debian/Ubuntu (.deb packages) For manual installation or non-Ubuntu Debian-based distributions: ```bash # Download the appropriate package for your architecture: # - Rustnet_LinuxDEB_amd64.deb (x86_64) # - Rustnet_LinuxDEB_arm64.deb (ARM64) # - Rustnet_LinuxDEB_armhf.deb (ARMv7) # Install the package (capabilities are automatically configured) sudo dpkg -i Rustnet_LinuxDEB_amd64.deb # Install dependencies if needed sudo apt-get install -f # Run without sudo (capabilities were set by post-install script) rustnet # Verify capabilities getcap /usr/bin/rustnet ``` **Note:** The .deb package automatically sets Linux capabilities via post-install script, so you can run RustNet without sudo. #### RedHat/Fedora/CentOS (.rpm packages) For manual installation or distributions not using COPR: ```bash # Download the appropriate package for your architecture: # - Rustnet_LinuxRPM_x86_64.rpm # - Rustnet_LinuxRPM_aarch64.rpm # Install the package (capabilities are automatically configured) sudo rpm -i Rustnet_LinuxRPM_x86_64.rpm # Or with dnf/yum: sudo dnf install Rustnet_LinuxRPM_x86_64.rpm # Run without sudo (capabilities were set by post-install script) rustnet # Verify capabilities getcap /usr/bin/rustnet ``` **Note:** The .rpm package automatically sets Linux capabilities via post-install script, so you can run RustNet without sudo. #### Arch Linux This package is included in the Arch Linux Extra repository ([link](https://archlinux.org/packages/extra/x86_64/rustnet/)). It can be installed using pacman: ```bash sudo pacman -S rustnet ``` Alternatively, two AUR packages are available: - [`rustnet-bin`](https://aur.archlinux.org/packages/rustnet-bin) - Pre-compiled binary from GitHub Releases - [`rustnet-git`](https://aur.archlinux.org/packages/rustnet-git) - Build from source and use the latest commit (maintained by [@DeepChirp](https://github.com/DeepChirp)) Install with your preferred AUR helper: ```bash # Pre-compiled binary from GitHub Releases yay -S rustnet-bin # OR source build from the latest commit yay -S rustnet-git ``` #### Nix / NixOS RustNet is available in [nixpkgs](https://search.nixos.org/packages?query=rustnet), including the **stable** channels (as well as `nixpkgs-unstable`). **Try it without installing (ephemeral shell):** ```bash nix-shell -p rustnet # Then inside the shell: sudo rustnet ``` **Persistent install on NixOS** — add to `/etc/nixos/configuration.nix`: ```nix environment.systemPackages = with pkgs; [ rustnet ]; ``` Then run `sudo nixos-rebuild switch`. **Note on permissions:** NixOS's `/nix/store` is read-only, so `sudo setcap` on the binary won't persist across rebuilds. The simplest option is `sudo rustnet`. For sudo-less operation, define a NixOS [security.wrappers](https://search.nixos.org/options?channel=unstable&query=security.wrappers) entry that carries the capabilities: ```nix security.wrappers.rustnet = { source = "${pkgs.rustnet}/bin/rustnet"; owner = "root"; group = "root"; capabilities = "cap_net_raw,cap_bpf,cap_perfmon+eip"; }; ``` Then run `rustnet` via the wrapper path (`/run/wrappers/bin/rustnet`). > **Coming soon — dedicated NixOS module.** A [`programs.rustnet` > module](https://github.com/NixOS/nixpkgs/pull/517620) is in review for > nixpkgs. Once merged it wraps exactly the capabilities above for you, so the > whole setup becomes: > > ```nix > programs.rustnet.enable = true; > ``` > > This grants `cap_net_raw`, `cap_bpf`, and `cap_perfmon` (but **not** > `cap_net_admin`, since RustNet never needs promiscuous mode) through > `security.wrappers` — the same pattern `programs.mtr` and > `programs.wireshark` use — letting you run `rustnet` without sudo. #### Fedora (COPR - Recommended for Fedora 42+) The easiest way to install RustNet on Fedora is via the official COPR repository. ```bash # Enable the COPR repository sudo dnf copr enable domcyrus/rustnet # Install rustnet sudo dnf install rustnet # Run with sudo sudo rustnet # Optional: Grant capabilities to run without sudo (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' /usr/bin/rustnet rustnet ``` **Important:** The COPR only supports Fedora 42 and 43 due to the Rust 1.88+ requirement. CentOS and RHEL don't have recent enough Rust compilers in their repositories. For those distributions, use the [.rpm packages](#redhatfedoracentos-rpm-packages) from GitHub releases or [build from source](#building-from-source). #### openSUSE Tumbleweed (OBS) RustNet is built for openSUSE Tumbleweed (x86_64 and aarch64) via the [openSUSE Build Service](https://build.opensuse.org/package/show/home:domcyrus:rustnet/rustnet). ```bash sudo zypper addrepo https://download.opensuse.org/repositories/home:/domcyrus:/rustnet/openSUSE_Tumbleweed/home:domcyrus:rustnet.repo sudo zypper refresh sudo zypper install rustnet # Run with sudo sudo rustnet # Optional: Grant capabilities to run without sudo (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' /usr/bin/rustnet rustnet ``` #### Homebrew Installation **On macOS:** ```bash brew install rustnet # Follow the caveats displayed after installation for permission setup ``` **On Linux:** ```bash brew install rustnet # Grant capabilities to the Homebrew-installed binary (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' $(brew --prefix)/bin/rustnet # Run without sudo rustnet ``` #### Static Binary (Portable - Any Linux Distribution) For maximum portability, static binaries are available that work on **any Linux distribution** regardless of GLIBC version. These are fully self-contained and require no system dependencies. ```bash # Download the static binary for your architecture: # - rustnet-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz (x86_64) # - rustnet-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz (ARM64) # Extract the archive tar xzf rustnet-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz # Move binary to PATH sudo mv rustnet-vX.Y.Z-x86_64-unknown-linux-musl/rustnet /usr/local/bin/ # Grant capabilities (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' /usr/local/bin/rustnet # Run without sudo rustnet ``` **When to use static binaries:** - Older distributions with outdated GLIBC (e.g., CentOS 7, older Ubuntu) - Minimal/containerized environments - Air-gapped systems where installing dependencies is difficult - When you want a single portable binary ### FreeBSD Installation FreeBSD support is available starting from version 0.15.0. #### From Ports or Packages (Future) Once available in FreeBSD ports: ```bash # Using pkg (binary packages) pkg install rustnet # Or build from ports cd /usr/ports/net/rustnet && make install clean ``` #### From GitHub Releases Download the FreeBSD binary from the [rustnet-bsd releases](https://github.com/domcyrus/rustnet-bsd/releases): ```bash # Download the appropriate package fetch https://github.com/domcyrus/rustnet-bsd/releases/download/vX.Y.Z/rustnet-vX.Y.Z-x86_64-unknown-freebsd.tar.gz # Extract the archive tar xzf rustnet-vX.Y.Z-x86_64-unknown-freebsd.tar.gz # Move binary to PATH sudo mv rustnet-vX.Y.Z-x86_64-unknown-freebsd/rustnet /usr/local/bin/ # Make it executable sudo chmod +x /usr/local/bin/rustnet # Run with sudo sudo rustnet ``` #### Building from Source on FreeBSD ```bash # Install dependencies pkg install rust libpcap # Clone the repository git clone https://github.com/domcyrus/rustnet.git cd rustnet # Build in release mode cargo build --release # The executable will be in target/release/rustnet sudo ./target/release/rustnet ``` #### Permission Setup for FreeBSD FreeBSD requires access to BPF (Berkeley Packet Filter) devices for packet capture. **Option 1: Run with sudo (Simplest)** ```bash sudo rustnet ``` **Option 2: Add user to the bpf group (Recommended)** ```bash # Add your user to the bpf group sudo pw groupmod bpf -m $(whoami) # Log out and back in for group changes to take effect # Now run without sudo rustnet ``` **Option 3: Change BPF device permissions (Temporary)** ```bash # This will reset on reboot sudo chmod o+rw /dev/bpf* # Now run without sudo rustnet ``` **Verifying FreeBSD Permissions:** ```bash # Check if you're in the bpf group groups | grep bpf # Check BPF device permissions ls -la /dev/bpf* # Test without sudo rustnet --help ``` ### Android (Termux) Installation RustNet can run on Android devices via [Termux](https://termux.dev/en/), provided the device is rooted. Because Android strictly controls network and process information, RustNet requires `root` access (`su`) to capture packets and identify processes. A specialized Android build is provided that statically links dependencies and disables Linux-specific features (like eBPF and Landlock) that are incompatible with Android's kernel environment. #### Prerequisites 1. **Rooted** Android device (e.g., via Magisk or KernelSU) 2. **Termux** installed (from F-Droid or GitHub, *not* Google Play) #### Installation Steps 1. **Install required packages in Termux:** ```bash pkg update pkg install tsu wget tar ``` 2. **Download the Android binary:** ```bash # Download the Android-specific static binary from GitHub Releases wget https://github.com/domcyrus/rustnet/releases/download/vX.Y.Z/rustnet-vX.Y.Z-aarch64-linux-android-musl.tar.gz ``` 3. **Extract and install:** ```bash tar xzf rustnet-vX.Y.Z-aarch64-linux-android-musl.tar.gz # Move it to a directory in your PATH mv rustnet-vX.Y.Z-aarch64-linux-android-musl/rustnet $PREFIX/bin/ chmod +x $PREFIX/bin/rustnet ``` 4. **Run RustNet as root:** ```bash # You must run RustNet with root privileges for it to function on Android sudo rustnet ``` *Note: On first run, your root manager (e.g., Magisk) will prompt you to grant Superuser access to Termux.* ## Install via Cargo ```bash # Install directly from crates.io cargo install rustnet-monitor # The binary will be installed to ~/.cargo/bin/rustnet # Make sure ~/.cargo/bin is in your PATH ``` After installation, see the [Permissions Setup](#permissions-setup) section to configure permissions. ## Building from Source ### Prerequisites - Rust 2024 edition or later (install from [rustup.rs](https://rustup.rs/)) - Platform-specific dependencies: - **Linux (Debian/Ubuntu)**: ```bash sudo apt-get install build-essential pkg-config libpcap-dev libelf-dev zlib1g-dev clang llvm ``` - **Linux (RedHat/CentOS/Fedora)**: ```bash sudo yum install make pkgconfig libpcap-devel elfutils-libelf-devel zlib-devel clang llvm ``` - **macOS**: Install Xcode Command Line Tools: `xcode-select --install` - **FreeBSD**: `pkg install rust libpcap` - **Windows**: Install Npcap and Npcap SDK (see [Windows Build Setup](#windows-build-setup) below) ### Basic Build ```bash # Clone the repository git clone https://github.com/domcyrus/rustnet.git cd rustnet # Build in release mode (eBPF is enabled by default on Linux) cargo build --release # To build WITHOUT eBPF support (procfs-only mode on Linux) cargo build --release --no-default-features # The executable will be in target/release/rustnet ``` To build without eBPF (procfs-only mode), use `cargo build --release --no-default-features`. ### Windows Build Setup Building RustNet on Windows requires the Npcap SDK and proper environment configuration: #### Build Requirements 1. **Download and Install Npcap SDK**: - Download the Npcap SDK from https://npcap.com/dist/ - Extract the SDK to a directory (e.g., `C:\npcap-sdk`) 2. **Set Environment Variables**: - Set the `LIB` environment variable to include the SDK's library path: ```cmd set LIB=%LIB%;C:\npcap-sdk\Lib\x64 ``` - For PowerShell: ```powershell $env:LIB = "$env:LIB;C:\npcap-sdk\Lib\x64" ``` - For permanent setup, add this to your system environment variables 3. **Build RustNet**: ```cmd cargo build --release ``` #### Runtime Requirements 1. **Install Npcap Runtime**: - Download the Npcap installer from https://npcap.com/dist/ - Run the installer and **select "WinPcap API compatible mode"** during installation - This ensures compatibility with the packet capture library 2. **Run RustNet**: ```cmd rustnet.exe ``` **Note**: Depending on your Npcap installation settings, you may or may not need Administrator privileges. If you didn't select the option to restrict packet capture to administrators during Npcap installation, RustNet can run with normal user privileges. ## Using Docker RustNet is available as a Docker container from GitHub Container Registry. The image runs as a **non-root** user by default, with `CAP_NET_RAW` baked into the binary as a file capability — so basic packet capture works with no extra flags. ```bash # Pull the latest image docker pull ghcr.io/domcyrus/rustnet:latest # Or pull a specific version docker pull ghcr.io/domcyrus/rustnet:0.7.0 # Option A — basic monitoring (non-root, recommended) # Captures packets via the built-in CAP_NET_RAW file capability. Process # attribution uses /proc (eBPF disabled). No --cap-add needed. docker run --rm -it --net=host ghcr.io/domcyrus/rustnet:latest # Option B — full eBPF process attribution (runs as root + extra caps) # eBPF needs CAP_BPF + CAP_PERFMON. A non-root user can't make these effective # from --cap-add alone, so enable them by also running as root. docker run --rm -it --user root \ --cap-add=NET_RAW --cap-add=BPF --cap-add=PERFMON --net=host \ ghcr.io/domcyrus/rustnet:latest # Run with a specific interface (either option; -i flag at the end) docker run --rm -it --net=host ghcr.io/domcyrus/rustnet:latest -i eth0 # Alternative: privileged mode (simplest, least secure) docker run --rm -it --privileged --net=host \ ghcr.io/domcyrus/rustnet:latest # View available options docker run --rm ghcr.io/domcyrus/rustnet:latest --help ``` **Note:** Basic capture (Option A) needs no special flags — the image carries `CAP_NET_RAW` as a file capability and runs non-root. eBPF-based process attribution (Option B) additionally needs `CAP_BPF` + `CAP_PERFMON`; because those can't be granted to a non-root user via file capabilities, enable them by running as root (`--user root`) with the matching `--cap-add` flags. Either way, rustnet drops these capabilities and sandboxes itself immediately after startup. Host networking (`--net=host`) is recommended for monitoring all interfaces. ## Permissions Setup RustNet requires elevated privileges to capture network packets because accessing network interfaces for packet capture is a privileged operation on all modern operating systems. This section explains how to properly grant these permissions on different platforms. > ### **Security Advantage: Read-Only Network Access on Linux** > > **RustNet uses read-only packet capture without promiscuous mode on all platforms.** This means: > > **Linux:** Requires only **`CAP_NET_RAW`** capability - **NOT** full root or `CAP_NET_ADMIN` > **Principle of Least Privilege:** Minimal permissions needed for packet capture > **No Promiscuous Mode:** Only captures packets to/from the host (not all network traffic) > **Read-Only:** Cannot modify or inject packets > **Enhanced Security:** Reduced attack surface compared to full root access > > **macOS Note:** PKTAP (for process metadata) requires root privileges, but you can run without sudo using the `lsof` fallback for basic packet capture. ### Why Permissions Are Required Network packet capture requires access to: - **Raw sockets** for low-level network access (read-only, non-promiscuous mode) - **Network interfaces** for packet capture - **BPF (Berkeley Packet Filter) devices** on macOS/BSD systems - **Network namespaces** on some Linux configurations These capabilities are restricted to prevent malicious software from intercepting network traffic. ### macOS Permission Setup On macOS, packet capture requires access to BPF (Berkeley Packet Filter) devices located at `/dev/bpf*`. **Note:** macOS PKTAP (for extracting process metadata from packets) requires **root/sudo** privileges. Without sudo, RustNet uses `lsof` as a fallback for process detection (slower but works without root). #### Option 1: Run with sudo (Simplest) ```bash # Build and run with sudo cargo build --release sudo ./target/release/rustnet ``` #### Option 2: BPF Group Access (Recommended) Add your user to the `access_bpf` group for passwordless packet capture: **Using Wireshark's ChmodBPF (For basic packet capture):** ```bash # Install Wireshark's BPF permission helper brew install --cask wireshark-chmodbpf # Log out and back in for group changes to take effect # Then run rustnet without sudo: rustnet # Uses lsof for process detection (slower) # For PKTAP support with process metadata from packet headers, use sudo: sudo rustnet # Uses PKTAP for faster process detection ``` **Note**: `wireshark-chmodbpf` grants access to `/dev/bpf*` for packet capture, but **PKTAP** is a separate privileged kernel interface that requires root privileges regardless of BPF permissions. The TUI will display which detection method is active ("pktap" with sudo, or "lsof" without). **Manual BPF Group Setup:** ```bash # Create the access_bpf group (if it doesn't exist) sudo dseditgroup -o create access_bpf # Add your user to the group sudo dseditgroup -o edit -a $USER -t user access_bpf # Set permissions on BPF devices (this needs to be done after each reboot) sudo chmod g+rw /dev/bpf* sudo chgrp access_bpf /dev/bpf* # Log out and back in for group membership to take effect ``` #### Option 3: Homebrew Installation If installed via Homebrew, the formula will provide detailed setup instructions: ```bash brew install rustnet # Follow the caveats displayed after installation ``` ### Linux Permission Setup (Read-Only Access - No Root Required!) **Linux Advantage:** RustNet requires **only `CAP_NET_RAW`** for packet capture - far less than full root access! On Linux, packet capture requires only the `CAP_NET_RAW` capability for read-only, non-promiscuous packet capture. For eBPF-enhanced process tracking, additional capabilities (`CAP_BPF` and `CAP_PERFMON`) are needed, but **`CAP_NET_ADMIN` is NOT required**. #### Option 1: Run with sudo (Simplest) ```bash # Build and run with sudo cargo build --release sudo ./target/release/rustnet ``` #### Option 2: Grant Capabilities (Recommended) Grant specific network capabilities to the binary without full root privileges: **For source builds:** ```bash # Build the binary first cargo build --release # Grant capabilities to the binary (modern kernel 5.8+, with eBPF support) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' ./target/release/rustnet # Now run without sudo ./target/release/rustnet ``` **For cargo-installed binaries:** ```bash # If installed via cargo install rustnet-monitor (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' ~/.cargo/bin/rustnet # Now run without sudo rustnet ``` **For eBPF-enabled builds (enhanced Linux performance, enabled by default):** eBPF is enabled by default on Linux. RustNet first attempts BPF trampoline programs using fentry/fexit, then falls back to legacy kprobes, and finally to procfs. Backend support is determined by actual program load and attachment results, not the reported kernel version. Both BPF backends use CO-RE socket field reads and require usable target BTF. When target BTF is unavailable, RustNet falls directly to procfs rather than using fixed kernel-structure offsets that could produce incorrect attribution. ```bash # Build in release mode (eBPF is enabled by default) cargo build --release # Modern Linux (5.8+) - works with just these three capabilities: sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' ./target/release/rustnet ./target/release/rustnet # Packet capture only - eBPF falls back to procfs: sudo setcap 'cap_net_raw+eip' ./target/release/rustnet ./target/release/rustnet # Check the TUI Statistics panel for the selected backend. ``` **Capability requirements:** **Base capability (always required):** - `CAP_NET_RAW` - Raw socket access for read-only packet capture (non-promiscuous mode) **eBPF-specific capabilities (Linux 5.8+):** - `CAP_BPF` - BPF program loading and map operations - `CAP_PERFMON` - Performance monitoring and tracing operations **Legacy Linux (pre-5.8):** Older kernels require broad `CAP_SYS_ADMIN` for eBPF operations. RustNet does not recommend or automatically grant it. Use `CAP_NET_RAW` only and let process attribution fall back to procfs unless you explicitly accept the extra risk. Kernels without memcg-based BPF memory accounting may also require a larger `RLIMIT_MEMLOCK`. libbpf raises it automatically when permitted. For a systemd service, set `LimitMEMLOCK=infinity` if BPF loading reports a memlock failure. **Note:** CAP_NET_ADMIN is NOT required. RustNet uses read-only packet capture without promiscuous mode. **Fallback behavior:** RustNet attempts the backends in this order: 1. `eBPF fentry/fexit + procfs` 2. `eBPF kprobe + procfs` 3. `procfs` The TUI Statistics panel reports the selected backend. A missing optional ICMP hook produces partial ICMP coverage without disabling TCP and UDP attribution. Falling back from fentry/fexit to kprobes is not reported as a degradation — both backends provide the same attribution coverage, and the fentry error is written to the log. If both BPF backends fail, the panel shows the classified reason for the legacy backend's failure and the log retains both full errors. **Note:** eBPF is enabled by default on Linux builds and may have limitations with process name display. See [ARCHITECTURE.md](ARCHITECTURE.md) for details on eBPF implementation. To build without eBPF, use `cargo build --release --no-default-features`. **For system-wide installation:** ```bash # If installed via package manager or copied to /usr/local/bin (modern kernel 5.8+) sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' /usr/local/bin/rustnet rustnet ``` ### Windows Permission and Process Attribution Setup Windows has two independent permission paths: 1. **Packet capture** uses Npcap. Whether RustNet must run as Administrator is determined by the options selected when Npcap was installed. If Npcap was configured to restrict capture to administrators, start Command Prompt, PowerShell, or Windows Terminal with **Run as administrator**. Otherwise a standard-user process can capture packets. 2. **Process attribution** prefers Event Tracing for Windows (ETW) and always keeps the IP Helper API available for reconciliation and fallback. At startup RustNet attempts to subscribe to the Windows kernel network and process ETW providers. The Overview tab reports the resulting mode: | Detection display | Meaning | |---|---| | `ETW + IP Helper` | Event-driven attribution is active. ETW catches short-lived processes; IP Helper fills cache misses and reconciles current sockets. | | `IP Helper` | ETW could not be started. RustNet continues without failing, using `GetExtendedTcpTable` and `GetExtendedUdpTable`. Very short-lived processes may be missed between table snapshots. | An Administrator shell is the most compatible way to enable ETW. A local administrator can instead grant a user trace-session rights by adding that user to the built-in **Performance Log Users** group (SID `S-1-5-32-559`). Sign out and back in after changing group membership. Provider security policy can still deny a particular ETW provider, so check the Overview tab rather than assuming ETW is active. ETW authorization and Npcap authorization are separate. Membership in **Performance Log Users** does not grant packet-capture access, and a non-administrator can still use IP Helper process attribution when ETW is unavailable. No manual fallback option is necessary: RustNet selects the best available mode automatically. Some rows may remain `