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>
145 lines
6.5 KiB
Text
145 lines
6.5 KiB
Text
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
|