opensnitch/ebpf_prog
trvon 60cd4311a8
build: daemon-only fork build + Arch packaging, kernel-matched eBPF
Add a daemon-only build path (no Python GUI) that builds the eBPF objects
against the running kernel's headers, deriving the BPF DataLayout from
clang and finalizing with opt; a structural unprivileged check target; an
install path that never clobbers existing units/config/rules; an Arch
PKGBUILD.in + prepare.sh and a test_install.sh harness. Document the
workflow and the event-loss diagnostics in README.md and ebpf_prog/README.
Gitignore the compiled ebpf_prog/*.o artifacts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-11-05 16:58:22 -07:00
..
bpf_headers Add loongarch64 support 2025-04-30 02:39:27 +00:00
tests daemon: event-loss diagnostics via per-module event_stats counters 2026-11-05 16:58:11 -07:00
arm-clang-asm-fix.patch ebpf: added patch to compile ebpf module for arm 2021-04-21 20:49:31 +02:00
common.h ebpf: arm improvements 2025-04-14 17:43:41 +02:00
common_defs.h ebpf: added support for ipv6 tunnels 2025-05-05 00:34:25 +02:00
event_stats.h daemon: event-loss diagnostics via per-module event_stats counters 2026-11-05 16:58:11 -07:00
Makefile build: daemon-only fork build + Arch packaging, kernel-matched eBPF 2026-11-05 16:58:22 -07:00
opensnitch-dns.c daemon: event-loss diagnostics via per-module event_stats counters 2026-11-05 16:58:11 -07:00
opensnitch-procs.c daemon: event-loss diagnostics via per-module event_stats counters 2026-11-05 16:58:11 -07:00
opensnitch.c ebpf: added support for ipv6 tunnels 2025-05-05 00:34:25 +02:00
README build: daemon-only fork build + Arch packaging, kernel-matched eBPF 2026-11-05 16:58:22 -07:00

Compilation requires getting kernel sources for now.

There's a helper script to automate this process:
 https://github.com/evilsocket/opensnitch/blob/master/utils/packaging/build_modules.sh

 (example to compile the modules for kernel 6.0: bash build_modules.sh 6.0)

---

The basic steps to manually compile the modules are:

  sudo apt install -y wget flex bison ca-certificates wget python3 rsync bc libssl-dev clang llvm libelf-dev libzip-dev git libpcap-dev
  cd opensnitch
  wget https://github.com/torvalds/linux/archive/v6.0.tar.gz
  tar -xf v6.0.tar.gz
  cd linux-6.0 && yes "" | make oldconfig && make prepare && make headers_install # (1 min)
  cd ../ebpf_prog/
  make KERNEL_DIR=../linux-6.0/ KERNEL_HEADERS=../linux-6.0/
  objdump -h opensnitch.o # you should see many sections, number 1 should be called kprobe/tcp_v4_connect
  llvm-strip -g opensnitch*.o # remove debug info
  sudo cp opensnitch*.o /usr/lib/opensnitchd/ebpf/ # or /etc/opensnitchd for < v1.6.x

Since v1.6.0, opensnitchd expects to find the opensnitch*.o modules under:
 /usr/local/lib/opensnitchd/ebpf/
 /usr/lib/opensnitchd/ebpf/
 /etc/opensnitchd/ # deprecated, only on < v1.5.x

start opensnitchd with:

  opensnitchd -rules-path /etc/opensnitchd/rules -process-monitor-method ebpf

---

### Arch Linux and current LLVM

Use prepared headers for the kernel that will run the programs. On Arch,
`/usr/lib/modules/$(uname -r)/build` is supplied by the matching kernel headers
package. Install matching headers before building; do not silently choose a
different installed kernel. The build needs `clang`, `llc` and `opt` from the
same LLVM release; `check` also uses `readelf` (binutils).

From the repository root:

  kver="$(uname -r)"
  kdir="/usr/lib/modules/$kver/build"
  make -C ebpf_prog -j1 check KERNEL_VER="$kver" KERNEL_DIR="$kdir" KERNEL_HEADERS="$kdir"

The native Clang frontend interprets the kernel's architecture-specific headers.
The build then derives the BPF DataLayout from Clang and uses `opt` to explicitly
retarget and verify the optimized IR before BPF code generation. This avoids
LLVM 23's native/BPF DataLayout mismatch without compiling the kernel headers
under the wrong architecture. The x86 ftrace header marker is supplied without
enabling host function-entry instrumentation. Host-only branch-protection flags
are not applicable to BPF objects; this does not change daemon compiler flags.

`check` requires all three objects to be BPF ELF files with their expected hook
sections. It is unprivileged and does NOT establish kernel verifier acceptance,
attachment or correct runtime behavior. The build/check has been exercised on
x86_64 with LLVM 23.1.4 and Arch kernel headers 7.2.14-arch1-1; other architectures
and toolchain/kernel combinations need their own validation.

After a successful build/check, strip and install the objects (no Python GUI is
needed):

  llvm-strip -g ebpf_prog/opensnitch.o ebpf_prog/opensnitch-dns.o ebpf_prog/opensnitch-procs.o && \
    sudo install -Dm644 ebpf_prog/opensnitch.o ebpf_prog/opensnitch-dns.o ebpf_prog/opensnitch-procs.o -t /usr/local/lib/opensnitchd/ebpf/

Installing the daemon with `make -C daemon install` does not install these
objects. Keep the intended configuration/rules and review daemon logs when the
operator starts the service; do not hide load errors by switching backends.

### Event-loss diagnostics (in-process API)

The process and DNS modules include an `event_stats` per-CPU array: one
16-byte value per possible CPU, counting attempted and failed ring-buffer
emissions. Map bookkeeping is additional. Emission return values and event
payloads are unchanged. These counters cover emission attempts, not hooks that
never ran or events lost before an emission was attempted.

The daemon exposes `core.SnapshotEventDiagnostics()` as a read-only Go API.
This increment does **not** add a CLI/UI/RPC endpoint, signal handler, collector
or polling thread. Kernel totals describe the current module `Generation`;
userspace totals accumulate over the daemon lifetime. Always check kernel
`Available` and `Status`: old objects without the optional map, incompatible
layouts, unsupported CPU counts, unbound modules and read errors are unavailable,
not evidence of zero loss. Map availability does not prove hook attachment.

Userspace `Received` counts successful ring-buffer reads. `Enqueued` counts
successful channel sends, including records subsequently drained; `DroppedCurrent`
counts discarded incoming records and `Drained` counts discarded queued records.
`Dequeued`, `Decoded`, `DecodeErrors`, `Canceled` and `ReaderErrors` distinguish
worker/reader stages. Decoding success does not mean successful attribution.
The existing discard-current-and-drain overflow policy and worker counts remain
unchanged. There are no path, argv or PID labels in these statistics.

Snapshots are not atomic across counters or CPUs; evaluate accounting at
quiescent checkpoints, keep kernel generations separate, and remember unsigned
64-bit totals can wrap. Before a collection closes, its diagnostic binding is
retired and any in-flight snapshot finishes. Snapshots reject CPU counts above
8192; their explicit value buffer is at most 128 KiB per module read, excluding
library overhead. Counters alone do not establish complete telemetry or a CPU
improvement. Kernel verifier/attachment, live loss rates and host overhead still
need operator-owned validation.

### Compiling for Fedora (and others rpm based systems)

You need to install the kernel-devel, clang and llvm packages.

Then: `cd ebpf_prog/ ; make KERNEL_DIR=/usr/src/kernels/$(uname -r)/`

(or just pass the kernel version you want)

### Notes

The kernel where you intend to run it must have some options activated:

 $ grep BPF /boot/config-$(uname -r)
  CONFIG_CGROUP_BPF=y
  CONFIG_BPF=y
  CONFIG_BPF_SYSCALL=y
  CONFIG_BPF_EVENTS=y
  CONFIG_KPROBES=y
  CONFIG_KPROBE_EVENTS=y

For the opensnitch-procs.o module to work, this option must be enabled:

 $ grep FTRACE_SYSCALLS /boot/config-$(uname -r)
  CONFIG_FTRACE_SYSCALLS=y

(https://github.com/iovisor/bcc/blob/master/docs/kernel_config.md)

Also, in some distributions debugfs is not mounted automatically.
Since v1.6.0 we try to mount it automatically. If you're running
a lower version so you'll need to mount it manually:

 $ sudo mount -t debugfs none /sys/kernel/debug

In order to make it permanent add it to /etc/fstab:

debugfs    /sys/kernel/debug      debugfs  defaults  0 0


opensnitch-procs.o and opensnitch-dns.o are only compatible with kernels >= 5.5,
bpf_probe_read_user*() were added on that kernel on:
https://github.com/iovisor/bcc/blob/master/docs/kernel-versions.md#helpers