mirror of https://github.com/domcyrus/rustnet.git synced 2026-01-01 11:30:14 -06:00

Files

Marco Cadetg 85b2662c85 feat: add freebsd (#71 )

* feat: add freebsd

2025-11-02 19:47:26 +01:00

24 KiB

Raw Permalink Blame History

Installation Guide

This guide covers all installation methods for RustNet across different platforms.

Installing from Release Packages
Install via Cargo
Building from Source
Using Docker
Prerequisites
Permissions Setup
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

Linux Package Installation

Ubuntu PPA (Recommended for Ubuntu 25.10+)

The easiest way to install RustNet on Ubuntu is via the official PPA.

# 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 only supports Ubuntu 25.10+ due to the Rust 1.88+ requirement. Earlier Ubuntu versions don't have a recent enough Rust compiler 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 (AUR)

Two AUR packages are available:

rustnet - Build from source (maintained by @DeepChirp)
rustnet-bin - Pre-compiled binary for faster installation

Install with your preferred AUR helper:

# Source build (optimized for your system)
yay -S rustnet

# OR pre-compiled binary (faster installation)
yay -S rustnet-bin

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.

Homebrew Installation

On macOS:

brew tap domcyrus/rustnet
brew install rustnet

# Follow the caveats displayed after installation for permission setup

On Linux:

brew install domcyrus/rustnet/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

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 GitHub Releases:

# Download the appropriate package
fetch https://github.com/domcyrus/rustnet/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

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)
libpcap or similar packet capture library:
- Linux: sudo apt-get install libpcap-dev (Debian/Ubuntu) or sudo yum install libpcap-devel (RedHat/CentOS)
- macOS: Included by default
- FreeBSD: pkg install libpcap (included in base system, but headers needed for building)
- Windows: Install Npcap and Npcap SDK (see Windows Build Setup below)
For eBPF support (enabled by default on Linux):
- sudo apt-get install libelf-dev clang llvm (Debian/Ubuntu)
- sudo yum install elfutils-libelf-devel clang llvm (RedHat/CentOS)
- Linux kernel 4.19+ with BTF support recommended
- Note: eBPF automatically falls back to procfs if unavailable

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

See EBPF_BUILD.md for detailed eBPF information.

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:

# 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

# Run with required capabilities for eBPF support (latest)
docker run --rm -it --cap-add=NET_RAW --cap-add=BPF --cap-add=PERFMON --net=host \
  ghcr.io/domcyrus/rustnet:latest

# Run with specific version
docker run --rm -it --cap-add=NET_RAW --cap-add=BPF --cap-add=PERFMON --net=host \
  ghcr.io/domcyrus/rustnet:0.7.0

# Run with specific interface
docker run --rm -it --cap-add=NET_RAW --cap-add=BPF --cap-add=PERFMON --net=host \
  ghcr.io/domcyrus/rustnet:latest -i eth0

# Alternative: Run with privileged mode (less secure but simpler)
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: The container requires capabilities (NET_RAW, BPF, and PERFMON) or privileged mode for packet capture with eBPF support. Host networking (--net=host) is recommended for monitoring all network 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 tap domcyrus/rustnet
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

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)
Some systems require CAP_NET_BIND_SERVICE as well

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)

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

Linux - Missing libpcap:

# Debian/Ubuntu
sudo apt-get install libpcap-dev

# RedHat/CentOS/Fedora
sudo yum install libpcap-devel

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

eBPF build fails:

# Install required dependencies
# Debian/Ubuntu
sudo apt-get install libelf-dev clang llvm

# RedHat/CentOS/Fedora
sudo yum install elfutils-libelf-devel clang llvm

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.

24 KiB Raw Permalink Blame History

Installation Guide

Table of Contents

Installing from Release Packages

macOS DMG Installation

Windows MSI Installation

Linux Package Installation

Ubuntu PPA (Recommended for Ubuntu 25.10+)

Debian/Ubuntu (.deb packages)

RedHat/Fedora/CentOS (.rpm packages)

Arch Linux (AUR)

Fedora (COPR - Recommended for Fedora 42+)

Homebrew Installation

FreeBSD Installation

From Ports or Packages (Future)

From GitHub Releases

Building from Source on FreeBSD

Permission Setup for FreeBSD

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

Troubleshooting

Common Installation Issues

Permission Denied Errors

No Suitable Capture Interfaces Found

Operation Not Permitted (with capabilities set)

Windows: Npcap Not Found

Build Errors

Getting Help

Security Best Practices

Integration with System Monitoring

24 KiB

Raw Permalink Blame History