Setup installation
This commit is contained in:
479
docs/api-reference.md
Normal file
479
docs/api-reference.md
Normal file
@@ -0,0 +1,479 @@
|
||||
# USB-SSD Management System - API Reference
|
||||
|
||||
## Übersicht
|
||||
|
||||
Diese Referenz dokumentiert alle verfügbaren Scripts, Parameter und Optionen des USB-SSD Management Systems. Alle Scripts unterstützen die `--help` Option für detaillierte Informationen.
|
||||
|
||||
## Script-Übersicht
|
||||
|
||||
| Script | Zweck | Hauptfunktionen |
|
||||
|--------|-------|-----------------|
|
||||
| `ssd-detect.sh` | Hardware-Erkennung | USB-C SSD Identifikation, NTFS-Erkennung |
|
||||
| `ssd-mount-manager.sh` | Mount-Management | Mounting, Unmounting, Status-Überwachung |
|
||||
| `ssd-test-suite.sh` | Qualitätssicherung | 11 Test-Kategorien, Performance-Benchmarks |
|
||||
| `ssd-safe-eject.sh` | Sichere Entfernung | Buffer-Flush, Prozess-Detection, Hardware-Eject |
|
||||
|
||||
## ssd-detect.sh
|
||||
|
||||
### Syntax
|
||||
```bash
|
||||
ssd-detect.sh [OPTIONS] [COMMAND]
|
||||
```
|
||||
|
||||
### Befehle
|
||||
| Befehl | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `detect` | Standard-Erkennung (Default) |
|
||||
| `list` | Alle erkannten SSDs auflisten |
|
||||
| `monitor` | Kontinuierliche Überwachung |
|
||||
| `info` | Detaillierte Device-Informationen |
|
||||
|
||||
### Optionen
|
||||
| Option | Kurz | Typ | Beschreibung | Default |
|
||||
|--------|------|-----|--------------|---------|
|
||||
| `--device` | `-d` | String | Spezifisches Device prüfen | Auto-detect |
|
||||
| `--ntfs-only` | `-n` | Flag | Nur NTFS-Partitionen anzeigen | false |
|
||||
| `--output` | `-o` | String | Output-Format (text/json/xml) | text |
|
||||
| `--verbose` | `-v` | Flag | Detaillierte Ausgabe | false |
|
||||
| `--debug` | | Flag | Debug-Modus aktivieren | false |
|
||||
| `--monitor` | `-m` | Flag | Kontinuierliche Überwachung | false |
|
||||
| `--interval` | `-i` | Integer | Monitor-Intervall (Sekunden) | 5 |
|
||||
| `--timeout` | `-t` | Integer | Detection-Timeout (Sekunden) | 30 |
|
||||
| `--hardware-info` | | Flag | Hardware-Details anzeigen | false |
|
||||
| `--performance-info` | | Flag | Performance-Informationen | false |
|
||||
|
||||
### Beispiele
|
||||
```bash
|
||||
# Standard-Erkennung
|
||||
ssd-detect.sh
|
||||
|
||||
# Spezifisches Device prüfen
|
||||
ssd-detect.sh --device /dev/sdb1
|
||||
|
||||
# JSON-Output für Automation
|
||||
ssd-detect.sh --output json
|
||||
|
||||
# Kontinuierliche Überwachung
|
||||
ssd-detect.sh --monitor --interval 10
|
||||
|
||||
# Debug-Modus
|
||||
ssd-detect.sh --debug --verbose
|
||||
```
|
||||
|
||||
### Exit-Codes
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 0 | Erfolg - SSD erkannt |
|
||||
| 1 | Allgemeiner Fehler |
|
||||
| 2 | Keine SSD gefunden |
|
||||
| 3 | NTFS nicht unterstützt |
|
||||
| 4 | Timeout erreicht |
|
||||
| 5 | Permission denied |
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
export SSD_DETECT_TIMEOUT=30 # Detection-Timeout
|
||||
export SSD_LOG_LEVEL=INFO # Log-Level
|
||||
export SSD_SUPPORTED_FS="ntfs,exfat" # Unterstützte Dateisysteme
|
||||
export SSD_DEBUG=false # Debug-Modus
|
||||
```
|
||||
|
||||
## ssd-mount-manager.sh
|
||||
|
||||
### Syntax
|
||||
```bash
|
||||
ssd-mount-manager.sh [OPTIONS] COMMAND
|
||||
```
|
||||
|
||||
### Befehle
|
||||
| Befehl | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `mount` | SSD mounten |
|
||||
| `unmount` | SSD unmounten |
|
||||
| `remount` | SSD neu mounten |
|
||||
| `status` | Mount-Status anzeigen |
|
||||
| `diagnose` | Mount-Probleme diagnostizieren |
|
||||
| `cleanup` | Mount-Point bereinigen |
|
||||
| `recover` | Recovery-Modus |
|
||||
| `metrics` | Performance-Metriken |
|
||||
|
||||
### Optionen
|
||||
| Option | Kurz | Typ | Beschreibung | Default |
|
||||
|--------|------|-----|--------------|---------|
|
||||
| `--device` | `-d` | String | Spezifisches Device | Auto-detect |
|
||||
| `--mountpoint` | `-m` | String | Mount-Point Pfad | /mnt/ssd-storage |
|
||||
| `--options` | `-o` | String | Mount-Optionen | uid=1000,gid=1000 |
|
||||
| `--readonly` | `-r` | Flag | Read-Only Mount | false |
|
||||
| `--readwrite` | `-w` | Flag | Read-Write Mount | true |
|
||||
| `--smb-ready` | | Flag | SMB-optimierte Optionen | false |
|
||||
| `--fsck` | | Flag | Filesystem-Check vor Mount | false |
|
||||
| `--timeout` | `-t` | Integer | Mount-Timeout (Sekunden) | 30 |
|
||||
| `--force` | `-f` | Flag | Force-Mount | false |
|
||||
| `--verbose` | `-v` | Flag | Detaillierte Ausgabe | false |
|
||||
| `--json` | | Flag | JSON-Output | false |
|
||||
|
||||
### Beispiele
|
||||
```bash
|
||||
# Standard-Mount
|
||||
ssd-mount-manager.sh mount
|
||||
|
||||
# Custom Mount-Point
|
||||
ssd-mount-manager.sh mount --mountpoint /custom/path
|
||||
|
||||
# Read-Only Mount
|
||||
ssd-mount-manager.sh mount --readonly
|
||||
|
||||
# SMB-optimiertes Mounting
|
||||
ssd-mount-manager.sh mount --smb-ready
|
||||
|
||||
# Status prüfen
|
||||
ssd-mount-manager.sh status --json
|
||||
|
||||
# Diagnose
|
||||
ssd-mount-manager.sh diagnose
|
||||
```
|
||||
|
||||
### Exit-Codes
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 0 | Erfolg |
|
||||
| 1 | Allgemeiner Fehler |
|
||||
| 2 | Device nicht gefunden |
|
||||
| 3 | Mount fehlgeschlagen |
|
||||
| 4 | Unmount fehlgeschlagen |
|
||||
| 5 | Permission denied |
|
||||
| 6 | Timeout erreicht |
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
export SSD_MOUNT_POINT="/mnt/ssd-storage" # Standard Mount-Point
|
||||
export SSD_MOUNT_OPTIONS="uid=1000,gid=1000" # Standard Mount-Optionen
|
||||
export SSD_MOUNT_TIMEOUT=30 # Mount-Timeout
|
||||
export SSD_AUTO_MOUNT=true # Auto-Mount aktivieren
|
||||
export SSD_SMB_READY=false # SMB-Optimierungen
|
||||
```
|
||||
|
||||
## ssd-test-suite.sh
|
||||
|
||||
### Syntax
|
||||
```bash
|
||||
ssd-test-suite.sh [OPTIONS] [TESTS]
|
||||
```
|
||||
|
||||
### Test-IDs
|
||||
| Test-ID | Name | Kategorie | Dauer |
|
||||
|---------|------|-----------|-------|
|
||||
| `T01` | Hardware Detection | Hardware | 5s |
|
||||
| `T02` | NTFS Filesystem | Hardware | 10s |
|
||||
| `T03` | Mount Stability | Hardware | 30s |
|
||||
| `T04` | Read Performance | Performance | 60s |
|
||||
| `T05` | Write Performance | Performance | 60s |
|
||||
| `T06` | File Operations | Performance | 45s |
|
||||
| `T07` | Permission System | Integration | 15s |
|
||||
| `T08` | SMB Readiness | Integration | 30s |
|
||||
| `T09` | Capacity Verification | Integration | 20s |
|
||||
| `T10` | Error Handling | Security | 25s |
|
||||
| `T11` | Security Scan | Security | 40s |
|
||||
|
||||
### Befehle
|
||||
| Befehl | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `all` | Alle Tests ausführen |
|
||||
| `quick` | Nur kritische Tests (T01,T02,T03,T08) |
|
||||
| `T01-T11` | Spezifische Tests |
|
||||
| `hardware` | Hardware-Tests (T01-T03) |
|
||||
| `performance` | Performance-Tests (T04-T06) |
|
||||
| `integration` | Integration-Tests (T07-T09) |
|
||||
| `security` | Security-Tests (T10-T11) |
|
||||
|
||||
### Optionen
|
||||
| Option | Kurz | Typ | Beschreibung | Default |
|
||||
|--------|------|-----|--------------|---------|
|
||||
| `--category` | `-c` | String | Test-Kategorie | all |
|
||||
| `--output` | `-o` | String | Output-Format (text/json/xml/csv) | text |
|
||||
| `--benchmark` | `-b` | Flag | Benchmark-Modus | false |
|
||||
| `--detailed` | | Flag | Detaillierte Ergebnisse | false |
|
||||
| `--continuous` | | Flag | Kontinuierliche Tests | false |
|
||||
| `--interval` | `-i` | Integer | Test-Intervall (Sekunden) | 3600 |
|
||||
| `--timeout` | `-t` | Integer | Test-Timeout (Sekunden) | 300 |
|
||||
| `--size` | `-s` | String | Test-Daten Größe | 100MB |
|
||||
| `--iterations` | | Integer | Test-Wiederholungen | 3 |
|
||||
| `--compare` | | String | Baseline-Datei für Vergleich | - |
|
||||
| `--trend` | | Flag | Trend-Analyse | false |
|
||||
| `--prometheus-metrics` | | Flag | Prometheus-Metriken | false |
|
||||
|
||||
### Beispiele
|
||||
```bash
|
||||
# Alle Tests
|
||||
ssd-test-suite.sh all
|
||||
|
||||
# Schnelle Tests
|
||||
ssd-test-suite.sh --quick
|
||||
|
||||
# Performance-Tests mit Benchmark
|
||||
ssd-test-suite.sh performance --benchmark
|
||||
|
||||
# Kontinuierliche Tests
|
||||
ssd-test-suite.sh --continuous --interval 1800
|
||||
|
||||
# JSON-Output
|
||||
ssd-test-suite.sh all --output json
|
||||
|
||||
# Spezifische Tests
|
||||
ssd-test-suite.sh T01 T04 T08
|
||||
```
|
||||
|
||||
### Exit-Codes
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 0 | Alle Tests erfolgreich |
|
||||
| 1 | Ein oder mehrere Tests fehlgeschlagen |
|
||||
| 2 | Kritischer Test fehlgeschlagen |
|
||||
| 3 | Performance unter Threshold |
|
||||
| 4 | Timeout erreicht |
|
||||
| 5 | Permission denied |
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
export SSD_TEST_TIMEOUT=300 # Test-Timeout
|
||||
export SSD_TEST_SIZE=100 # Test-Daten Größe (MB)
|
||||
export SSD_TEST_ITERATIONS=3 # Test-Wiederholungen
|
||||
export SSD_BENCHMARK_MODE=false # Benchmark-Modus
|
||||
export SSD_PERFORMANCE_THRESHOLD_READ="50MB/s" # Read-Performance Threshold
|
||||
export SSD_PERFORMANCE_THRESHOLD_WRITE="30MB/s" # Write-Performance Threshold
|
||||
```
|
||||
|
||||
## ssd-safe-eject.sh
|
||||
|
||||
### Syntax
|
||||
```bash
|
||||
ssd-safe-eject.sh [OPTIONS]
|
||||
```
|
||||
|
||||
### Optionen
|
||||
| Option | Kurz | Typ | Beschreibung | Default |
|
||||
|--------|------|-----|--------------|---------|
|
||||
| `--device` | `-d` | String | Spezifisches Device | Auto-detect |
|
||||
| `--force` | `-f` | Flag | Force-Eject | false |
|
||||
| `--show-processes` | | Flag | Blockierende Prozesse anzeigen | false |
|
||||
| `--kill-processes` | | Flag | Prozesse automatisch beenden | false |
|
||||
| `--unmount-only` | | Flag | Nur Unmount (kein Hardware-Eject) | false |
|
||||
| `--timeout` | `-t` | Integer | Buffer-Flush Timeout (Sekunden) | 60 |
|
||||
| `--process-timeout` | | Integer | Prozess-Kill Timeout (Sekunden) | 10 |
|
||||
| `--verbose` | `-v` | Flag | Detaillierte Ausgabe | false |
|
||||
| `--dry-run` | | Flag | Simulation (keine Änderungen) | false |
|
||||
| `--monitor-buffers` | | Flag | Buffer-Status überwachen | false |
|
||||
| `--hardware-reset` | | Flag | Hardware-Reset nach Eject | false |
|
||||
|
||||
### Beispiele
|
||||
```bash
|
||||
# Standard Safe-Eject
|
||||
ssd-safe-eject.sh
|
||||
|
||||
# Mit Prozess-Übersicht
|
||||
ssd-safe-eject.sh --show-processes
|
||||
|
||||
# Force-Eject
|
||||
ssd-safe-eject.sh --force --kill-processes
|
||||
|
||||
# Nur Unmount
|
||||
ssd-safe-eject.sh --unmount-only
|
||||
|
||||
# Dry-Run
|
||||
ssd-safe-eject.sh --dry-run --verbose
|
||||
```
|
||||
|
||||
### Exit-Codes
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 0 | Erfolgreicher Eject |
|
||||
| 1 | Allgemeiner Fehler |
|
||||
| 2 | Device nicht gefunden |
|
||||
| 3 | Unmount fehlgeschlagen |
|
||||
| 4 | Prozesse blockieren |
|
||||
| 5 | Hardware-Eject fehlgeschlagen |
|
||||
| 6 | Timeout erreicht |
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
export SSD_EJECT_TIMEOUT=60 # Buffer-Flush Timeout
|
||||
export SSD_PROCESS_TIMEOUT=10 # Prozess-Kill Timeout
|
||||
export SSD_HARDWARE_EJECT=true # Hardware-Eject aktivieren
|
||||
export SSD_KILL_PROCESSES=false # Automatisches Prozess-Killing
|
||||
export SSD_MONITOR_BUFFERS=true # Buffer-Monitoring
|
||||
```
|
||||
|
||||
## Globale Environment Variables
|
||||
|
||||
### Logging-Konfiguration
|
||||
```bash
|
||||
export SSD_LOG_LEVEL=INFO # Log-Level (DEBUG,INFO,WARN,ERROR)
|
||||
export SSD_LOG_FILE="/var/log/ssd-management.log" # Log-Datei
|
||||
export SSD_USE_SYSLOG=true # Syslog-Integration
|
||||
export SSD_DEBUG=false # Debug-Modus
|
||||
export SSD_VERBOSE=false # Verbose-Output
|
||||
```
|
||||
|
||||
### System-Konfiguration
|
||||
```bash
|
||||
export SSD_CONFIG_DIR="/etc/ssd-management" # Konfigurationsverzeichnis
|
||||
export SSD_CACHE_DIR="/var/cache/ssd-management" # Cache-Verzeichnis
|
||||
export SSD_LOCK_DIR="/var/lock/ssd-management" # Lock-Verzeichnis
|
||||
export SSD_PID_FILE="/var/run/ssd-management.pid" # PID-Datei
|
||||
```
|
||||
|
||||
### Performance-Konfiguration
|
||||
```bash
|
||||
export SSD_MAX_PARALLEL_OPS=1 # Maximale parallele Operationen
|
||||
export SSD_IO_SCHEDULER="mq-deadline" # I/O-Scheduler
|
||||
export SSD_READ_AHEAD_KB=1024 # Read-Ahead Buffer
|
||||
export SSD_CACHE_MODE="strict" # Cache-Modus
|
||||
```
|
||||
|
||||
## Konfigurationsdateien
|
||||
|
||||
### Haupt-Konfiguration
|
||||
```ini
|
||||
# /etc/ssd-management/config.conf
|
||||
[global]
|
||||
debug = false
|
||||
verbose = false
|
||||
log_level = INFO
|
||||
|
||||
[mount]
|
||||
default_mount_point = /mnt/ssd-storage
|
||||
ntfs_options = uid=1000,gid=1000,umask=022,windows_names
|
||||
auto_mount = true
|
||||
smb_ready = false
|
||||
|
||||
[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
|
||||
```
|
||||
|
||||
### Logging-Konfiguration
|
||||
```ini
|
||||
# /etc/ssd-management/logging.conf
|
||||
[loggers]
|
||||
keys = root,ssd
|
||||
|
||||
[handlers]
|
||||
keys = fileHandler,syslogHandler
|
||||
|
||||
[formatters]
|
||||
keys = detailedFormatter
|
||||
|
||||
[logger_root]
|
||||
level = INFO
|
||||
handlers = fileHandler
|
||||
|
||||
[logger_ssd]
|
||||
level = DEBUG
|
||||
handlers = fileHandler,syslogHandler
|
||||
qualname = ssd
|
||||
propagate = 0
|
||||
|
||||
[handler_fileHandler]
|
||||
class = FileHandler
|
||||
level = DEBUG
|
||||
formatter = detailedFormatter
|
||||
args = ('/var/log/ssd-management.log',)
|
||||
|
||||
[handler_syslogHandler]
|
||||
class = handlers.SysLogHandler
|
||||
level = INFO
|
||||
formatter = detailedFormatter
|
||||
args = (('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
|
||||
|
||||
[formatter_detailedFormatter]
|
||||
format = %(asctime)s - %(name)s - %(levelname)s - %(message)s
|
||||
```
|
||||
|
||||
## Return-Codes Übersicht
|
||||
|
||||
### Allgemeine Codes (0-9)
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 0 | Erfolg |
|
||||
| 1 | Allgemeiner Fehler |
|
||||
| 2 | Ungültige Parameter |
|
||||
| 3 | Permission denied |
|
||||
| 4 | Timeout erreicht |
|
||||
| 5 | Resource nicht verfügbar |
|
||||
|
||||
### Hardware-Codes (10-19)
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 10 | Device nicht gefunden |
|
||||
| 11 | USB-Fehler |
|
||||
| 12 | Hardware-Fehler |
|
||||
| 13 | Filesystem nicht unterstützt |
|
||||
| 14 | Partition-Fehler |
|
||||
|
||||
### Mount-Codes (20-29)
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 20 | Mount fehlgeschlagen |
|
||||
| 21 | Unmount fehlgeschlagen |
|
||||
| 22 | Mount-Point nicht verfügbar |
|
||||
| 23 | Filesystem-Fehler |
|
||||
| 24 | Permission-Fehler |
|
||||
|
||||
### Test-Codes (30-39)
|
||||
| Code | Bedeutung |
|
||||
|------|-----------|
|
||||
| 30 | Test fehlgeschlagen |
|
||||
| 31 | Performance unter Threshold |
|
||||
| 32 | Kritischer Test fehlgeschlagen |
|
||||
| 33 | Test-Timeout |
|
||||
| 34 | Test-Daten korrupt |
|
||||
|
||||
## JSON-Output Format
|
||||
|
||||
### Standard-Response
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-07T19:10:00Z",
|
||||
"script": "ssd-detect.sh",
|
||||
"version": "0.1.0",
|
||||
"status": "success",
|
||||
"exit_code": 0,
|
||||
"data": {
|
||||
// Script-spezifische Daten
|
||||
},
|
||||
"errors": [],
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
### Error-Response
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-08-07T19:10:00Z",
|
||||
"script": "ssd-mount-manager.sh",
|
||||
"version": "0.1.0",
|
||||
"status": "error",
|
||||
"exit_code": 20,
|
||||
"data": null,
|
||||
"errors": [
|
||||
{
|
||||
"code": "MOUNT_FAILED",
|
||||
"message": "Failed to mount /dev/sdb1",
|
||||
"details": "Permission denied"
|
||||
}
|
||||
],
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**💡 Tipp**: Verwenden Sie `script-name.sh --help` für die aktuellste Dokumentation und alle verfügbaren Optionen.
|
||||
Reference in New Issue
Block a user