usb-ssd/docs/usage-guide.md

USB-SSD Management System - Nutzungshandbuch

Übersicht

Dieses Handbuch beschreibt die detaillierte Nutzung aller Funktionen des USB-SSD Management Systems. Es richtet sich an System-Administratoren, DevOps-Engineers und Entwickler in KMU-Umgebungen.

Grundlegende Konzepte

Konstanter Mount-Point

Das System verwendet einen konstanten logischen Mount-Point (/mnt/ssd-storage), unabhängig von der physischen SSD:

• Vorteil: Anwendungen können immer denselben Pfad verwenden
• Flexibilität: SSDs können gewechselt werden ohne Anpassung der Konfiguration
• SMB-Integration: Freigaben bleiben konstant verfügbar

UUID-basierte Identifikation

Alle Operationen basieren auf UUID-Identifikation statt Device-Namen:

• Stabilität: Unabhängig von USB-Port-Wechseln
• Sicherheit: Eindeutige Identifikation verhindert Verwechslungen
• Logging: Nachverfolgbare Audit-Trails

Täglicher Workflow

1. SSD anschließen und erkennen

# USB-C SSD anschließen
# Automatische Erkennung durch udev-rules

# Manuelle Erkennung (falls nötig)
ssd-detect.sh

# Erkannte SSDs anzeigen
ssd-detect.sh --list

# Detaillierte Informationen
ssd-detect.sh --verbose

2. SSD mounten

# Automatisches Mounting
ssd-mount-manager.sh mount

# Spezifische SSD mounten
ssd-mount-manager.sh mount --device /dev/sdb1

# Read-Only Mount für Prüfungen
ssd-mount-manager.sh mount --readonly

# Mount-Status prüfen
ssd-mount-manager.sh status

3. Mit SSD arbeiten

# Verfügbaren Speicher prüfen
df -h /mnt/ssd-storage

# Dateien kopieren
cp -r /home/user/documents/ /mnt/ssd-storage/backup/

# Berechtigungen prüfen
ls -la /mnt/ssd-storage/

# SMB-Freigabe testen (falls konfiguriert)
smbclient //localhost/ssd-storage -U $USER

4. SSD sicher entfernen

# Sichere Entfernung
ssd-safe-eject.sh

# Mit Prozess-Übersicht
ssd-safe-eject.sh --show-processes

# Force-Eject bei hängenden Prozessen
ssd-safe-eject.sh --force

# Status nach Entfernung prüfen
ssd-mount-manager.sh status

Erweiterte Funktionen

SSD-Erkennung (ssd-detect.sh)

Grundlegende Verwendung

# Alle USB-Storage-Geräte erkennen
ssd-detect.sh

# Nur NTFS-Partitionen
ssd-detect.sh --ntfs-only

# JSON-Output für Automation
ssd-detect.sh --output json

# Kontinuierliche Überwachung
ssd-detect.sh --monitor --interval 5

Erweiterte Optionen

# Spezifisches Device prüfen
ssd-detect.sh --device /dev/sdb1

# Hardware-Details anzeigen
ssd-detect.sh --hardware-info

# Performance-Informationen
ssd-detect.sh --performance-info

# Debug-Modus
ssd-detect.sh --debug --verbose

Output-Beispiele

# Standard-Output
[INFO] USB-C SSD detected: /dev/sdb1
[INFO] Filesystem: NTFS
[INFO] UUID: 1234-5678-9ABC-DEF0
[INFO] Size: 500GB
[INFO] Label: BACKUP_SSD
[SUCCESS] Device ready for mounting

# JSON-Output
{
  "device": "/dev/sdb1",
  "filesystem": "ntfs",
  "uuid": "1234-5678-9ABC-DEF0",
  "size": "500GB",
  "label": "BACKUP_SSD",
  "status": "ready",
  "usb_version": "3.0",
  "speed": "5Gbps"
}

Mount-Management (ssd-mount-manager.sh)

Mount-Operationen

# Standard-Mount
ssd-mount-manager.sh mount

# Custom Mount-Point
ssd-mount-manager.sh mount --mountpoint /custom/path

# Spezifische Mount-Optionen
ssd-mount-manager.sh mount --options "uid=1000,gid=1000,umask=022"

# SMB-optimiertes Mounting
ssd-mount-manager.sh mount --smb-ready

Status und Monitoring

# Aktueller Status
ssd-mount-manager.sh status

# Detaillierte Informationen
ssd-mount-manager.sh status --detailed

# JSON-Output für Monitoring
ssd-mount-manager.sh status --json

# Performance-Metriken
ssd-mount-manager.sh metrics

Troubleshooting

# Mount-Probleme diagnostizieren
ssd-mount-manager.sh diagnose

# Mount-Point bereinigen
ssd-mount-manager.sh cleanup

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

# Filesystem-Check vor Mount
ssd-mount-manager.sh mount --fsck

Test-Suite (ssd-test-suite.sh)

Grundlegende Tests

# Alle Tests ausführen
ssd-test-suite.sh all

# Schnelle Tests (nur kritische)
ssd-test-suite.sh --quick

# Spezifischen Test ausführen
ssd-test-suite.sh T01  # Hardware Detection
ssd-test-suite.sh T04  # Read Performance
ssd-test-suite.sh T08  # SMB Readiness

Test-Kategorien

# Hardware-Tests
ssd-test-suite.sh --category hardware

# Performance-Tests
ssd-test-suite.sh --category performance

# Integration-Tests
ssd-test-suite.sh --category integration

# Security-Tests
ssd-test-suite.sh --category security

Benchmark-Modus

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

# Detaillierte Performance-Analyse
ssd-test-suite.sh --benchmark --detailed

# Vergleich mit Baseline
ssd-test-suite.sh --benchmark --compare baseline.json

# Kontinuierliche Performance-Überwachung
ssd-test-suite.sh --benchmark --continuous --interval 3600

Sichere Entfernung (ssd-safe-eject.sh)

Standard-Eject

# Sichere Entfernung
ssd-safe-eject.sh

# Mit Verbose-Output
ssd-safe-eject.sh --verbose

# Dry-Run (Simulation)
ssd-safe-eject.sh --dry-run

Erweiterte Eject-Optionen

# Aktive Prozesse anzeigen
ssd-safe-eject.sh --show-processes

# Prozesse automatisch beenden
ssd-safe-eject.sh --kill-processes

# Force-Eject bei Problemen
ssd-safe-eject.sh --force

# Nur Unmount (ohne Hardware-Eject)
ssd-safe-eject.sh --unmount-only

Timeout-Konfiguration

# Custom Buffer-Flush Timeout
ssd-safe-eject.sh --timeout 120

# Prozess-Kill Timeout
ssd-safe-eject.sh --process-timeout 30

# Hardware-Eject Timeout
ssd-safe-eject.sh --eject-timeout 10

Use Cases und Workflows

1. KMU-Backup-System

#!/bin/bash
# Tägliches Backup-Script

# SSD mounten
ssd-mount-manager.sh mount || exit 1

# Backup durchführen
rsync -av --delete /important/data/ /mnt/ssd-storage/backup/

# Backup verifizieren
if [ $? -eq 0 ]; then
    echo "Backup erfolgreich"
    # Optional: Test-Suite ausführen
    ssd-test-suite.sh --quick
else
    echo "Backup fehlgeschlagen"
    exit 1
fi

# SSD sicher entfernen
ssd-safe-eject.sh

2. Entwicklungsumgebung

#!/bin/bash
# Projekt-SSD wechseln

# Aktuelle SSD sicher entfernen
ssd-safe-eject.sh

echo "Bitte neue Projekt-SSD anschließen..."
read -p "Drücken Sie Enter wenn bereit..."

# Neue SSD erkennen und mounten
ssd-detect.sh
ssd-mount-manager.sh mount

# Projekt-Verzeichnis wechseln
cd /mnt/ssd-storage/project-alpha/

echo "Entwicklungsumgebung bereit"

3. Media-Server Erweiterung

#!/bin/bash
# Neue Media-Library hinzufügen

# SSD mounten
ssd-mount-manager.sh mount --smb-ready

# Qualitätsprüfung
ssd-test-suite.sh all

# Media-Verzeichnis erstellen
mkdir -p /mnt/ssd-storage/media/videos
mkdir -p /mnt/ssd-storage/media/music

# Berechtigungen für Media-Server setzen
chown -R mediaserver:mediaserver /mnt/ssd-storage/media/
chmod -R 755 /mnt/ssd-storage/media/

# SMB-Freigabe neu laden (falls konfiguriert)
sudo systemctl reload smbd

echo "Media-Library bereit"

4. Sichere Datenübertragung

#!/bin/bash
# Verschlüsselte Datenübertragung

# SSD read-only mounten für Prüfung
ssd-mount-manager.sh mount --readonly

# Datenintegrität prüfen
ssd-test-suite.sh T02 T06  # Filesystem + File Operations

# Read-Write remount
ssd-mount-manager.sh remount --readwrite

# Verschlüsselte Daten entschlüsseln
gpg --decrypt /mnt/ssd-storage/encrypted.gpg > /tmp/decrypted.txt

# Verarbeitung...
process_data.sh /tmp/decrypted.txt

# Temporäre Dateien sicher löschen
shred -vfz -n 3 /tmp/decrypted.txt

# SSD sicher entfernen
ssd-safe-eject.sh

Konfiguration und Anpassung

Environment Variables

# Mount-Konfiguration
export SSD_MOUNT_POINT="/mnt/ssd-storage"
export SSD_MOUNT_OPTIONS="uid=1000,gid=1000,umask=022"
export SSD_MOUNT_TIMEOUT=30

# Logging-Konfiguration
export SSD_LOG_LEVEL=INFO
export SSD_LOG_FILE="/var/log/ssd-management.log"
export SSD_USE_SYSLOG=true

# Test-Konfiguration
export SSD_TEST_TIMEOUT=300
export SSD_TEST_SIZE=100
export SSD_BENCHMARK_MODE=false

# Eject-Konfiguration
export SSD_EJECT_TIMEOUT=60
export SSD_PROCESS_TIMEOUT=10
export SSD_HARDWARE_EJECT=true

Konfigurationsdatei

# /etc/ssd-management/config.conf
[mount]
default_mount_point = /mnt/ssd-storage
ntfs_options = uid=1000,gid=1000,umask=022,windows_names
auto_mount = true
smb_ready = true

[logging]
log_level = INFO
log_file = /var/log/ssd-management.log
use_syslog = true
rotate_logs = true

[testing]
quick_tests = T01,T02,T03,T08
performance_threshold_read = 50MB/s
performance_threshold_write = 30MB/s
benchmark_enabled = false

[security]
require_sudo = true
audit_logging = true
process_detection = true
buffer_monitoring = true

Monitoring und Logging

Log-Analyse

# Aktuelle Logs anzeigen
tail -f /var/log/ssd-management.log

# Fehler-Logs filtern
grep ERROR /var/log/ssd-management.log

# Performance-Logs analysieren
grep PERFORMANCE /var/log/ssd-management.log | tail -20

# Audit-Trail anzeigen
grep AUDIT /var/log/ssd-management.log

Systemd-Journal

# Service-Logs anzeigen
journalctl -u ssd-detection.service -f

# Fehler-Logs der letzten Stunde
journalctl -u ssd-automount.service --since "1 hour ago" -p err

# Boot-Logs für SSD-Services
journalctl -b -u ssd-detection.service

Performance-Monitoring

# Aktuelle Performance-Metriken
ssd-mount-manager.sh metrics

# Performance-Trend (letzte 24h)
ssd-test-suite.sh --benchmark --trend --hours 24

# Prometheus-Metriken exportieren
ssd-test-suite.sh --prometheus-metrics > /var/lib/prometheus/ssd-metrics.prom

Troubleshooting

Häufige Probleme und Lösungen

Problem: SSD wird nicht erkannt

# Diagnose
lsusb                    # USB-Geräte auflisten
lsblk                    # Block-Geräte anzeigen
dmesg | tail -20         # Kernel-Messages prüfen

# Lösungsansätze
sudo udevadm trigger     # Udev-Events neu auslösen
sudo modprobe ntfs       # NTFS-Modul laden
ssd-detect.sh --debug   # Debug-Modus

Problem: Mount schlägt fehl

# Diagnose
ssd-mount-manager.sh diagnose
sudo fsck.ntfs /dev/sdb1  # Filesystem prüfen
mount | grep ssd-storage  # Aktuelle Mounts prüfen

# Lösungsansätze
ssd-mount-manager.sh cleanup    # Mount-Point bereinigen
ssd-mount-manager.sh recover    # Recovery-Modus
sudo umount -f /mnt/ssd-storage # Force-Unmount

Problem: Eject hängt

# Diagnose
ssd-safe-eject.sh --show-processes  # Blockierende Prozesse
lsof /mnt/ssd-storage               # Offene Dateien
fuser -v /mnt/ssd-storage           # Prozess-Details

# Lösungsansätze
ssd-safe-eject.sh --kill-processes  # Prozesse beenden
ssd-safe-eject.sh --force          # Force-Eject
sudo fuser -km /mnt/ssd-storage     # Alle Prozesse killen

Debug-Modi

# Alle Scripts mit Debug-Output
export SSD_DEBUG=true
export SSD_VERBOSE=true

# Trace-Modus für Scripts
bash -x ssd-detect.sh

# Systemd-Service Debug
sudo systemctl edit ssd-detection.service
# [Service]
# Environment=SSD_DEBUG=true

Best Practices

Produktionsumgebung

1. Regelmäßige Tests: Tägliche Quick-Tests, wöchentliche Full-Tests
2. Monitoring: Performance-Metriken überwachen, Alerts konfigurieren
3. Backup: Konfiguration und Logs regelmäßig sichern
4. Updates: System und Scripts aktuell halten
5. Dokumentation: Änderungen und Konfigurationen dokumentieren

Sicherheit

1. Berechtigungen: Minimale Berechtigungen verwenden
2. Audit-Logs: Alle Operationen protokollieren
3. Verschlüsselung: Sensible Daten verschlüsselt übertragen
4. Access-Control: Zugriff auf autorisierte Benutzer beschränken
5. Regular-Scans: Regelmäßige Security-Tests durchführen

Performance

1. USB 3.0+: Moderne USB-Standards verwenden
2. SSD-Qualität: Hochwertige SSDs für kritische Anwendungen
3. Mount-Optionen: Performance-optimierte NTFS-Optionen
4. Caching: Angemessene Cache-Konfiguration
5. Monitoring: Performance-Degradation frühzeitig erkennen

---

💡 Tipp: Nutzen Sie die --help Option bei allen Scripts für detaillierte Informationen zu verfügbaren Parametern und Optionen.

Anhang

Script-Referenz

• ssd-detect.sh - Hardware-Erkennung und Device-Identifikation
• ssd-mount-manager.sh - Mount-Lifecycle Management
• ssd-test-suite.sh - Qualitätssicherung und Performance-Tests
• ssd-safe-eject.sh - Sichere Hardware-Entfernung

Wichtige Pfade

• /mnt/ssd-storage/ - Standard Mount-Point
• /etc/ssd-management/ - Konfigurationsdateien
• /var/log/ssd-*.log - Log-Dateien
• /usr/local/bin/ssd-* - Installierte Scripts

Support-Ressourcen

• Installation Guide - Detaillierte Installation
• Troubleshooting - Problemlösungen
• API Reference - Script-Parameter Referenz