From 020da85b87d3b26c1d85812d70e141399d00fdcb1d60d06a387e382615f85597 Mon Sep 17 00:00:00 2001 From: Axel Druschel Date: Sun, 3 Aug 2025 13:51:15 +0200 Subject: [PATCH] Update README.md --- README.md | 289 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 287 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a8626c6..9158641 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,288 @@ -# usb-ssd +# USB-SSD Management System -Anleitung zur Installation und Einrichtung eines USB-C SSD Management Systems \ No newline at end of file +[![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 # 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) 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) 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* \ No newline at end of file