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.

Installing from Release Packages
Install via Cargo
Building from Source
Using Docker
Prerequisites
Permissions Setup
GeoIP Databases (Optional)
Troubleshooting

Installing from Release Packages

Pre-built packages are available for each release on the GitHub 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 for instructions.

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
Open the DMG and drag Rustnet.app to your Applications folder
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
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

Optional: Create a symlink for shell access:

# 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

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 section for detailed instructions

Windows MSI Installation

Install Npcap Runtime (required for packet capture):
- Download from https://npcap.com/dist/
- Run the installer and select "WinPcap API compatible mode"
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
Run the installer and follow the installation wizard
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:

# Run in Administrator PowerShell
choco install rustnet

Note: You still need to install Npcap 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)

# 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 from GitHub releases or build from source.

Debian/Ubuntu (.deb packages)

For manual installation or non-Ubuntu Debian-based distributions:

# 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:

# 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). It can be installed using pacman:

sudo pacman -S rustnet

Alternatively, two AUR packages are available:

rustnet-bin - Pre-compiled binary from GitHub Releases
rustnet-git - Build from source and use the latest commit (maintained by @DeepChirp)

Install with your preferred AUR helper:

# 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, including the stable channels (as well as nixpkgs-unstable).

Try it without installing (ephemeral shell):

nix-shell -p rustnet
# Then inside the shell:
sudo rustnet

Persistent install on NixOS — add to /etc/nixos/configuration.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 entry that carries the capabilities:

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 is in review for nixpkgs. Once merged it wraps exactly the capabilities above for you, so the whole setup becomes:
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.

# 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 from GitHub releases or build from source.

openSUSE Tumbleweed (OBS)

RustNet is built for openSUSE Tumbleweed (x86_64 and aarch64) via the openSUSE Build Service.

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:

brew install rustnet

# Follow the caveats displayed after installation for permission setup

On Linux:

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.

# 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:

# 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:

# 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

# 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)

sudo rustnet

Option 2: Add user to the bpf group (Recommended)

# 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)

# This will reset on reboot
sudo chmod o+rw /dev/bpf*

# Now run without sudo
rustnet

Verifying FreeBSD Permissions:

# 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, 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

Rooted Android device (e.g., via Magisk or KernelSU)
Termux installed (from F-Droid or GitHub, not Google Play)

Installation Steps

Install required packages in Termux:
```
pkg update
pkg install tsu wget tar
```

Download the Android binary:

# 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

Extract and install:

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

Run RustNet as root:
```
# 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

# 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 section to configure permissions.

Building from Source

Prerequisites

Rust 2024 edition or later (install from rustup.rs)
Platform-specific dependencies:
- Linux (Debian/Ubuntu):
```
sudo apt-get install build-essential pkg-config libpcap-dev libelf-dev zlib1g-dev clang llvm
```
- Linux (RedHat/CentOS/Fedora):
```
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 below)

Basic Build

# 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

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)
Set Environment Variables:
- Set the LIB environment variable to include the SDK's library path:
```
set LIB=%LIB%;C:\npcap-sdk\Lib\x64
```
- For PowerShell:
```
$env:LIB = "$env:LIB;C:\npcap-sdk\Lib\x64"
```
- For permanent setup, add this to your system environment variables
Build RustNet:
```
cargo build --release
```

Runtime Requirements

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
Run RustNet:
```
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.

# 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)

# 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):

# 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:

# 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:

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)

# 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:

# 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:

# 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 and provides lower-overhead process identification using kernel probes:

# 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

# Legacy Linux (older kernels without CAP_BPF) - use CAP_SYS_ADMIN as fallback:
sudo setcap 'cap_net_raw,cap_sys_admin+eip' ./target/release/rustnet
./target/release/rustnet

# Check TUI Statistics panel - should show "Process Detection: eBPF + procfs"

Capability requirements:

Base capability (always required):

CAP_NET_RAW - Raw socket access for read-only packet capture (non-promiscuous mode)

eBPF-specific capabilities (choose based on kernel version):

Modern Linux (5.8+):

CAP_BPF - BPF program loading and map operations
CAP_PERFMON - Performance monitoring and tracing operations

Legacy Linux (pre-5.8):

CAP_SYS_ADMIN - Required for BPF operations on older kernels without CAP_BPF support

Note: CAP_NET_ADMIN is NOT required. RustNet uses read-only packet capture without promiscuous mode.

Fallback behavior: If eBPF cannot load (e.g., insufficient capabilities, incompatible kernel), the application automatically uses procfs-only mode. The TUI Statistics panel displays which detection method is active:

Process Detection: eBPF + procfs - eBPF successfully loaded
Process Detection: procfs - Using procfs fallback

Note: eBPF is enabled by default on Linux builds and may have limitations with process name display. See ARCHITECTURE.md for details on eBPF implementation. To build without eBPF, use cargo build --release --no-default-features.

For system-wide installation:

# 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 Setup

Windows support is currently limited, but when available:

RustNet will require Administrator privileges
Must install WinPcap or Npcap for packet capture
Run Command Prompt or PowerShell "As Administrator"

Verifying Permissions

To verify that permissions are set up correctly:

macOS

# Check BPF device permissions
ls -la /dev/bpf*

# Check group membership
groups | grep access_bpf

# Test without sudo
rustnet --help

Linux

# Check capabilities on the binary
# For source builds:
getcap ./target/release/rustnet

# For cargo-installed binaries:
getcap ~/.cargo/bin/rustnet

# For system-wide installations:
getcap $(which rustnet)

# Modern (5.8+): Should show cap_net_raw,cap_bpf,cap_perfmon+eip
# Legacy: Should show cap_net_raw,cap_sys_admin+eip

# Test without sudo
rustnet --help

GeoIP Databases (Optional)

RustNet supports GeoIP lookups to show country codes, city names, and ASN information for remote IPs. To enable this, install the GeoLite2 databases using MaxMind's geoipupdate tool (requires a free MaxMind account).

Available databases:

Database	Provides	Flag
`GeoLite2-Country.mmdb`	Country code and name	(auto-discovered)
`GeoLite2-ASN.mmdb`	ASN number and organization	(auto-discovered)
`GeoLite2-City.mmdb`	City name, postal code, and country	(auto-discovered)

Tip: GeoLite2-City is a superset of GeoLite2-Country. If you install the City database you do not need to also install the Country database.

Configuring which databases to download

In your GeoIP.conf, set EditionIDs to include the databases you want:

# Country + ASN only:
EditionIDs GeoLite2-Country GeoLite2-ASN

# City + ASN (City includes country data):
EditionIDs GeoLite2-City GeoLite2-ASN

# All three:
EditionIDs GeoLite2-Country GeoLite2-ASN GeoLite2-City

macOS (Homebrew)

brew install geoipupdate
# Edit the config with your MaxMind account credentials and EditionIDs:
#   $(brew --prefix)/etc/GeoIP.conf
geoipupdate

Databases are installed to $(brew --prefix)/share/GeoIP/.

Ubuntu/Debian

sudo apt-get install geoipupdate
# Edit /etc/GeoIP.conf with your MaxMind account credentials and EditionIDs
sudo geoipupdate

Databases are installed to /usr/share/GeoIP/.

Fedora/RHEL

sudo dnf install geoipupdate
# Edit /etc/GeoIP.conf with your MaxMind account credentials and EditionIDs
sudo geoipupdate

Databases are installed to /usr/share/GeoIP/.

Arch Linux

sudo pacman -S geoipupdate
# Edit /etc/GeoIP.conf with your MaxMind account credentials and EditionIDs
sudo geoipupdate

Databases are installed to /usr/share/GeoIP/.

FreeBSD

pkg install geoipupdate
# Edit /usr/local/etc/GeoIP.conf with your MaxMind account credentials and EditionIDs
sudo geoipupdate

Databases are installed to /usr/local/share/GeoIP/.

Manual Specification

If your databases are in a non-standard location, specify them directly:

# Country + ASN:
rustnet --geoip-country /path/to/GeoLite2-Country.mmdb --geoip-asn /path/to/GeoLite2-ASN.mmdb

# City + ASN (City includes country data):
rustnet --geoip-city /path/to/GeoLite2-City.mmdb --geoip-asn /path/to/GeoLite2-ASN.mmdb

RustNet auto-discovers databases from standard locations. Run rustnet --help to see the full search path list.

Troubleshooting

Common Installation Issues

Permission Denied Errors

On macOS:

Ensure you're in the access_bpf group: groups | grep access_bpf
Check BPF device permissions: ls -la /dev/bpf0
Try running with sudo to confirm it's a permission issue
Log out and back in after group changes

On Linux:

Check if capabilities are set: getcap $(which rustnet) or getcap ~/.cargo/bin/rustnet
Verify libpcap is installed: ldconfig -p | grep pcap
Try running with sudo to confirm it's a permission issue: sudo $(which rustnet)

No Suitable Capture Interfaces Found

Check available interfaces: ip link show (Linux) or ifconfig (macOS)
Try specifying an interface explicitly: rustnet -i eth0
Ensure the interface is up and has an IP address
Some virtual interfaces may not support packet capture

Operation Not Permitted (with capabilities set)

Capabilities may have been removed by system updates
Re-apply capabilities (modern): sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' $(which rustnet)
Some filesystems don't support extended attributes (capabilities)
Try copying the binary to a different filesystem (e.g., from NFS to local disk)

eBPF Unavailable Despite Capabilities Being Set

If RustNet shows Process Detection: procfs with a degradation message even after running setcap, work through the following checks. The TUI surfaces the actual reason on the second status line — use it to jump to the right section below.

1. file caps ignored: binary on a nosuid mount

The kernel silently ignores file capabilities for binaries that live on a filesystem mounted with the nosuid option. Common culprits: /home on hardened distros, /tmp, removable media, some bind-mounts inside containers.

# Find the mount that holds the binary and check its options
findmnt -T $(realpath $(which rustnet)) -o TARGET,OPTIONS
# If the OPTIONS column contains "nosuid", caps will not work.

# Fix: install or copy the binary to a mount without nosuid
sudo install -m 0755 $(which rustnet) /usr/local/bin/rustnet
sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' /usr/local/bin/rustnet
/usr/local/bin/rustnet

2. BPF denied (check perf_event_paranoid / AppArmor / unprivileged_bpf_disabled)

Caps were granted, but the kernel returned EPERM or EACCES. Three layers can do that — check them in this order:

# 2a. perf_event_paranoid (THE most common cause on Debian).
#     Debian 13 ships with kernel.perf_event_paranoid=3, which blocks
#     perf_event_open(2) — and therefore kprobe attach — for non-root
#     users *even with CAP_PERFMON*. Upstream kernels only go up to 2,
#     where CAP_PERFMON correctly bypasses the restriction.
#
#     Ubuntu uses a different patch (paranoid=4) that was updated in
#     late 2025 to honor CAP_PERFMON, so on recent Ubuntu kernels
#     (Jammy 5.15.0-165+, Noble 6.8.0-91+, Plucky 6.14.0-37+,
#     Questing 6.17.0-14+, Resolute 6.18.0-8+) `setcap` alone is
#     enough — no sysctl change required. Debian's equivalent patch
#     (bug #994044) was never updated and was archived in 2025
#     without a fix, so Debian users still need the workaround below.
sysctl kernel.perf_event_paranoid
# If the value is 3 (Debian) or 4 on an old Ubuntu kernel, drop it to 2:
sudo sysctl kernel.perf_event_paranoid=2
# Make it persist across reboot:
echo 'kernel.perf_event_paranoid = 2' | \
  sudo tee /etc/sysctl.d/99-rustnet.conf

# 2b. AppArmor confining rustnet (Debian/Ubuntu install AppArmor by default).
sudo aa-status | grep rustnet
# If listed, either disable the profile or add a rule allowing capability bpf,
# capability perfmon, and the bpf() syscall for this binary.

# 2c. unprivileged_bpf_disabled (Debian sets =2; file caps should bypass).
sysctl kernel.unprivileged_bpf_disabled

# Confirm caps actually became effective at exec:
grep ^Cap /proc/$(pgrep -n rustnet)/status
# CapEff must include CAP_BPF (bit 39) and CAP_PERFMON (bit 38).

3. kprobe attach failed: <symbol>

The kernel is missing the symbol the eBPF probe wants to attach to. This is usually a kernel-config issue (e.g. CONFIG_IPV6 disabled, CONFIG_KPROBES off, or the symbol was inlined). RustNet currently attaches to tcp_connect, inet_csk_accept, udp_sendmsg, tcp_v6_connect, udpv6_sendmsg, ping_v4_sendmsg, and ping_v6_sendmsg.

# Check whether the failing symbol exists in the running kernel:
sudo grep '<symbol_name>' /proc/kallsyms

If the symbol is genuinely missing, eBPF process detection will not work on this kernel build; procfs fallback continues to function.

4. kernel BTF unavailable

CO-RE relocations require /sys/kernel/btf/vmlinux. On stripped-down kernels (some embedded / minimal cloud images) this file is absent.

ls /sys/kernel/btf/vmlinux
# If missing: install the kernel-debuginfo / linux-image package matching
# your running kernel, or rebuild the kernel with CONFIG_DEBUG_INFO_BTF=y.

5. Inside Docker / Podman

Even with file capabilities, the bounding set inside the container must contain CAP_BPF and CAP_PERFMON, or they get masked at exec:

docker run --cap-add=NET_RAW --cap-add=BPF --cap-add=PERFMON \
           --net=host --pid=host rustnet
# Optionally, if your container's seccomp profile blocks bpf(2):
#   --security-opt seccomp=unconfined
# Or if AppArmor mediates BPF:
#   --security-opt apparmor=unconfined

6. eBPF load failed: ...

The catch-all branch carries the raw libbpf error text. Re-run with RUST_LOG=debug rustnet 2>&1 | tee rustnet.log and inspect the full chain — it usually contains an errno name (EPERM, EACCES, ENOSPC for memlock, etc.) that points at the root cause.

Windows: Npcap Not Found

Ensure Npcap is installed from https://npcap.com/dist/
During Npcap installation, select "WinPcap API compatible mode"
Verify Npcap service is running: sc query npcap
Try reinstalling Npcap with administrator privileges

Build Errors

Windows - Npcap SDK not found:

Ensure the LIB environment variable includes the Npcap SDK path
Check that the SDK is extracted to a directory without spaces
Use the correct architecture (x64 vs x86) for your Rust toolchain

Linux build fails:

# Install all required dependencies
# Debian/Ubuntu
sudo apt-get install build-essential pkg-config libpcap-dev libelf-dev zlib1g-dev clang llvm

# RedHat/CentOS/Fedora
sudo yum install make pkgconfig libpcap-devel elfutils-libelf-devel zlib-devel clang llvm

Windows: Graphs Display Incorrectly in PowerShell

If graphs and sparklines appear corrupted (showing question marks or garbled characters) in PowerShell, this is a font issue, not a RustNet bug. The default console fonts (Consolas, Lucida Console) lack support for Unicode Braille characters used for graph rendering.

Solution: Install a font with Unicode Braille support:

Download and install Iosevka or any Nerd Font
Open PowerShell Properties (right-click title bar → Properties)
Select the installed font in the Font tab
Restart PowerShell

Alternative: Use Windows Terminal which has better Unicode support out of the box.

Getting Help

If you encounter issues not covered here:

Enable debug logging: rustnet --log-level debug
Check the log file in the logs/ directory
Open an issue on GitHub with:
- Your operating system and version
- Installation method used
- Error messages from logs
- Output of permission verification commands

Security Best Practices

Use capabilities instead of sudo when possible (Linux)
Use group-based access instead of running as root (macOS)
Regularly audit which users have packet capture privileges
Consider network segmentation if running on production systems
Monitor log files for unauthorized usage

Remove capabilities when RustNet is no longer needed:

# Linux: Remove capabilities
sudo setcap -r /path/to/rustnet

# macOS: Remove from group
sudo dseditgroup -o edit -d $USER -t user access_bpf

Integration with System Monitoring

For production environments, consider:

Audit logging of packet capture access
Network monitoring policies and compliance requirements
User access reviews for privileged network access
Automated capability management in configuration management systems

This permissions setup ensures RustNet can capture packets while maintaining security best practices and principle of least privilege.

FilesExpand file tree

INSTALL.md

Latest commit

History

INSTALL.md

File metadata and controls

Installation Guide

Table of Contents

Installing from Release Packages

macOS DMG Installation

Windows MSI Installation

Windows Chocolatey Installation

Linux Package Installation

Ubuntu PPA (Recommended for Ubuntu 25.10 Questing and 26.04 LTS Resolute)

Debian/Ubuntu (.deb packages)

RedHat/Fedora/CentOS (.rpm packages)

Arch Linux

Nix / NixOS

Fedora (COPR - Recommended for Fedora 42+)

openSUSE Tumbleweed (OBS)

Homebrew Installation

Static Binary (Portable - Any Linux Distribution)

FreeBSD Installation

From Ports or Packages (Future)

From GitHub Releases

Building from Source on FreeBSD

Permission Setup for FreeBSD

Android (Termux) Installation

Prerequisites

Installation Steps

Install via Cargo

Building from Source

Prerequisites

Basic Build

Windows Build Setup

Build Requirements

Runtime Requirements

Using Docker

Permissions Setup

Security Advantage: Read-Only Network Access on Linux

Why Permissions Are Required

macOS Permission Setup

Option 1: Run with sudo (Simplest)

Option 2: BPF Group Access (Recommended)

Option 3: Homebrew Installation

Linux Permission Setup (Read-Only Access - No Root Required!)

Option 1: Run with sudo (Simplest)

Option 2: Grant Capabilities (Recommended)

Windows Permission Setup

Verifying Permissions

macOS

Linux

GeoIP Databases (Optional)

Configuring which databases to download

macOS (Homebrew)

Ubuntu/Debian

Fedora/RHEL

Arch Linux

FreeBSD

Manual Specification

Troubleshooting

Common Installation Issues

Permission Denied Errors

No Suitable Capture Interfaces Found

Operation Not Permitted (with capabilities set)

eBPF Unavailable Despite Capabilities Being Set

Windows: Npcap Not Found

Build Errors

Windows: Graphs Display Incorrectly in PowerShell

Getting Help

Security Best Practices

Integration with System Monitoring