A tiny Linux kernel module + Rust CLI that provides per-interface IPv4 traffic statistics in time buckets (default: 60s) with 48h retention.
The kernel exports a parse-friendly stream via:
/proc/packets_stats
The CLI turns that raw data into human-readable summaries (text) or machine-friendly output (CSV / JSON), supporting queries between dates.
This project consists of:
- A Linux kernel module (via DKMS) that tracks IPv4 packets and bytes per interface, stored in rolling time buckets.
- A Rust CLI that reads
/proc/packets_statsand aggregates the data over arbitrary time ranges.
The design is intentionally simple, fast, and human-readable, while remaining machine-friendly when needed.
- Per-interface statistics
- RX / TX split + totals
- Bucketed history (rolling window)
- Default bucket size: 60 seconds
- Default retention: 48 hours
- Query by time range:
--from "YYYY-MM-DD HH:MM"(or epoch seconds)--to "YYYY-MM-DD HH:MM"(or epoch seconds)
- Output formats:
--format text(default, human-readable)--format csv--format json
dkmslinux-headers-$(uname -r)(orlinux-headers-generic)build-essential(to compile the module withdkms)
dkmslinux-headers(for your kernel)
dkmskernel-devel(for your kernel)- Toolchain:
gcc,make
For building packages with scripts you will need:
docker
Scripts scripts/build-*.sh build inside Docker, you don't need any local toolchains to package.
gcc,make- Kernel headers:
/lib/modules/$(uname -r)/buildorlinux-headers-$(uname -r) rust+cargo(>= 1.79)
The project is packaged as three packages per distro:
- Installs the kernel module sources under:
/usr/src/packets-stats-<version>/ - Registers and builds the module via DKMS
- Automatically rebuilds on kernel upgrades
- Installs the Rust CLI as:
/usr/bin/packets-stats(Debian/RPM) or/usr/bin/packets-stats(Arch too) - Reads
/proc/packets_statsand formats the output
- Depends on both:
packets-stats-dkmspackets-stats-cli
- Allows installing everything with a single package (still usually installed together when using local files)
kernel/— kernel module sources + dkms.confcli/packets-stats/— Rust CLIpackaging/— packaging templates + Docker builder scriptspackaging/deb/packaging/arch/packaging/rpm/
scripts/— host entrypoints (build from Docker)scripts/build-deb.shscripts/build-arch.shscripts/build-rpm.sh
dist/— build output (generated)dist/deb/dist/arch/dist/rpm/
cd kernel
make -C /lib/modules/$(uname -r)/build M=$PWD modules
sudo insmod packets_stats.ko
head -n 10 /proc/packets_stats
sudo rmmod packets_stats
make -C /lib/modules/$(uname -r)/build M=$PWD cleancargo run --manifest-path cli/packets-stats/Cargo.toml -- \
--from "2025-12-15 14:00" \
--to "2025-12-15 14:10" \
--format textAll packaging is built inside Docker for reproducibility. Output is always written to dist/.
A common rule used in builders:
- Rust builds write to an isolated
CARGO_TARGET_DIR(e.g./tmp/cargo-target) to avoid permission issues and keeping your repo clean. - When templates are rendered with
envsubst, it is done with a whitelist of variables and with needed variables exported, to avoid accidentally replacing${pkgdir}/$PKG/ etc. with empty strings.
From the repository root:
./scripts/build-deb.shThis generates:
dist/deb/packets-stats-dkms_<version>_all.debdist/deb/packets-stats-cli_<version>_<arch>.debdist/deb/packets-stats_<version>_all.deb
Recommended (resolves deps) — copy to /tmp to avoid _apt sandbox permission warnings:
cp dist/deb/*.deb /tmp/
sudo apt install /tmp/packets-stats*.debIf DKMS didn’t build automatically (e.g., missing headers), install prerequisites and rebuild:
sudo apt install -y dkms build-essential linux-headers-$(uname -r)
sudo dkms install -m packets-stats -v "$(cat VERSION)" --force
sudo modprobe packets_statshead -n 10 /proc/packets_stats
packets-stats --from "2025-12-15 14:00" --to "2025-12-15 14:10" --format textsudo apt purge -y packets-stats packets-stats-cli packets-stats-dkms
sudo apt autoremove -y./scripts/build-arch.shThis generates (examples):
dist/arch/packets-stats-dkms-<ver>-1-any.pkg.tar.zstdist/arch/packets-stats-cli-<ver>-1-x86_64.pkg.tar.zstdist/arch/packets-stats-<ver>-1-any.pkg.tar.zst- Optionally:
dist/arch/packets-stats-cli-debug-...
Since these are local files (not a repo), install all three explicitly:
sudo pacman -U dist/arch/packets-stats-dkms-*.pkg.tar.zst \
dist/arch/packets-stats-cli-*.pkg.tar.zst \
dist/arch/packets-stats-*.pkg.tar.zstEnsure you have DKMS and kernel headers for your kernel:
sudo pacman -S --needed dkms linux-headersThen load the module:
sudo modprobe packets_statssudo pacman -Rns packets-stats packets-stats-cli packets-stats-dkms./scripts/build-rpm.shThis generates RPMs in:
dist/rpm/*.rpm
RPM packaging is stricter about Version:. If you use pre-release versions like 0.1.0-rc1, you typically need to map -rc1 to ~rc1 for correct ordering and to keep Version valid. The builder handles this conversion.
sudo dnf install ./dist/rpm/*.rpmIf your distro doesn’t provide dkms by default, you may need to enable the appropriate repository or install DKMS/kernel-devel first.
sudo dnf remove packets-stats packets-stats-cli packets-stats-dkms- The kernel module is not loaded.
- Or DKMS did not build for your running kernel yet.
Steps:
dkms status | grep packets-stats || true
sudo modprobe packets_stats
dmesg | tail -n 50On Debian/Ubuntu, check DKMS logs:
sudo cat /var/lib/dkms/packets-stats/$(cat VERSION)/build/make.logGPL-2.0-only. See License.