Schnellstart - KnightChaser/ebpftracer

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

ebpftracer ist ein einfaches strace-ähnliches Werkzeug zur Verfolgung von Systemaufrufen unter Linux, das mit C und eBPF entwickelt wurde. Das Projekt nutzt eBPF-Tracepoints (raw_syscalls:sys_enter und raw_syscalls:sys_exit), um Ereignisse effizient auf Kernel-Ebene zu erfassen und an eine Userspace-C-Anwendung zur Verarbeitung und Ausgabe zu senden README.md:12-15.

Voraussetzungen und Umgebung

Systemanforderungen

Das Projekt erfordert ein Linux-System mit einem modernen Kernel, der BTF (BSS Type Format) unterstützt. Diese Anforderung ist zwingend, da eBPF-Programme auf die Kernel-Typdefinitionen angewiesen sind README.md:28-35.

Erforderliche Komponenten:

Komponente	Zweck	Hinweis
Linux Kernel mit BTF	Kernel-Typdefinitionen	Moderner Kernel erforderlich
`clang` und `llvm`	Kompilierung der eBPF-Programme	Toolchain für BPF-Target
`libbpf`	Userspace-Bibliothek	Development-Paket erforderlich
`bpftool`	Generierung von `vmlinux.h`	Für BTF-Dump und Skeleton
`meson`	Build-System	C/C++ Build-System

Build-Optionen für verschiedene Umgebungen

Das Projekt bietet eine spezielle Build-Option für Umgebungen ohne eBPF-Unterstützung, wie CI/CD-Pipelines oder CodeQL-Analysen. Die Option skip_bpf ermöglicht das Überspringen der eBPF-Artefaktgenerierung meson_options.txt:1-6.

Toolchain-Konfiguration

Die Datei clang.ini definiert die LLVM/Clang-Toolchain-Konfiguration für den Build-Prozess. Diese Konfiguration stellt sicher, dass alle Binärtools aus der LLVM-Suite verwendet werden clang.ini:1-11.

[binaries]
c       = 'clang'
cpp     = 'clang++'
c_ld    = 'lld'
cpp_ld  = 'lld'
ar      = 'llvm-ar'

Repository klonen und einrichten

Klonen mit Submodulen

Das Repository muss mit allen Submodulen geklont werden, da das Projekt externe Abhängigkeiten wie hashmap.c enthält. Der Befehl zum Klonen lautet README.md:38-42:

sh
1git clone --recurse-submodules https://github.com/KnightChaser/ebpftracer.git
2cd ebpf-tracer

Projektstruktur verstehen

Die Projektstruktur wird durch die Meson-Build-Konfiguration definiert. Das Projekt verwendet den C11-Standard und eine Warnstufe von 2 meson.build:1-19. Die Hauptverzeichnisse umfassen:

src/: Hauptquellcode mit eBPF-Controller und Userspace-Loader
src/syscalls/: Syscall-Handler und Hilfsfunktionen
src/utils/: Hilfsprogramme für Logging und Pfadoperationen
test/: Testprogramme

eBPF-Artefakte generieren

Manuelle Generierung

Die Userspace-Anwendung hängt von einigen kernelspezifischen Headern ab, die auf dem Host-System generiert werden müssen. Dieser Schritt ist erforderlich, da diese Dateien kernelspezifisch sind und nicht in die Versionskontrolle eingecheckt werden README.md:44-55.

Schritt 1: vmlinux.h generieren

sh
1bpftool btf dump file /sys/kernel/btf/vmlinux format c > src/vmlinux.h

Schritt 2: eBPF-Objekt kompilieren

sh
1clang -g -O2 -target bpf -c src/controller.c -o src/controller.bpf.o

Schritt 3: Skeleton-Header generieren

sh
1bpftool gen skeleton src/controller.bpf.o > src/controller.skel.h

Automatisierte Generierung durch Meson

Das Build-System automatisiert die Generierung der eBPF-Artefakte, wenn die Option skip_bpf nicht gesetzt ist. Der Prozess umfasst drei Hauptschritte src/meson.build:30-55:

vmlinux.h-Generierung: bpftool extrahiert BTF-Informationen aus dem Kernel
BPF-Objektkompilierung: clang kompiliert den eBPF-Code mit -target bpf
Skeleton-Erstellung: bpftool gen skeleton erstellt den Userspace-Header

Projekt kompilieren mit Meson

Empfohlener Build-Pfad

Die Kompilierung erfolgt mit dem Meson-Build-System unter Verwendung der Clang-Toolchain README.md:56-62:

sh
1meson setup builddir --native-file=clang.ini
2cd builddir
3meson compile

Dieser Prozess erstellt die ausführbare Datei ebpftracer im Verzeichnis builddir.

Executable-Definition

Die Executable wird mit allen erforderlichen Quellcodedateien und Abhängigkeiten definiert src/meson.build:67-133. Die Hauptkomponenten umfassen:

BPF-Skeleton: controller.skel.h für Userspace-Zugriff auf eBPF-Maps
Syscall-Handler: Dedizierte Handler für verschiedene Syscall-Typen
Hilfsprogramme: Logger, Pfadoperationen und Byte-Konvertierung
Externe Abhängigkeiten: libbpf und hashmap.c

Alternative Build-Optionen

Option	Befehl	Anwendungsfall
Standard-Build	`meson setup builddir --native-file=clang.ini`	Normale Entwicklung
CI/CD-Build	`meson setup builddir -Dskip_bpf=true`	Umgebungen ohne eBPF
Installation	`meson install -C builddir`	Systemweite Installation

Anwendung ausführen

Grundlegende Verwendung

Der Tracer wird mit sudo ausgeführt, da eBPF-Programme Root-Rechte erfordern. Die Syntax ähnelt strace README.md:64-71:

sh
1# Aus dem builddir-Verzeichnis
2sudo ./src/ebpftracer /bin/ls -l /tmp

Programmfluss und Architektur

Die Anwendung verwendet einen Fork-Mechanismus, um das Zielprogramm zu starten und eBPF-Programme daran anzuhängen src/main.c:19-31:

正在加载图表渲染器...

Initialisierung und Event-Verarbeitung

Der BPF-Loader initialisiert das Skeleton und registriert die Syscall-Handler src/loader.c:131-190. Die Event-Verarbeitung erfolgt über einen Ring-Buffer, der Syscall-Einträge und -Austritte verarbeitet.

Ausführung verifizieren

Erfolgreiche Ausführung erkennen

Bei erfolgreicher Ausführung erscheint eine Ausgabe, die den Syscall-Trace anzeigt src/main.c:79-83:

-------------- Syscall Trace ---------------
[Syscall-Ausgaben...]

------------ Syscall Trace Ended ------------

Prozessstatus-Überprüfung

Der Tracer meldet den Status des Kindprozesses nach Beendigung src/main.c:90-99:

Normal beendet: Child process exited with status: X
Durch Signal beendet: Child process killed by signal: X
Durch Signal gestoppt: Child process stopped by signal: X

Häufige Probleme und Fehlerbehebung

Problem 1: BTF wird nicht unterstützt

Symptom: Fehler beim Ausführen von bpftool btf dump

Lösung: Überprüfen, ob der Kernel BTF unterstützt:

sh
1ls /sys/kernel/btf/vmlinux

Wenn die Datei nicht existiert, ist ein Kernel mit BTF-Unterstützung erforderlich. Die Datei /sys/kernel/btf/vmlinux wird vom Build-System als Quelle für BTF-Informationen verwendet src/meson.build:34-39.

Problem 2: Fehlende libbpf-Abhängigkeit

Symptom: Kompilierungsfehler bezüglich libbpf

Lösung: Das Build-System erfordert libbpf als zwingende Abhängigkeit src/meson.build:3-4. Installation unter Ubuntu/Debian:

sh
1sudo apt install libbpf-dev

Problem 3: Berechtigungsfehler

Symptom: Fehler beim Laden des eBPF-Programms

Lösung: eBPF-Programme erfordern Root-Rechte. Die Anwendung muss mit sudo ausgeführt werden README.md:70. Der Loader meldet einen Fehler, wenn das BPF-Objekt nicht geladen werden kann src/loader.c:163-166.

Problem 4: CI/CD ohne eBPF-Unterstützung

Symptom: Build-Fehler in CI-Umgebungen

Lösung: Die Option skip_bpf verwenden, um Stub-Dateien zu generieren meson_options.txt:1-6:

sh
1meson setup builddir -Dskip_bpf=true

Nächste Schritte

Nach erfolgreicher Installation und Verifikation können folgende Themen erkundet werden:

Unterstützte Syscalls: Das Projekt verfügt über dedizierte Handler für spezifische Syscalls wie read, write, open, close und weitere src/loader.c:31-58
Dateideskriptor-Cache: Der Tracer löst Dateideskriptoren zu absoluten Pfaden auf
I/O-Daten-Dump: Für I/O-Syscalls wie read, write, readv und writev werden Daten ausgegeben

Für fortgeschrittene Konfigurationen und detaillierte Nutzungshinweise wird auf die weiterführende Dokumentation verwiesen.