mirror/rustnet
1
0
Fork 0
mirror of https://github.com/domcyrus/rustnet.git synced 2026-01-03 04:20:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: update Linux build dependencies and remove EBPF_BUILD.md

Browse Source 
- Add missing build-essential, pkg-config, zlib1g-dev to documentation
- Update rust.yml CI with complete dependencies
- Remove EBPF_BUILD.md (info already in INSTALL.md)
- Update references in README.md and ARCHITECTURE.md
This commit is contained in:
Marco Cadetg
2025-11-30 15:25:15 +01:00
parent 26152f053b
commit f43db07738
5 changed files with 18 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/rust.yml vendored
View File

@@ -33,7 +33,7 @@ jobs:
steps:
- uses: actions/checkout@v6
- name: Install dependencies
run: sudo apt-get update && sudo apt-get install -y libpcap-dev libelf-dev clang llvm
run: sudo apt-get update && sudo apt-get install -y libpcap-dev libelf-dev zlib1g-dev clang llvm pkg-config
- name: Build
run: cargo build --verbose
- name: Run tests

2
ARCHITECTURE.md
View File

@@ -180,8 +180,6 @@ RustNet uses platform-specific APIs to associate network connections with proces
- If eBPF fails to load (permissions, kernel compatibility), automatically falls back to procfs mode
- TUI Statistics panel shows active detection method
See [EBPF_BUILD.md](EBPF_BUILD.md) for detailed eBPF build and deployment information.
#### macOS
**PKTAP Mode (with sudo):**

156
EBPF_BUILD.md
View File

@@ -1,156 +0,0 @@
# eBPF Build Guide
This document explains how to work with eBPF kernel headers in this project.
**Note:** eBPF is now enabled by default on Linux builds. This guide provides detailed information about the eBPF implementation and how to customize the build.
## Current Setup
The project bundles **architecture-specific vmlinux.h files** from the [libbpf/vmlinux.h](https://github.com/libbpf/vmlinux.h) repository. This eliminates network dependencies during builds and ensures reproducible builds.
### Bundled vmlinux.h Files
Pre-downloaded vmlinux.h files (based on Linux kernel 6.14) are included in the repository at:
- `resources/ebpf/vmlinux/x86/vmlinux.h` (for x86_64, ~1.1MB)
- `resources/ebpf/vmlinux/aarch64/vmlinux.h` (for aarch64, ~1.0MB)
- `resources/ebpf/vmlinux/arm/vmlinux.h` (for armv7, ~981KB)
These files are automatically used during the build process based on the target architecture. **No network access is required** during compilation.
**Benefits:**
- **Zero network dependency**: Works in restricted build environments (COPR, Fedora build systems, etc.)
- **Reproducible builds**: Same headers every time, no external dependencies
- **Complete kernel definitions**: All kernel structures available, no missing types
- **No manual maintenance**: Auto-generated from kernel BTF
- **Cross-kernel compatibility**: CO-RE/BTF ensures portability across kernel versions
**Trade-offs:**
- Repository size: ~3MB total for all architectures (acceptable for modern git)
- Not immediately clear which kernel structures are actually used by the code
## Updating Bundled vmlinux.h Files
The bundled vmlinux.h files are based on kernel 6.14 from the libbpf repository. To update them to a newer kernel version:
```bash
# Update all architectures at once
for arch in x86 aarch64 arm; do
# Get the symlink target (e.g., vmlinux_6.14.h)
target=$(curl -sL "https://raw.githubusercontent.com/libbpf/vmlinux.h/main/include/${arch}/vmlinux.h")
# Download the actual file
curl -sL "https://raw.githubusercontent.com/libbpf/vmlinux.h/main/include/${arch}/${target}" \
-o "resources/ebpf/vmlinux/${arch}/vmlinux.h"
echo "Updated ${arch} to ${target}"
done
```
Or update a single architecture:
```bash
# Example: Update x86 only
arch="x86"
target=$(curl -sL "https://raw.githubusercontent.com/libbpf/vmlinux.h/main/include/${arch}/vmlinux.h")
curl -sL "https://raw.githubusercontent.com/libbpf/vmlinux.h/main/include/${arch}/${target}" \
-o "resources/ebpf/vmlinux/${arch}/vmlinux.h"
```
After updating, commit the changes to the repository.
## Building with eBPF Support
eBPF is enabled by default on Linux. To build rustnet:
```bash
# Install build dependencies
sudo apt-get install libelf-dev clang llvm # Debian/Ubuntu
sudo yum install elfutils-libelf-devel clang llvm # RedHat/CentOS/Fedora
# Build in release mode (eBPF is enabled by default)
cargo build --release
# The bundled vmlinux.h files will be used automatically
# No network access required!
```
To build **without** eBPF support (procfs-only mode):
```bash
# Build without eBPF
cargo build --release --no-default-features
```
## Testing eBPF Functionality
After building (eBPF is enabled by default), test that it works correctly:
```bash
# Option 1: Run with sudo (always works)
sudo cargo run --release
# Option 2: Set capabilities (Linux only, see INSTALL.md Permissions section)
# Modern Linux (5.8+):
sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon=eip' ./target/release/rustnet
./target/release/rustnet
# Legacy Linux (older kernels):
sudo setcap 'cap_net_raw,cap_sys_admin=eip' ./target/release/rustnet
./target/release/rustnet
# Check the TUI Statistics panel to verify it shows "Process Detection: eBPF + procfs"
```
**Note**: eBPF kprobe programs require specific Linux capabilities. RustNet uses read-only packet capture (CAP_NET_RAW) without promiscuous mode, so CAP_NET_ADMIN is not required. Modern kernels (5.8+) need CAP_BPF and CAP_PERFMON for eBPF, while older kernels require CAP_SYS_ADMIN. See [INSTALL.md - Permissions Setup](INSTALL.md#permissions-setup) for detailed capability requirements.
## Generating vmlinux.h from Your Local Kernel (Optional)
If you need to generate a vmlinux.h file for your specific kernel (e.g., for debugging or custom kernel builds):
```bash
# Method 1: Using bpftool (requires root/CAP_BPF)
sudo bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h
# Method 2: Using pahole (if available)
pahole -J /boot/vmlinux-$(uname -r)
pahole --btf_encode_detached vmlinux.btf /boot/vmlinux-$(uname -r)
bpftool btf dump file vmlinux.btf format c > vmlinux.h
# Method 3: From kernel source
cd /path/to/kernel/source
make scripts_gdb
bpftool btf dump file vmlinux format c > vmlinux.h
```
This is typically not needed since the bundled headers work across kernel versions thanks to CO-RE/BTF.
## Troubleshooting
### Compilation Errors
**"Bundled vmlinux.h not found"**:
- Ensure the `resources/ebpf/vmlinux/` directory exists
- Verify you've cloned the full repository (not a partial checkout)
- Check that the vmlinux.h file exists for your target architecture
**Missing build dependencies**:
- Install clang, llvm, and libelf-dev
- Ensure rustfmt is installed: `rustup component add rustfmt`
### Runtime Errors
**"BTF verification failed"**:
- Your kernel may not have BTF support enabled
- Linux kernel 4.19+ with BTF support is recommended
- Check if BTF is available: `ls /sys/kernel/btf/vmlinux`
**"Permission denied" when loading eBPF**:
- See [INSTALL.md - Permissions Setup](INSTALL.md#permissions-setup) for capability setup
- Required capabilities (modern kernel 5.8+): `CAP_NET_RAW`, `CAP_BPF`, `CAP_PERFMON`
- Required capabilities (legacy kernel): `CAP_NET_RAW`, `CAP_SYS_ADMIN`
- Note: CAP_NET_ADMIN is NOT required (RustNet uses read-only packet capture)
**eBPF fails to load, falls back to procfs**:
- This is expected behavior when eBPF can't load
- Check the TUI Statistics panel to see which detection method is active
- Common reasons: insufficient capabilities, incompatible kernel, BTF not available

39
INSTALL.md
View File

@@ -315,16 +315,18 @@ After installation, see the [Permissions Setup](#permissions-setup) section to c
### Prerequisites
- Rust 2024 edition or later (install from [rustup.rs](https://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)
- 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)
- **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
@@ -342,7 +344,7 @@ cargo build --release --no-default-features
# The executable will be in target/release/rustnet
```
See [EBPF_BUILD.md](EBPF_BUILD.md) for detailed eBPF information.
To build without eBPF (procfs-only mode), use `cargo build --release --no-default-features`.
### Windows Build Setup
@@ -682,28 +684,19 @@ rustnet --help
#### Build Errors
**Linux - Missing libpcap:**
```bash
# 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:**
**Linux build fails:**
```bash
# Install required dependencies
# Install all required dependencies
# Debian/Ubuntu
sudo apt-get install libelf-dev clang llvm
sudo apt-get install build-essential pkg-config libpcap-dev libelf-dev zlib1g-dev clang llvm
# RedHat/CentOS/Fedora
sudo yum install elfutils-libelf-devel clang llvm
sudo yum install make pkgconfig libpcap-devel elfutils-libelf-devel zlib-devel clang llvm
```
### Getting Help

3
README.md
View File

@@ -53,7 +53,7 @@ To disable eBPF and use procfs-only mode, build with:
cargo build --release --no-default-features
```
See [EBPF_BUILD.md](EBPF_BUILD.md) for more details and [ARCHITECTURE.md](ARCHITECTURE.md) for technical information.
See [ARCHITECTURE.md](ARCHITECTURE.md) for technical information.
</details>
@@ -236,7 +236,6 @@ See [USAGE.md](USAGE.md) for complete timeout details.
- **[PROFILING.md](PROFILING.md)** - Performance profiling guide with flamegraph setup and optimization tips
- **[ROADMAP.md](ROADMAP.md)** - Planned features and future improvements
- **[RELEASE.md](RELEASE.md)** - Release process for maintainers
- **[EBPF_BUILD.md](EBPF_BUILD.md)** - eBPF build instructions and requirements
## Contributing