# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
#!/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
```bash
#!/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](https://git.gitcover.de/KMU/usb-ssd/issues)
- **Discussions**: Repository-Discussions für allgemeine Fragen
- **Wiki**: [Repository Wiki](https://git.gitcover.de/KMU/usb-ssd/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.