Setup installation

This commit is contained in:
2025-08-07 19:28:22 +02:00
parent e3f6363844
commit 17d74b261d
19 changed files with 6144 additions and 0 deletions

660
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,660 @@
# 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.