Projektüberblick

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• README.md

ebpftracer ist ein experimentelles System-Tracing-Tool, das als persönliche Erkundung in die Linux-Systemprogrammierung und eBPF-Technologie (Extended Berkeley Packet Filter) konzipiert wurde. Das Projekt implementiert einen strace-ähnlichen Systemaufruf-Tracer vollständig in C unter Verwendung von libbpf, clang und dem Meson-Build-System. Der Hauptzweck besteht darin, Systemaufrufe eines spezifizierten Programms abzufangen und zu protokollieren, wobei eBPF-Tracepoints (raw_syscalls:sys_enter und raw_syscalls:sys_exit) für eine effiziente Erfassung auf Kernel-Ebene eingesetzt werden (README.md:1-5, README.md:12-14).

Die Architektur nutzt thread-sichere Hash-Maps, um Enter/Exit-Events korrekt zuzuordnen – eine kritische Anforderung für komplexe I/O-Operationen. Zu den fortgeschrittenen Ausgabefunktionen gehören die Auflösung von Dateideskriptoren zu absoluten Pfaden, das Dumpen von I/O-Daten für Systemaufrufe wie read, write, readv und writev sowie die Umwandlung relativer in absolute Pfadangaben. Das Projekt ist nicht als produktionsreifer Ersatz für Tools wie strace konzipiert, sondern dient als Lernplattform und technische Demonstration (README.md:14-18, README.md:19-23).

Technologie-Stack und Werkzeuge

Die folgende Tabelle fasst die im Projekt verwendeten Kerntechnologien zusammen:

(README.md:16-18)

Projektstruktur und Verzeichnisorganisation

Die Projektstruktur folgt einer klaren Trennung zwischen Kernel-Space-eBPF-Code und Userspace-Verarbeitungskomponenten:

ebpftracer/
├── src/
│   ├── tracer.bpf.c        # eBPF-Kernel-Programm
│   ├── tracer.c            # Userspace-Hauptanwendung
│   ├── handlers/           # Syscall-spezifische Handler
│   └── utils/              # Hilfsfunktionen
├── include/                # Header-Dateien
├── meson.build             # Meson-Build-Konfiguration
└── README.md               # Projektdokumentation

Die Kernarchitektur trennt strikt zwischen dem eBPF-Kernel-Modul, das Tracepoint-Events erfasst, und der Userspace-Anwendung, die für die Ereignisverarbeitung, Zustandsverwaltung und formatierte Ausgabe verantwortlich ist.

Systemarchitektur und Komponenteninteraktion

Die folgende Grafik zeigt die Hauptkomponenten des Systems und deren Abhängigkeiten:

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

Architektur-Erklärung:

1. Kernel-Space-Komponenten: Die eBPF-Programme werden an die Tracepoints raw_syscalls:sys_enter und raw_syscalls:sys_exit angehängt und erfassen jeden Systemaufruf im Kernel. Die erfassten Events werden über einen Perf Buffer an den Userspace gesendet (README.md:14).

2. Userspace-Hauptanwendung: Die C-Anwendung nutzt libbpf zum Laden und Verwalten des eBPF-Programms. Sie liest Events aus dem Perf Buffer und delegiert die Verarbeitung an spezialisierte Handler.

3. Zustandsverwaltung: Thread-sichere Hash-Maps ordnen Enter-Events ihren korrespondierenden Exit-Events zu, was für asynchrone I/O-Operationen essenziell ist (README.md:18).

4. Handler-System: Dedizierte Handler verarbeiten spezifische Systemaufrufe und extrahieren relevante Informationen wie Dateideskriptoren, Pufferinhalte und Pfadangaben (README.md:24-25).

Datenfluss und Event-Verarbeitungskette

Der folgende Ablauf zeigt die sequenzielle Verarbeitung eines Systemaufrufs vom Kernel bis zur formatierten Ausgabe:

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

Datenfluss-Erklärung:

1. Event-Erfassung: Bei jedem Systemaufruf löst der Kernel die registrierten Tracepoints aus. Das eBPF-Programm extrahiert Prozess-ID, Thread-ID, Syscall-Nummer und Argumente bzw. Rückgabewerte (README.md:14).

2. Enter/Exit-Korrelation: Die thread-sichere Hash-Map speichert bei sys_enter die Argumente unter der Thread-ID als Schlüssel. Bei sys_exit werden die gespeicherten Daten abgerufen und mit dem Rückgabewert kombiniert (README.md:18).

3. Spezialisierte Verarbeitung: Handler für I/O-Syscalls wie read, write, readv, writev dumpen die übertragenen Daten und lösen Dateideskriptoren zu Pfaden auf (README.md:20-22).

4. Ausgabeformatierung: Das Ausgabemodul formatiert die gesammelten Informationen inklusive aufgelöster Pfade und optionaler Daten-Dumps.

Kernfunktionalität und Implementierungsdetails

eBPF-Tracepoint-Integration

Das Projekt nutzt die Tracepoints raw_syscalls:sys_enter und raw_syscalls:sys_exit als primäre Event-Quellen. Diese Tracepoints werden bei jedem Systemaufruf im Kernel getriggert, unabhängig vom spezifischen Syscall-Typ. Die eBPF-Programme filtern Events anhand der Zielprozess-PID und übertragen nur relevante Daten an den Userspace (README.md:14).

Verantwortlichkeiten:

• Erfassung aller Systemaufrufe des Zielprozesses
• Extraktion von PID, TID, Syscall-Nummer und Argumenten
• Push von Event-Strukturen an den Perf Buffer

Nicht im Verantwortungsbereich:

• Interpretation von Syscall-Argumenten (erfolgt im Userspace)
• Speicherung von Zuständen über mehrere Events hinweg

Thread-sichere Zustandsverwaltung

Die Korrelation von Enter- und Exit-Events erfordert eine zuverlässige Zuordnung anhand der Thread-ID. Bei Multithreaded-Anwendungen können Syscall-Events unterschiedlicher Threads interleaved auftreten, was eine thread-sichere Datenstruktur notwendig macht (README.md:18).

Datenstruktur-Konzept:

Hash-Map Key: Thread-ID (TID)
Hash-Map Value: {
    syscall_number: int,
    args: [arg0, arg1, arg2, ...],
    timestamp_enter: uint64,
    fd_info: optional struct
}

Fehlerbehandlung:

• Fehlendes Enter-Event bei Exit: Warnung loggen, Event verwerfen
• Timeout für verwaiste Enter-Events: Periodische Bereinigung
• Hash-Map-Kollisionen: Chaining oder Open Addressing

Syscall-spezifische Handler

Das Projekt implementiert dedizierte Handler für eine definierte Menge von Systemaufrufen, die im GitHub-Issue #1 spezifiziert sind. Andere Syscalls werden gefiltert und nicht ausgegeben, was die Übersichtlichkeit erhöht (README.md:24-25).

Handler-Kategorien:

(README.md:19-23)

Dateideskriptor-Auflösung

Ein zentrales Feature ist die Zuordnung von Dateideskriptor-Nummern zu absoluten Pfaden. Dies erfordert die Nachverfolgung von open/openat-Aufrufen und die Pflege einer FD-zu-Pfad-Tabelle pro Prozess (README.md:20).

Implementierungsansatz:

1. Bei open/openat: Neuen Eintrag mit FD als Key und Pfad als Value erstellen
2. Bei read/write: FD nachschlagen und absoluten Pfad in Ausgabe einfügen
3. Bei close: Eintrag aus Tabelle entfernen
4. Bei dup/dup2/dup3: Eintrag für neuen FD kopieren

Randbedingungen:

• Relative Pfade werden unter Verwendung des aktuellen Arbeitsverzeichnisses aufgelöst
• Symbolic Links werden auf ihre Ziele aufgelöst
• /proc/self/fd/<fd> als Fallback für nicht getrackte FDs

I/O-Daten-Dump

Für Lese- und Schreiboperationen bietet der Tracer die Möglichkeit, die übertragenen Daten hexadezimal oder als ASCII-Darstellung auszugeben. Dies ist besonders nützlich für Debugging-Zwecke und Protokollanalyse (README.md:21).

Datenextraktion:

• Puffer-Pointer und Größe aus Syscall-Argumenten extrahieren
• Bei read: Daten nach erfolgreichem Exit aus Userspace lesen
• Bei write: Daten vor dem Enter-Event lesen
• Begrenzung der Dump-Größe zur Vermeidung von Overflow

Sicherheitsaspekte:

• Speicherzugriff nur innerhalb der Prozess-Grenzen
• Behandlung von ungültigen Pointern (Segmentation Fault Prevention)
• Optionale Filterung sensibler Daten

Erweiterte Ausgabefunktionen

Pfadauflösung

Der Tracer konvertiert relative Pfadangaben (z.B. ./file) in absolute Pfade (z.B. /home/user/file). Dies erfordert die Kenntnis des aktuellen Arbeitsverzeichnisses des Zielprozesses, das über /proc/<pid>/cwd ermittelt wird (README.md:22).

Auflösungslogik:

1. Prüfen, ob Pfad bereits absolut ist (beginnt mit /)
2. Bei relativem Pfad: CWD aus /proc/<pid>/cwd lesen
3. Pfad-Komponenten normalisieren (. und .. auflösen)
4. Symbolic Links verfolgen (optional konfigurierbar)

Formatierte Ausgabe

Die Ausgabe kombiniert Informationen aus Enter- und Exit-Events in einer lesbaren Formatierung:

[PID: 1234][TID: 1234] read(fd=3</home/user/file.txt>, buf=0x7fff..., count=1024) = 1024
  Data: 48656c6c6f20576f726c64... (Hello World...)

Die Formatierung beinhaltet:

• Prozess- und Thread-ID zur Identifikation
• Syscall-Name und aufgelöste Argumente
• Dateideskriptor mit zugehörigem Pfad in spitzen Klammern
• Rückgabewert und Fehlercodes
• Optional: Hex-Dump der übertragenen Daten

Quantifizierbare Projektkennzahlen

(README.md:16-18)

Anwendungsszenarien und Einsatzbereiche

Debugging und Fehlersuche:

• Analyse von Datei-I/O-Verhalten fehlerhafter Anwendungen
• Nachverfolgung von Konfigurationsdateizugriffen
• Identifikation von Permission-Denied-Problemen

Sicherheitsanalyse:

• Überwachung verdächtiger Systemaufrufe
• Erkennung von Dateizugriffen außerhalb erwarteter Pfade
• Analyse von Netzwerk-Syscalls (sofern implementiert)

Leistungsanalyse:

• Identifikation von Syscall-Hotspots
• Messung von I/O-Latenzen durch Enter/Exit-Timestamps
• Analyse von Blocking-Operationen

Bildung und Forschung:

• Verständnis von Linux-Syscall-Mechanismen
• Demonstration von eBPF-Tracing-Funktionalität
• Experimentelle Erweiterungen und Modifikationen

Berichtsstruktur und Lesepfad

Die folgende Grafik zeigt die empfohlene Lesereihenfolge für die technische Dokumentation:

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

Empfohlene Lesereihenfolge:

1. Projektüberblick (aktuelle Seite): Grundlegende Konzepte, Architektur und Kernfunktionalität verstehen
2. Architektur: Detaillierte Analyse der Komponentenstruktur und Abhängigkeiten
3. Datenfluss: Sequenzielle Verarbeitungsketten und Event-Korrelation
4. Features: Implementierungsdetails der spezifischen Ausgabefunktionen
5. API-Design: Schnittstellen zwischen Kernel- und Userspace-Komponenten
6. Deployment: Build-Prozess, Installation und Konfiguration

Technische Einschränkungen und Design-Entscheidungen

Nicht-Produktionsreif: Das Projekt ist explizit als Lernprojekt konzipiert und nicht als vollwertiger Ersatz für strace gedacht. Produktionsreife Features wie robuste Fehlerbehandlung, umfassende Dokumentation und Performance-Optimierungen sind nicht vollständig implementiert (README.md:5).

Eingeschränkte Syscall-Abdeckung: Nur die in GitHub-Issue #1 definierten Systemaufrufe werden verarbeitet und ausgegeben. Dies reduziert die Komplexität, schränkt aber die Anwendbarkeit für umfassende Tracing-Szenarien ein (README.md:24-25).

Kernel-Abhängigkeit: Die Funktionalität hängt von spezifischen Kernel-Features (eBPF, Tracepoints) ab, was die Portabilität auf ältere Systeme oder andere Betriebssysteme einschränkt.

Performance-Overhead: Obwohl eBPF als effiziente Tracing-Technologie gilt, verursacht die Erfassung und Verarbeitung jedes Systemaufrufs einen messbaren Overhead, der bei I/O-intensiven Anwendungen relevant sein kann.