# USB-SSD Management System

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/Version-0.1.0-blue.svg)](https://git.gitcover.de/KMU/usb-ssd/releases)
[![Platform](https://img.shields.io/badge/Platform-Linux-green.svg)](https://git.gitcover.de/KMU/usb-ssd)

Ein professionelles Management-System für USB-C SSDs auf Ubuntu/Linux-Servern mit automatischer Erkennung, sicherem Mounting und SMB-Freigabe-Vorbereitung.

## 🎯 Zweck und Zielgruppe

### **Primärer Zweck**
Vereinfachung und Standardisierung der Verwaltung wechselbarer USB-C SSDs in Linux-Serverumgebungen, insbesondere für:
- **KMU-Infrastrukturen** mit flexiblen Speicheranforderungen
- **Entwicklungsumgebungen** mit häufig wechselnden Speichergeräten
- **Backup- und Archivierungssysteme** mit externen Medien
- **Media-Server** mit erweiterbarem Speicher

### **Zielgruppe**
- **System-Administratoren** in kleinen und mittleren Unternehmen
- **DevOps-Engineers** mit Infrastructure-as-Code Anforderungen
- **Entwickler** die USB-Storage-Management automatisieren möchten
- **IT-Consultants** für standardisierte Client-Deployments

## 🚀 Hauptfunktionen

### **Kernkomponenten**

| Komponente | Zweck | Hauptfunktionen |
|------------|-------|-----------------|
| **SSD Detection** | Hardware-Erkennung | Automatische USB-C SSD Identifikation, NTFS-Partition Erkennung |
| **Mount Manager** | Lifecycle-Management | Flexibles Mounting, konstanter Mount-Point, Auto-Detection |
| **Test Suite** | Qualitätssicherung | 11 umfassende Tests, Performance-Messung, SMB-Bereitschaft |
| **Safe-Eject** | Sichere Entfernung | Hardware-Eject, Buffer-Flush, Prozess-Überwachung |

### **Schlüssel-Features**
✅ **Wechselbare SSDs** mit konstantem logischem Mount-Point (`/mnt/ssd-storage`)  
✅ **NTFS-Kompatibilität** für Windows/Linux Dual-Use  
✅ **SMB-Freigabe ready** mit optimierten Zugriffsrechten  
✅ **Umfassendes Logging** für Audit-Trails  
✅ **Systemd-Integration** für automatisches Mounting  
✅ **Git-Repository-ready** für Infrastructure-as-Code  

## 📋 Schnellstart

### **1. Installation**
```bash
# Repository klonen
git clone https://git.gitcover.de/KMU/usb-ssd.git
cd usb-ssd

# Master-Installation ausführen
sudo ./scripts/installation/install.sh
```

### **2. Erste Verwendung**
```bash
# USB-C SSD anschließen und erkennen
ssd-detect

# Automatisches Mounting
ssd-mount

# Vollständige Tests
ssd-test all

# Sichere Entfernung
ssd-safe-eject
```

### **3. Täglicher Workflow**
```bash
# Status prüfen
ssd-status

# SSD wechseln
ssd-safe-eject    # Alte SSD entfernen
ssd-remount       # Neue SSD automatisch mounten
```

## 🏗️ Repository-Struktur

```
usb-ssd/
├── README.md                    # Diese Datei
├── LICENSE.md                   # MIT License
├── CHANGELOG.md                 # Versionshistorie
├── .gitignore                   # Git-Ignorierung
├── scripts/
│   ├── ssd-detection/
│   │   ├── ssd-detect.sh       # Hardware-Erkennung
│   │   └── README.md
│   ├── ssd-management/
│   │   ├── ssd-mount-manager.sh # Mount-Lifecycle
│   │   ├── ssd-safe-eject.sh   # Sichere Entfernung
│   │   └── README.md
│   ├── ssd-testing/
│   │   ├── ssd-test-suite.sh   # Qualitätssicherung
│   │   └── README.md
│   └── installation/
│       ├── install.sh          # Master-Installation
│       └── README.md
├── docs/
│   ├── installation-guide.md   # Detaillierte Installation
│   ├── usage-guide.md         # Nutzungshandbuch
│   ├── troubleshooting.md     # Problemlösung
│   └── api-reference.md       # Script-Referenz
└── examples/
    ├── systemd-services/       # Service-Templates
    ├── udev-rules/            # Auto-Mount Regeln
    └── smb-configuration/     # SMB-Setup Beispiele
```

## 🔧 System-Anforderungen

### **Mindestanforderungen**
- **OS**: Ubuntu 20.04+ / Debian 11+ / vergleichbare Linux-Distribution
- **Hardware**: USB-C Port, NTFS-formatierte SSD
- **Berechtigungen**: `sudo` Zugriff für Installation und Mount-Operationen
- **Speicher**: < 1MB für Scripts, variabel für Logs

### **Abhängigkeiten**
```bash
# Automatisch installiert durch install.sh
ntfs-3g      # NTFS-Dateisystem Unterstützung
parted       # Partitionstabellen-Management
util-linux   # Mount/Unmount Utilities
bc           # Berechnungen in Scripts
eject        # Hardware-Eject Funktionalität
```

## 📖 Dokumentation

### **Verfügbare Guides**
- **[Installation Guide](docs/installation-guide.md)** - Schritt-für-Schritt Setup
- **[Usage Guide](docs/usage-guide.md)** - Detaillierte Nutzung aller Funktionen
- **[Troubleshooting](docs/troubleshooting.md)** - Häufige Probleme und Lösungen
- **[API Reference](docs/api-reference.md)** - Script-Parameter und Optionen

### **Externe Dokumentation**
- [NTFS-3G Documentation](https://www.tuxera.com/community/open-source-ntfs-3g/)
- [Linux USB Storage](https://www.kernel.org/doc/html/latest/usb/storage.html)
- [Systemd Mount Units](https://www.freedesktop.org/software/systemd/man/systemd.mount.html)

## 🎯 Use Cases

### **1. KMU-Backup-System**
```bash
# Täglich: Externe SSD für Backups mounten
ssd-mount
rsync -av /important/data/ /mnt/ssd-storage/backup/
ssd-safe-eject
```

### **2. Entwicklungsumgebung**
```bash
# Projekt-spezifische Daten auf wechselbaren SSDs
ssd-mount
cd /mnt/ssd-storage/project-alpha/
# Entwicklung...
ssd-safe-eject  # SSD zu anderem Entwickler transportieren
```

### **3. Media-Server Erweiterung**
```bash
# Neue Video-Library hinzufügen
ssd-mount
ssd-test all  # Qualitätsprüfung
# SMB-Freigabe automatisch verfügbar
```

### **4. Sichere Datenübertragung**
```bash
# Verschlüsselte Daten auf NTFS-SSD
ssd-mount
gpg --decrypt secret.gpg > /mnt/ssd-storage/data.txt
ssd-safe-eject  # Hardware-sicher entfernen
```

## 🔒 Sicherheit und Best Practices

### **Sicherheitsfeatures**
- **Read-Only Mounting** für kritische Prüfungen
- **Process Detection** vor Safe-Eject
- **Buffer-Flush Überwachung** für Datenintegrität
- **UUID-basierte Identifikation** statt Device-Namen
- **Umfassendes Logging** für Audit-Trails

### **Best Practices**
1. **Immer `ssd-safe-eject` verwenden** statt einfacher `umount`
2. **Tests ausführen** nach dem Mounting neuer SSDs
3. **Logs regelmäßig prüfen** für Systemanomalien
4. **Backup der Konfiguration** in Git-Repository
5. **Systemd-Service nutzen** für Produktionsumgebungen

## 🚀 Template-Nutzung

### **Als Gitea-Template verwenden**
1. **"Use this template"** auf der Gitea-Repository-Seite klicken
2. **Neues Repository** für Ihr spezifisches Setup erstellen
3. **Anpassungen vornehmen**:
   - Mount-Points in Scripten anpassen
   - Firmen-spezifische Konfigurationen hinzufügen
   - Zusätzliche Tests für Ihre Hardware entwickeln
4. **Deployment** in Ihrer Infrastruktur

### **Erweiterungsmöglichkeiten**
- **Encryption-Support** für verschlüsselte SSDs
- **RAID-Integration** für gespiegelte USB-Storage
- **Cloud-Backup** Integration mit S3-kompatiblen Systemen
- **Monitoring-Integration** mit Prometheus/Grafana
- **Multi-Device-Support** für mehrere gleichzeitige SSDs

## 🤝 Beitragen

### **Contribution Guidelines**
1. **Fork** des Repositories erstellen
2. **Feature-Branch** erstellen (`git checkout -b feature/amazing-feature`)
3. **Änderungen committen** (`git commit -m 'Add amazing feature'`)
4. **Branch pushen** (`git push origin feature/amazing-feature`)
5. **Pull Request** erstellen

### **Development Setup**
```bash
# Development-Umgebung vorbereiten
git clone https://git.gitcover.de/KMU/usb-ssd.git
cd usb-ssd
./scripts/installation/install.sh
# Entwicklung...
```

## 📄 License

Dieses Projekt ist unter der **MIT License** lizenziert. Siehe [LICENSE](LICENSE.md) Datei für Details.

```
MIT License - Copyright (c) 2025 Coverflex® | GitCover® Organization
Erlaubt uneingeschränkte Nutzung, Modifikation und Weiterverteilung.
```

## ⚠️ Haftungsausschluss (Disclaimer)

**WICHTIGER HINWEIS: Die Verwendung dieser Inhalte erfolgt auf eigene Gefahr.**

### **Haftungsausschluss**
Die Scripts und Tools in diesem Repository werden "wie besehen" zur Verfügung gestellt. Die Coverflex® | GitCover® Organization und die Mitwirkenden übernehmen **keine Haftung** für:

- **Datenverlust** oder Beschädigung von Dateien
- **Hardware-Schäden** an USB-SSDs oder anderen Speichergeräten  
- **System-Ausfälle** oder Betriebsstörungen
- **Sicherheitsprobleme** oder unbefugten Zugriff
- **Produktionsausfälle** oder Geschäftsunterbrechungen

### **Verantwortung des Benutzers**
Vor der Verwendung in Produktionsumgebungen:

1. **Umfassende Tests** in isolierten Testumgebungen durchführen
2. **Vollständige Backups** aller wichtigen Daten erstellen
3. **Systemkonfiguration** dokumentieren und sichern
4. **Wiederherstellungsverfahren** testen und validieren
5. **Sicherheitsrichtlinien** des Unternehmens befolgen

### **Empfohlene Vorsichtsmaßnahmen**
- **Nie in kritischen Produktionssystemen** ohne vorherige Tests einsetzen
- **Immer mit non-kritischen Daten** beginnen
- **Monitoring und Logging** für alle Operationen aktivieren
- **Regelmäßige Backups** vor Script-Ausführung
- **Dokumentation aller Änderungen** an System-Konfigurationen

**Die MIT License enthält explizite Haftungsausschlüsse - siehe [LICENSE](LICENSE.md) für vollständige rechtliche Details.**

---

**⚠️ WARNUNG: Diese Software manipuliert Dateisysteme und Hardware-Devices. Unsachgemäße Verwendung kann zu irreversiblen Datenverlusten führen. Verwenden Sie diese Tools nur, wenn Sie die Risiken verstehen und akzeptieren.**

## 📞 Support

### **Community Support**
- **Issues**: [GitHub Issues](https://git.gitcover.de/KMU/usb-ssd/issues) für Bug-Reports und Feature-Requests
- **Discussions**: Repository-Discussions für allgemeine Fragen
- **Wiki**: [Repository Wiki](https://git.gitcover.de/KMU/usb-ssd/wiki) für erweiterte Dokumentation

### **Enterprise Support**
Für professionellen Support und Custom-Entwicklungen kontaktieren Sie die GitCover® Organization.

---

**Made with ❤️ by Coverflex® | GitCover® Organization**  
*Professional USB-SSD Management for Linux Infrastructure*