README.md aktualisiert

README.md

@@ -1,3 +1,339 @@
-# change-swap-size
+# Change Swap Size
 
-Ändert Swap Size basierend des vorhandenen RAMs.
+Ein robustes Bash-Skript zur automatischen Anpassung der Swap-Größe auf Debian-basierten Systemen.
+
+## 📋 Übersicht
+
+Dieses Skript passt die Größe der `/swapfile` automatisch an die Systemkonfiguration an. Es berechnet die optimale Swap-Größe basierend auf dem installierten RAM und vergrößert die Swap-Datei bei Bedarf sicher und unterbrechungsfrei.
+
+### Hauptmerkmale
+
+- ✅ **Automatische Größenberechnung**: RAM + 2GB als Zielgröße
+- ✅ **Unterbrechungsfreier Betrieb**: Temporärer Swap während des Vorgangs
+- ✅ **Sicherheitsgeprüft**: Speicherplatz-Validierung vor Ausführung
+- ✅ **Idempotent**: Kann mehrfach sicher ausgeführt werden
+- ✅ **Detailliertes Logging**: Klare Fortschrittsanzeige in 6 Schritten
+- ✅ **Fehlerbehandlung**: Automatischer Abbruch bei Problemen
+
+## 🚀 Installation
+
+### Schnellinstallation
+
+```bash
+# Repository klonen
+git clone https://git.jtl-hosting.de/thomasciesla/change-swap-size.git
+cd change-swap-size
+
+# Skript ausführbar machen
+chmod +x resizeswap.py
+
+# Als Root ausführen
+sudo ./resizeswap.py
+```
+
+### Systemweite Installation
+
+```bash
+# Skript nach /usr/local/bin kopieren
+sudo cp resizeswap.py /usr/local/bin/resizeswap
+sudo chmod +x /usr/local/bin/resizeswap
+
+# Überall im System ausführbar
+sudo resizeswap
+```
+
+## 📖 Verwendung
+
+### Basis-Aufruf
+
+```bash
+sudo ./resizeswap.py
+```
+
+Das Skript benötigt Root-Rechte und führt folgende Aktionen aus:
+
+1. Ermittelt die installierte RAM-Größe
+2. Berechnet Zielgröße (RAM + 2GB)
+3. Prüft aktuelle Swap-Größe
+4. Vergrößert bei Bedarf die `/swapfile`
+
+### Beispielausgabe
+
+```
+=== Swap-Anpassung wird gestartet ===
+Erkannter RAM: 16384 MB
+Zielgröße für Swap: 18432 MB (RAM + 2048 MB)
+Aktuelle Swap-Größe: 4096 MB
+
+Swap wird vergrößert von 4096 MB auf 18432 MB...
+Verfügbarer Speicher: 50000 MB
+Benötigt (temporär): 28672 MB
+
+[1/6] Erstelle temporären Swap (10240 MB)...
+[2/6] Aktiviere temporären Swap...
+[3/6] Deaktiviere alten /swapfile...
+[4/6] Erstelle neue /swapfile mit 18432 MB...
+[5/6] Aktiviere neue /swapfile...
+[6/6] Entferne temporären Swap...
+
+=== Swap erfolgreich vergrößert und aktiviert! ===
+```
+
+## 🔧 Technische Details
+
+### Berechnungsformel
+
+```
+Ziel-Swap-Größe = RAM + 2048 MB
+```
+
+Diese Formel orientiert sich an gängigen Best Practices für Swap-Dimensionierung.
+
+### Ablaufdiagramm
+
+```
+┌─────────────────────────────────────┐
+│ 1. Temporären 10GB Swap erstellen  │
+│    und aktivieren                   │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 2. Alten /swapfile deaktivieren    │
+│    und löschen                      │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 3. Neuen /swapfile mit Zielgröße   │
+│    erstellen                        │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 4. Neuen /swapfile aktivieren      │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 5. Temporären Swap deaktivieren    │
+│    und löschen                      │
+└─────────────────────────────────────┘
+```
+
+### Sicherheitsmechanismen
+
+- **Speicherplatz-Prüfung**: Validiert vor Beginn, ob genug Speicher verfügbar ist
+- **Temporärer Swap**: 10GB Sicherheits-Swap während der Operation
+- **Root-Prüfung**: Verhindert Ausführung ohne ausreichende Rechte
+- **Fehlerbehandlung**: `set -e` bricht bei Fehlern sofort ab
+- **Permission-Management**: Automatisches Setzen von `chmod 600` für Swap-Dateien
+
+### Systemvoraussetzungen
+
+- **Betriebssystem**: Debian, Ubuntu oder andere Debian-Derivate
+- **Kernel**: Linux mit Swap-Unterstützung
+- **Tools**: `bash`, `dd`, `free`, `mkswap`, `swapon`, `swapoff`, `stat`, `df`
+- **Rechte**: Root-Zugriff erforderlich
+- **Speicher**: Mindestens RAM + 2GB + 10GB freier Festplattenspeicher
+
+## ⚙️ Konfiguration
+
+### Anpassbare Parameter
+
+Im Skript können folgende Variablen angepasst werden:
+
+```bash
+# Temporäre Swap-Größe (in MB)
+TEMP_SWAP_SIZE_MB=10240  # Standard: 10 GB
+
+# Zusätzlicher Speicher zum RAM (in MB)
+RAM_ADDITION=2048        # Standard: 2 GB
+```
+
+### Beispiel: Custom-Größe
+
+Für ein System mit speziellen Anforderungen:
+
+```bash
+# Im Skript anpassen:
+RAM_ADDITION=4096        # RAM + 4GB statt 2GB
+TEMP_SWAP_SIZE_MB=20480  # 20GB temporärer Swap
+```
+
+## 📊 Verwendungsszenarien
+
+### Szenario 1: Server mit 16GB RAM
+
+```
+RAM:              16384 MB
+Berechnung:       16384 + 2048 = 18432 MB
+Ergebnis:         18.4 GB Swap
+```
+
+### Szenario 2: Server mit 128GB RAM
+
+```
+RAM:              131072 MB
+Berechnung:       131072 + 2048 = 133120 MB
+Ergebnis:         133 GB Swap
+```
+
+### Szenario 3: Swap bereits groß genug
+
+```
+RAM:              8192 MB
+Ziel:             10240 MB
+Aktuell:          16384 MB
+Aktion:           Keine - Swap bereits ausreichend
+```
+
+## 🛠️ Troubleshooting
+
+### Problem: Nicht genug Speicherplatz
+
+**Fehler:**
+```
+FEHLER: Nicht genug freier Speicherplatz!
+Benötigt: 28672 MB, Verfügbar: 20000 MB
+```
+
+**Lösung:**
+- Speicherplatz freigeben auf dem entsprechenden Volume
+- Temporäre Swap-Größe reduzieren (`TEMP_SWAP_SIZE_MB`)
+- Alternative Partition für Swap verwenden
+
+### Problem: Swap bereits groß genug
+
+**Meldung:**
+```
+=== Swap ist bereits groß genug ===
+Aktuelle Größe (20480 MB) >= Zielgröße (18432 MB)
+```
+
+**Lösung:**
+- Normal - keine Aktion erforderlich
+- Falls dennoch Anpassung gewünscht, `TARGET_MB` manuell anpassen
+
+### Problem: Keine Root-Rechte
+
+**Fehler:**
+```
+Fehler: Dieses Skript muss als root ausgeführt werden
+```
+
+**Lösung:**
+```bash
+sudo ./resizeswap.py
+```
+
+## 🔍 Verifikation
+
+### Swap-Status prüfen
+
+```bash
+# Aktive Swap-Devices anzeigen
+swapon --show
+
+# Speicher-Übersicht
+free -h
+
+# Detaillierte Swap-Informationen
+cat /proc/swaps
+```
+
+### /etc/fstab prüfen
+
+```bash
+grep swapfile /etc/fstab
+```
+
+Erwartete Ausgabe:
+```
+/swapfile none swap sw 0 0
+```
+
+## 📝 Best Practices
+
+### Empfehlungen
+
+1. **Backup**: Wichtige Daten vor Ausführung sichern
+2. **Wartungsfenster**: Während wartungsarmer Zeiten ausführen
+3. **Monitoring**: Swap-Nutzung nach Anpassung überwachen
+4. **Dokumentation**: Änderungen in Change-Management dokumentieren
+
+### Swap-Dimensionierung
+
+Allgemeine Richtlinien für Swap-Größen:
+
+| RAM      | Empfohlener Swap | Skript-Berechnung |
+|----------|------------------|-------------------|
+| 1-2 GB   | RAM × 2          | RAM + 2GB         |
+| 2-8 GB   | RAM × 1.5        | RAM + 2GB         |
+| 8-64 GB  | RAM + 2-4 GB     | RAM + 2GB ✓       |
+| > 64 GB  | 8-32 GB          | RAM + 2GB         |
+
+Das Skript folgt der modernen Best Practice für mittlere bis große Server.
+
+## 🤝 Beitragen
+
+Wir freuen uns über Beiträge! Bitte beachten Sie:
+
+### Issues melden
+
+Bugs oder Feature-Requests können hier gemeldet werden:  
+**Issues**: https://git.jtl-hosting.de/thomasciesla/change-swap-size/issues
+
+### Merge Requests
+
+Pull Requests sind willkommen:  
+**Merge Requests**: https://git.jtl-hosting.de/thomasciesla/change-swap-size/pulls
+
+### Entwicklungsrichtlinien
+
+- Bash-Coding-Standards einhalten
+- Ausführliche Kommentare für komplexe Logik
+- Fehlerbehandlung für alle kritischen Operationen
+- Tests auf Debian 11 und 12 durchführen
+
+## 📞 Kontakt
+
+**Maintainer**: Thomas Ciesla  
+**E-Mail**: thomas.ciesla@jtl-software.com  
+**Teams**: thomas.ciesla@jtl-software.com  
+**Organisation**: JTL-Software
+
+## 📜 Lizenz
+
+Dieses Projekt ist für den internen Gebrauch bei JTL-Software entwickelt.
+
+## 🔖 Changelog
+
+### Version 1.0.0 (2025-10-24)
+
+- Initial Release
+- Automatische RAM-Erkennung und Berechnung
+- Temporärer Swap für unterbrechungsfreien Betrieb
+- Speicherplatz-Validierung
+- fstab-Integration
+- Ausführliches Logging
+
+## ⚠️ Wichtige Hinweise
+
+### Sicherheit
+
+- **Root-Rechte erforderlich**: Skript manipuliert System-Level Ressourcen
+- **Temporärer Speicherbedarf**: Benötigt kurzzeitig Zielgröße + 10GB
+- **Keine Datenvalidierung**: Swap-Inhalt wird nicht gesichert
+- **Production-Use**: In Testumgebung validieren vor Production-Einsatz
+
+### Einschränkungen
+
+- Nur für `/swapfile`, nicht für Swap-Partitionen
+- Keine Verkleinerung der Swap-Datei
+- Keine Unterstützung für Multiple-Swap-Dateien
+- Nur Linux/Debian-basierte Systeme
+
+---
+
+**Entwickelt mit ❤️ für JTL-Software Infrastructure Team**