usb-ssd/docs/troubleshooting.md

USB-SSD Management System - Troubleshooting

Übersicht

Diese Anleitung hilft bei der Diagnose und Lösung häufiger Probleme mit dem USB-SSD Management System. Die Probleme sind nach Kategorien sortiert und enthalten detaillierte Lösungsschritte.

Allgemeine Diagnose-Tools

System-Informationen sammeln

# System-Status prüfen
./scripts/installation/install.sh --status

# Hardware-Informationen
lsusb -v | grep -A 10 "Mass Storage"
lsblk -f
dmesg | grep -i usb | tail -20

# Service-Status
sudo systemctl status ssd-detection.service
sudo systemctl status ssd-automount.service

# Log-Analyse
tail -50 /var/log/ssd-management.log
journalctl -u ssd-detection.service --since "1 hour ago"

Debug-Modus aktivieren

# Environment-Variables setzen
export SSD_DEBUG=true
export SSD_VERBOSE=true
export SSD_LOG_LEVEL=DEBUG

# Scripts mit Debug-Output ausführen
ssd-detect.sh --debug --verbose
ssd-mount-manager.sh diagnose
ssd-test-suite.sh --debug

Hardware-Probleme

Problem: USB-C SSD wird nicht erkannt

Symptome

• lsusb zeigt das Gerät nicht an
• Keine Kernel-Messages beim Anschließen
• ssd-detect.sh findet keine Geräte

Diagnose

# USB-Controller prüfen
lspci | grep -i usb

# USB-Geräte auflisten
lsusb -t

# Kernel-Messages überwachen
sudo dmesg -w
# SSD anschließen und Messages beobachten

# USB-Module prüfen
lsmod | grep -E "(usb|storage)"

Lösungsansätze

# 1. USB-Module neu laden
sudo modprobe -r usb_storage
sudo modprobe usb_storage

# 2. USB-Controller zurücksetzen
echo '1-1' | sudo tee /sys/bus/usb/drivers/usb/unbind
echo '1-1' | sudo tee /sys/bus/usb/drivers/usb/bind

# 3. Udev-Rules neu laden
sudo udevadm control --reload-rules
sudo udevadm trigger

# 4. Anderen USB-Port testen
# SSD an verschiedenen Ports testen

# 5. Power-Management prüfen
echo 'on' | sudo tee /sys/bus/usb/devices/*/power/control

Problem: SSD wird erkannt aber nicht als Block-Device

Symptome

• lsusb zeigt das Gerät an
• lsblk zeigt kein entsprechendes Device
• Kernel-Messages zeigen Fehler

Diagnose

# Block-Devices auflisten
lsblk -a

# SCSI-Devices prüfen
cat /proc/scsi/scsi

# Device-Mapper prüfen
sudo dmsetup ls

# Partition-Tabelle prüfen
sudo fdisk -l | grep -A 10 "Disk /dev/sd"

Lösungsansätze

# 1. SCSI-Bus neu scannen
echo "- - -" | sudo tee /sys/class/scsi_host/host*/scan

# 2. Partition-Tabelle reparieren
sudo parted /dev/sdb print
sudo parted /dev/sdb mklabel msdos  # Nur wenn nötig!

# 3. Device-Permissions prüfen
ls -la /dev/sd*
sudo chmod 660 /dev/sdb*

# 4. Storage-Module neu laden
sudo modprobe -r usb_storage
sudo modprobe usb_storage quirks=VENDOR:PRODUCT:u

Dateisystem-Probleme

Problem: NTFS-Dateisystem wird nicht unterstützt

Symptome

• Mount schlägt mit "unknown filesystem type 'ntfs'" fehl
• ssd-detect.sh erkennt Filesystem nicht
• NTFS-Tools nicht verfügbar

Diagnose

# NTFS-Support prüfen
cat /proc/filesystems | grep ntfs
which ntfs-3g
dpkg -l | grep ntfs

# Kernel-Module prüfen
lsmod | grep ntfs
modinfo ntfs

Lösungsansätze

# 1. NTFS-3G installieren
# Ubuntu/Debian
sudo apt update
sudo apt install ntfs-3g

# CentOS/RHEL
sudo yum install ntfs-3g

# 2. NTFS-Modul laden
sudo modprobe ntfs

# 3. Fuse-Support prüfen
sudo modprobe fuse
ls -la /dev/fuse

# 4. Alternative: exFAT verwenden
sudo apt install exfat-fuse exfat-utils

Problem: Filesystem-Korruption

Symptome

• Mount schlägt mit I/O-Fehlern fehl
• Dateien sind nicht lesbar
• ssd-test-suite.sh zeigt Filesystem-Fehler

Diagnose

# Filesystem-Check
sudo fsck.ntfs -f /dev/sdb1
sudo ntfsfix /dev/sdb1

# SMART-Daten prüfen
sudo smartctl -a /dev/sdb

# Bad-Blocks testen
sudo badblocks -v /dev/sdb1

Lösungsansätze

# 1. Read-Only Mount versuchen
sudo mount -t ntfs -o ro /dev/sdb1 /mnt/ssd-storage

# 2. Filesystem reparieren
sudo ntfsfix /dev/sdb1
sudo fsck.ntfs -f /dev/sdb1

# 3. Daten retten
sudo ddrescue /dev/sdb1 /backup/ssd-image.img /backup/ssd-mapfile

# 4. Neu formatieren (Datenverlust!)
sudo mkfs.ntfs -f /dev/sdb1

Mount-Probleme

Problem: Mount schlägt fehl

Symptome

• ssd-mount-manager.sh mount gibt Fehler zurück
• Mount-Point ist nicht verfügbar
• Permission-Denied Fehler

Diagnose

# Mount-Diagnose
ssd-mount-manager.sh diagnose

# Aktuelle Mounts prüfen
mount | grep ssd
findmnt /mnt/ssd-storage

# Mount-Point Status
ls -la /mnt/ssd-storage
stat /mnt/ssd-storage

# Berechtigungen prüfen
groups $USER
id $USER

Lösungsansätze

# 1. Mount-Point bereinigen
ssd-mount-manager.sh cleanup
sudo umount -f /mnt/ssd-storage
sudo rmdir /mnt/ssd-storage
sudo mkdir -p /mnt/ssd-storage

# 2. Berechtigungen korrigieren
sudo chown root:root /mnt/ssd-storage
sudo chmod 755 /mnt/ssd-storage

# 3. Manueller Mount-Test
sudo mount -t ntfs /dev/sdb1 /mnt/ssd-storage
sudo mount -t ntfs -o uid=1000,gid=1000 /dev/sdb1 /mnt/ssd-storage

# 4. Recovery-Modus
ssd-mount-manager.sh recover

Problem: Mount hängt oder ist langsam

Symptome

• Mount-Operation dauert sehr lange
• System reagiert nicht während Mount
• Hohe I/O-Wait Zeiten

Diagnose

# I/O-Status prüfen
iostat -x 1
iotop

# Mount-Optionen prüfen
mount | grep ssd-storage

# USB-Performance prüfen
sudo hdparm -t /dev/sdb1
sudo dd if=/dev/sdb1 of=/dev/null bs=1M count=100

Lösungsansätze

# 1. Mount-Optionen optimieren
sudo mount -t ntfs -o big_writes,cache=strict /dev/sdb1 /mnt/ssd-storage

# 2. USB-Performance tunen
echo mq-deadline | sudo tee /sys/block/sdb/queue/scheduler
echo 1024 | sudo tee /sys/block/sdb/queue/read_ahead_kb

# 3. Timeout erhöhen
export SSD_MOUNT_TIMEOUT=120
ssd-mount-manager.sh mount

# 4. Alternative Mount-Methode
sudo mount.ntfs-3g /dev/sdb1 /mnt/ssd-storage -o uid=1000,gid=1000

Service-Probleme

Problem: Systemd-Services starten nicht

Symptome

• systemctl start ssd-detection.service schlägt fehl
• Services sind im "failed" Status
• Boot-Prozess hängt bei SSD-Services

Diagnose

# Service-Status detailliert
sudo systemctl status ssd-detection.service -l
sudo systemctl status ssd-automount.service -l

# Service-Logs
sudo journalctl -u ssd-detection.service --no-pager
sudo journalctl -u ssd-automount.service --since "1 hour ago"

# Service-Konfiguration prüfen
sudo systemctl cat ssd-detection.service
sudo systemd-analyze verify /etc/systemd/system/ssd-detection.service

Lösungsansätze

# 1. Services neu laden
sudo systemctl daemon-reload
sudo systemctl reset-failed ssd-detection.service

# 2. Service-Konfiguration reparieren
sudo systemctl edit ssd-detection.service
# [Service]
# Restart=on-failure
# RestartSec=5

# 3. Dependencies prüfen
sudo systemctl list-dependencies ssd-detection.service

# 4. Service manuell testen
sudo /usr/local/bin/ssd-detect.sh --monitor

Problem: Udev-Rules funktionieren nicht

Symptome

• Automatische Erkennung funktioniert nicht
• USB-Events lösen keine Scripts aus
• Manuelle Erkennung funktioniert

Diagnose

# Udev-Rules prüfen
ls -la /etc/udev/rules.d/99-ssd-*
cat /etc/udev/rules.d/99-ssd-automount.rules

# Udev-Events testen
sudo udevadm monitor --environment --udev
# SSD anschließen und Events beobachten

# Rule-Syntax testen
sudo udevadm test /sys/block/sdb

Lösungsansätze

# 1. Rules neu laden
sudo udevadm control --reload-rules
sudo udevadm trigger

# 2. Rule-Syntax korrigieren
sudo nano /etc/udev/rules.d/99-ssd-automount.rules
# Korrekte Syntax:
# SUBSYSTEM=="block", ATTRS{removable}=="1", ACTION=="add", RUN+="/usr/local/bin/ssd-detect.sh --device %k"

# 3. Permissions prüfen
sudo chmod 644 /etc/udev/rules.d/99-ssd-automount.rules

# 4. Udev-Service neu starten
sudo systemctl restart systemd-udevd

Performance-Probleme

Problem: Langsame SSD-Performance

Symptome

• ssd-test-suite.sh zeigt schlechte Performance
• Datei-Operationen sind langsam
• Benchmark-Werte unter Erwartung

Diagnose

# Performance-Benchmark
ssd-test-suite.sh --benchmark --detailed

# Hardware-Performance testen
sudo hdparm -t /dev/sdb1
sudo dd if=/dev/zero of=/mnt/ssd-storage/testfile bs=1M count=1000

# USB-Geschwindigkeit prüfen
lsusb -t
cat /sys/bus/usb/devices/*/speed

Lösungsansätze

# 1. USB 3.0+ Port verwenden
# SSD an USB 3.0+ Port anschließen

# 2. Mount-Optionen optimieren
sudo mount -o remount,big_writes,cache=strict /mnt/ssd-storage

# 3. I/O-Scheduler optimieren
echo mq-deadline | sudo tee /sys/block/sdb/queue/scheduler

# 4. Read-Ahead tunen
echo 2048 | sudo tee /sys/block/sdb/queue/read_ahead_kb

# 5. SSD-Health prüfen
sudo smartctl -a /dev/sdb

Problem: Hohe CPU-Last bei SSD-Operationen

Symptome

• Hohe CPU-Auslastung während Mount/Unmount
• System reagiert langsam bei SSD-Zugriff
• top zeigt hohe System-CPU

Diagnose

# CPU-Usage überwachen
top -p $(pgrep -f ssd-)
htop

# I/O-Wait analysieren
iostat -x 1 10

# Prozess-Analyse
sudo strace -p $(pgrep -f ssd-mount-manager)

Lösungsansätze

# 1. Nice-Level anpassen
sudo renice -n 10 $(pgrep -f ssd-)

# 2. I/O-Priorität setzen
sudo ionice -c 3 -p $(pgrep -f ssd-)

# 3. Concurrent-Operations reduzieren
export SSD_MAX_PARALLEL_OPS=1

# 4. Caching optimieren
echo 1 | sudo tee /proc/sys/vm/drop_caches

Eject-Probleme

Problem: Safe-Eject schlägt fehl

Symptome

• ssd-safe-eject.sh gibt Fehler zurück
• "Device is busy" Meldungen
• Unmount schlägt fehl

Diagnose

# Blockierende Prozesse finden
ssd-safe-eject.sh --show-processes
lsof /mnt/ssd-storage
fuser -v /mnt/ssd-storage

# Mount-Status prüfen
mount | grep ssd-storage
findmnt /mnt/ssd-storage

# Buffer-Status prüfen
cat /proc/meminfo | grep -E "(Dirty|Writeback)"

Lösungsansätze

# 1. Prozesse beenden
ssd-safe-eject.sh --kill-processes
sudo fuser -km /mnt/ssd-storage

# 2. Buffer-Flush erzwingen
sync
echo 3 | sudo tee /proc/sys/vm/drop_caches

# 3. Force-Unmount
sudo umount -f /mnt/ssd-storage
sudo umount -l /mnt/ssd-storage  # Lazy unmount

# 4. Hardware-Reset
echo 1 | sudo tee /sys/block/sdb/device/delete

Problem: Hardware-Eject funktioniert nicht

Symptome

• Unmount erfolgreich, aber LED blinkt weiter
• SSD kann nicht physisch entfernt werden
• eject Befehl schlägt fehl

Diagnose

# Eject-Fähigkeiten prüfen
sudo hdparm -I /dev/sdb | grep -i removable
cat /sys/block/sdb/removable

# SCSI-Eject testen
sudo sg_start --eject /dev/sdb

Lösungsansätze

# 1. Standard-Eject
sudo eject /dev/sdb

# 2. SCSI-Eject
sudo sg_start --stop --eject /dev/sdb

# 3. USB-Device entfernen
echo 1 | sudo tee /sys/block/sdb/device/delete

# 4. Power-Management
echo auto | sudo tee /sys/block/sdb/device/power/control

Logging-Probleme

Problem: Logs werden nicht erstellt

Symptome

• Log-Dateien sind leer oder existieren nicht
• Keine Einträge in Systemd-Journal
• Debug-Output wird nicht angezeigt

Diagnose

# Log-Verzeichnisse prüfen
ls -la /var/log/ssd-*
ls -la /var/log/syslog

# Berechtigungen prüfen
stat /var/log/ssd-management.log
sudo -u ssd-user touch /var/log/test.log

# Syslog-Konfiguration
cat /etc/rsyslog.d/50-ssd-management.conf
sudo systemctl status rsyslog

Lösungsansätze

# 1. Log-Verzeichnisse erstellen
sudo mkdir -p /var/log/ssd-management
sudo chown syslog:adm /var/log/ssd-management

# 2. Berechtigungen korrigieren
sudo chmod 644 /var/log/ssd-*.log
sudo chown syslog:adm /var/log/ssd-*.log

# 3. Syslog neu starten
sudo systemctl restart rsyslog

# 4. Manuelle Log-Tests
logger -t ssd-test "Test message"
tail -f /var/log/syslog | grep ssd-test

Erweiterte Diagnose

Vollständige System-Diagnose

#!/bin/bash
# system-diagnosis.sh

echo "=== USB-SSD System Diagnosis ==="
echo "Date: $(date)"
echo "User: $(whoami)"
echo

echo "=== System Information ==="
uname -a
lsb_release -a 2>/dev/null || cat /etc/os-release
echo

echo "=== Hardware Information ==="
lsusb -v | grep -A 10 "Mass Storage"
lsblk -f
lspci | grep -i usb
echo

echo "=== Service Status ==="
systemctl status ssd-detection.service --no-pager
systemctl status ssd-automount.service --no-pager
echo

echo "=== Mount Status ==="
mount | grep ssd
findmnt /mnt/ssd-storage
echo

echo "=== Log Analysis ==="
tail -20 /var/log/ssd-management.log
journalctl -u ssd-detection.service --since "1 hour ago" --no-pager
echo

echo "=== Performance Test ==="
if [ -b /dev/sdb1 ]; then
    sudo hdparm -t /dev/sdb1
fi
echo

echo "=== Configuration ==="
cat /etc/ssd-management/config.conf 2>/dev/null || echo "No config file found"
echo

echo "=== Diagnosis Complete ==="

Log-Sammlung für Support

#!/bin/bash
# collect-logs.sh

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
LOGDIR="/tmp/ssd-logs-$TIMESTAMP"

mkdir -p "$LOGDIR"

# System-Logs
cp /var/log/ssd-*.log "$LOGDIR/" 2>/dev/null
journalctl -u ssd-detection.service > "$LOGDIR/systemd-detection.log"
journalctl -u ssd-automount.service > "$LOGDIR/systemd-automount.log"

# Konfiguration
cp -r /etc/ssd-management/ "$LOGDIR/config/" 2>/dev/null
cp /etc/udev/rules.d/99-ssd-*.rules "$LOGDIR/" 2>/dev/null

# System-Informationen
./system-diagnosis.sh > "$LOGDIR/diagnosis.txt"

# Archiv erstellen
tar -czf "ssd-logs-$TIMESTAMP.tar.gz" -C /tmp "ssd-logs-$TIMESTAMP"
echo "Logs collected in: ssd-logs-$TIMESTAMP.tar.gz"

Support-Kontakt

Vor Support-Anfrage

1. Diagnose durchführen: system-diagnosis.sh ausführen
2. Logs sammeln: collect-logs.sh verwenden
3. Reproduzierbarkeit: Problem-Schritte dokumentieren
4. System-Details: Hardware und Software-Versionen angeben

Community-Support

• Issues: Repository Issues
• Discussions: Repository-Discussions für allgemeine Fragen
• Wiki: Repository Wiki

Enterprise-Support

Für professionellen Support und Custom-Entwicklungen kontaktieren Sie die GitCover® Organization.

---

⚠️ Wichtiger Hinweis: Bei kritischen Produktionsproblemen immer zuerst Backups erstellen und in einer Testumgebung reproduzieren, bevor Lösungsschritte angewendet werden.