debugfs erkunden: Kernel-Internals jenseits von /proc und /sys

1. Wozu debugfs überhaupt existiert

Sowohl /proc als auch /sys unterliegen strengen Stabilitätsregeln: Einmal veröffentlichte Dateien und ihr Format gelten als stabile Kernel-ABI und dürfen nicht ohne Weiteres verändert werden, weil Userspace-Programme sich darauf verlassen. Das bremst Kernel-Entwickler, die schnell und ohne langfristige Kompatibilitätsversprechen Debug-Informationen exportieren wollen, spürbar aus.

debugfs wurde genau für diesen Zweck geschaffen: ein Dateisystem ohne jede Stabilitätsgarantie, in dem Kernel-Subsysteme beliebige interne Zustände als Dateien exponieren können, ohne Rücksicht auf Formatänderungen zwischen Kernel-Versionen nehmen zu müssen. Für Admins bedeutet das im Gegenzug: Was heute unter debugfs funktioniert, kann sich in einem späteren Kernel-Update ändern oder verschwinden, ohne Vorwarnung.

2. Mount-Punkt und Einrichtung von debugfs

Der Standard-Mount-Punkt für debugfs ist /sys/kernel/debug, auf den meisten modernen Distributionen bereits beim Systemstart automatisch eingehängt. Ob debugfs aktuell gemountet ist, lässt sich schnell über mount oder direkt durch einen Blick in das Verzeichnis prüfen, wobei ein leeres oder nicht existierendes Verzeichnis meist bedeutet, dass debugfs nicht aktiv ist.

Fehlt der Mount, etwa in einem minimalistisch konfigurierten Kernel oder in einer Container-Umgebung, lässt er sich manuell nachholen, sofern der Kernel mit CONFIG_DEBUG_FS gebaut wurde. In den meisten Distributions-Kerneln ist diese Option standardmäßig aktiviert.

# Pruefen, ob debugfs bereits gemountet ist
mount | grep debugfs

# Manuell mounten, falls nicht vorhanden
mount -t debugfs none /sys/kernel/debug

# Kernel-Konfiguration auf debugfs-Unterstützung pruefen
zgrep CONFIG_DEBUG_FS /proc/config.gz

3. Block-Layer-Statistiken unter debugfs

Für Storage-Diagnosen jenseits der aggregierten Zahlen aus /proc/diskstats liefert debugfs deutlich detailliertere Einblicke in den Block-Layer. Unter /sys/kernel/debug/block/<device> finden sich unter anderem Informationen zur I/O-Scheduler-Queue, zu ausstehenden Requests und, je nach Scheduler, zu internen Warteschlangen-Zuständen.

Besonders bei Performance-Problemen mit Datenbank- oder Elasticsearch-Volumes auf NVMe- oder SSD-Storage helfen diese Werte dabei, zwischen einem Problem im Kernel-I/O-Scheduler und einem Problem auf Ebene des Storage-Backends selbst zu unterscheiden, eine Unterscheidung, die aus iostat allein oft nicht eindeutig hervorgeht.

# Verfuegbare Block-Devices unter debugfs auflisten
ls /sys/kernel/debug/block/

# Scheduler-spezifische Statistiken für ein Geraet ansehen (Beispiel: nvme0n1)
find /sys/kernel/debug/block/nvme0n1/ -type f | xargs -I{} sh -c 'echo "== {} =="; cat {}'

4. Die Tracing-Infrastruktur unter debugfs/tracing

Das gesamte ftrace-Subsystem des Kernels, also das eingebaute Function-Tracing, wird traditionell über Dateien unter /sys/kernel/debug/tracing gesteuert, auch wenn ein Teil davon inzwischen zusätzlich über /sys/kernel/tracing erreichbar ist. Wer schon einmal perf oder trace-cmd verwendet hat, hat diese Infrastruktur bereits indirekt genutzt, ohne die rohen Dateien selbst anzufassen.

Für einen manuellen Blick genügt es, verfügbare Tracer über available_tracers aufzulisten, einen davon in current_tracer zu aktivieren und anschließend trace auszulesen. Dieser direkte, dateibasierte Zugriff ist zwar deutlich unkomfortabler als bpftrace oder perf, funktioniert aber auch auf minimalen Systemen ohne zusätzliche Pakete.

# Verfuegbare ftrace-Tracer auflisten
cat /sys/kernel/debug/tracing/available_tracers

# Function-Tracer aktivieren und kurz beobachten
echo function > /sys/kernel/debug/tracing/current_tracer
sleep 2
cat /sys/kernel/debug/tracing/trace | head -n 40

# Tracer wieder deaktivieren
echo nop > /sys/kernel/debug/tracing/current_tracer

5. Weitere Subsysteme mit eigenen debugfs-Einträgen

Neben Block-Layer und Tracing exponieren zahlreiche weitere Kernel-Subsysteme eigene debugfs-Verzeichnisse: Das Dateisystem ext4 etwa unter /sys/kernel/debug/ext4 mit internen Statistiken pro Mount, Netzwerktreiber häufig unter einem eigenen Verzeichnis mit Registerdumps, und der Speicherverwaltung nahe Subsysteme wie kmemleak für die Suche nach Speicherlecks im Kernel selbst.

Welche Verzeichnisse konkret existieren, hängt stark von geladenen Treibern und Kernel-Konfiguration ab, weshalb sich ein einfacher rekursiver Blick in /sys/kernel/debug lohnt, um zu sehen, was auf dem konkreten System tatsächlich verfügbar ist, statt sich auf eine feste Liste zu verlassen.

# Vorhandene debugfs-Unterverzeichnisse als Übersicht auflisten
find /sys/kernel/debug -maxdepth 1 -type d | sort

# ext4-spezifische Debug-Informationen für ein Dateisystem pruefen (falls vorhanden)
ls /sys/kernel/debug/ext4/ 2>/dev/null

6. Sicherheitsaspekte und Zugriffsbeschränkung

debugfs exponiert absichtlich sehr detaillierte, teils sicherheitsrelevante Kernel-Interna, unter anderem Speicheradressen, interne Zustände von Treibern und in manchen Fällen sogar kryptografisches Material während der Entwicklung. Aus diesem Grund ist der Zugriff standardmäßig auf Root beschränkt, und diese Beschränkung sollte auf produktiven Servern nicht gelockert werden.

Härtungsrichtlinien wie die des CIS-Benchmarks empfehlen zusätzlich, debugfs auf produktiven Systemen ganz zu deaktivieren oder zumindest read-only zu mounten, sofern keine aktive Diagnose läuft. Über den Kernel-Boot-Parameter debugfs=off lässt sich das Dateisystem bereits beim Boot komplett unterbinden, was auf gehärteten Produktionsservern ohne regelmäßigen Debug-Bedarf sinnvoll sein kann.

Gerade weil debugfs keine API-Stabilität garantiert und tief in Kernel-Interna blickt, sollte der Zugriff im Alltag auf gezielte, zeitlich begrenzte Diagnosesitzungen beschränkt bleiben, statt dauerhaft in Monitoring-Skripte eingebunden zu werden, die bei einem Kernel-Update plötzlich stillschweigend falsche oder gar keine Daten mehr liefern.

# Aktuelle Berechtigungen des Mount-Punkts pruefen
stat -c "%a %U:%G" /sys/kernel/debug

# debugfs beim naechsten Boot komplett deaktivieren (GRUB-Kernel-Parameter)
# in /etc/default/grub: GRUB_CMDLINE_LINUX="... debugfs=off"

7. Abgrenzung zu /proc und /sys

Der zentrale Unterschied liegt im Stabilitätsversprechen: /proc und /sys folgen klaren API-Regeln, Dateiformate dort gelten faktisch als Teil der Kernel-ABI und werden nur mit großer Vorsicht geändert. debugfs kennt dieses Versprechen bewusst nicht, was Entwicklern Freiheit verschafft, aber bedeutet, dass Skripte, die debugfs-Dateien parsen, bei jedem Major-Kernel-Update erneut geprüft werden sollten.

In der Praxis heißt das für Admins: Für dauerhafte Automatisierung und Monitoring-Integration sind /proc und /sys die verlässlichere Quelle, debugfs bleibt das Werkzeug für die punktuelle, tiefgehende Diagnose eines konkreten Problems, bei dem die Standard-Interfaces nicht genug Detailtiefe liefern.

8. Praktischer Workflow für eine debugfs-Diagnosesitzung

Ein sinnvoller Ablauf beginnt mit dem Prüfen, ob debugfs überhaupt gemountet ist, gefolgt von einer gezielten Suche im relevanten Unterverzeichnis, etwa block bei Storage-Problemen oder tracing bei Funktionsaufruf-Fragen. Änderungen an Tracer-Einstellungen sollten nach der Diagnose immer zurückgesetzt werden, insbesondere current_tracer wieder auf nop, um keinen dauerhaften Tracing-Overhead zu hinterlassen.

Da viele debugfs-Dateien schreibbar sind und direkte Kernel-Zustände beeinflussen können, etwa das Aktivieren eines Tracers oder das Zurücksetzen von Zählern, gehört jeder Schreibzugriff dokumentiert und, wo möglich, zuerst auf einem Test-System ausprobiert, bevor er auf einem produktiven Magento-Hosting-Server angewendet wird.

9. Häufige Fehler beim Umgang mit debugfs

Ein verbreiteter Fehler ist die Annahme, ein leeres oder fehlendes Verzeichnis unter /sys/kernel/debug bedeute automatisch, dass die entsprechende Kernel-Funktion nicht existiert. Häufig liegt die Ursache schlicht darin, dass debugfs gar nicht gemountet ist oder der zugehörige Treiber nicht geladen wurde, was sich mit einem Blick auf lsmod und den Mount-Status schnell klären lässt.

Ein weiterer typischer Stolperstein ist der Versuch, debugfs-Dateien als unprivilegierter Nutzer zu lesen, was in der Regel mit Permission denied quittiert wird, selbst wenn dieselbe Information unter /proc für alle Nutzer offen wäre. Das ist beabsichtigtes Verhalten und kein Konfigurationsfehler, weshalb entsprechende Diagnose-Skripte grundsätzlich mit Root-Rechten laufen sollten oder gezielt über sudo auf die relevante Datei zugreifen.

Schließlich führt das Verwechseln von debugfs-Pfaden zwischen Kernel-Versionen zu stillen Fehlern in Skripten: Ein Pfad, der unter Kernel 5.10 existierte, kann unter Kernel 6.x umbenannt oder in ein anderes Unterverzeichnis verschoben worden sein. Ein kurzer find-Aufruf vor jeder größeren Kernel-Migration schafft hier Klarheit, bevor produktive Monitoring-Skripte plötzlich leere Ausgaben liefern.

# Pruefen, ob der zugehoerige Treiber überhaupt geladen ist
lsmod | grep nvme

# Zugriff als root statt als unprivilegierter Nutzer testen
sudo cat /sys/kernel/debug/tracing/current_tracer

10. Zusammenfassung

11. FAQ: debugfs