Setup installation
This commit is contained in:
570
docs/usage-guide.md
Normal file
570
docs/usage-guide.md
Normal file
@@ -0,0 +1,570 @@
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
#!/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
|
||||
```bash
|
||||
#!/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
|
||||
```bash
|
||||
#!/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
|
||||
```bash
|
||||
#!/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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# /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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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](installation-guide.md) - Detaillierte Installation
|
||||
- [Troubleshooting](troubleshooting.md) - Problemlösungen
|
||||
- [API Reference](api-reference.md) - Script-Parameter Referenz
|
||||
Reference in New Issue
Block a user