From 8cc60e3daefa8ce32c56e839a41dc30783d36ec5 Mon Sep 17 00:00:00 2001 From: Stefan Strobl Date: Wed, 24 Dec 2025 20:45:20 +0100 Subject: [PATCH] docs: update README for v2.0 full CLI installer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete documentation rewrite to reflect v2.0 changes: - Remove void-installer handoff instructions (obsolete) - Document new automated workflow (11 phases) - Add locale/timezone/keyboard configuration section - Add user management documentation - List default package installation - Update usage (remove --skip-installer flag) - Add troubleshooting section for new phases - Document standard user groups (wheel, audio, video, etc.) Major documentation changes: 1. Title: "Vollständiger CLI-Installer" (emphasizes automation) 2. Overview: Highlights "ohne manuelle Eingriffe" (no manual intervention) 3. Workflow: 11 phases instead of 7 4. Configuration: Three new sections (Locale, User, Packages) 5. Architecture: Added new modules to structure diagram Removed sections: - "Installer Bedienung nach dem Script" (manual installer instructions) - --skip-installer flag documentation Added sections: - Package-Liste (complete list of installed packages) - User-Konfiguration (user creation and group membership) - Nach der Installation (post-install steps) - Fehlerbehebung (troubleshooting for new phases) - Zukünftige Erweiterungen (roadmap for config file support) Decision: Keep German language for consistency with existing docs. Technical terms (packages, services) use English for clarity. --- README.md | 203 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 160 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index cffceb2..26e28b5 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,176 @@ -# Void Bootstrapp Wrapper +# Void Bootstrapp - Vollständiger CLI-Installer -Ein Bash-Wrapper, der die kritischen Vorarbeiten fuer eine verschluesselte Void-Linux-Installation erledigt und danach den offiziellen `void-installer` nutzt. +Ein vollautomatischer Bash-Installer für verschlüsselte Void Linux Installationen. -## Ablauf +## Überblick -1. Sanity Checks (Root, UEFI, Zielplatte) -2. Partitionierung (GPT, ESP + Root) -3. LUKS-Verschluesselung und Mapping -4. Dateisysteme (btrfs oder ext4) -5. Mounts fuer den Installer -6. Installer-Handoff (manuelle Mountpoints, kein Reformat) -7. Post-Install (crypttab, dracut, GRUB, optional Swapfile) +Dieser Installer automatisiert die komplette Installation von Void Linux mit LUKS2-Verschlüsselung, btrfs/ext4-Dateisystem und allen erforderlichen System-Konfigurationen - **ohne manuelle Eingriffe**. -## Usage +**Was ist neu (v2.0):** +- Vollständig automatisiert - keine manuelle void-installer Navigation mehr +- Package-Installation (Base-System, Kernel, Tools) +- Locale/Timezone/Keyboard-Konfiguration +- User-Management (Root + Standard-User mit sudo) +- Service-Aktivierung (dhcpcd für Netzwerk) + +## Installation-Workflow + +Der Installer führt folgende Phasen automatisch aus: + +1. **Sanity Checks** - Root-Rechte, UEFI-Modus, Zielplatte validieren +2. **Konfiguration** - Interaktive Eingabe aller Parameter +3. **Partitionierung** - GPT-Layout (ESP + Root-Partition) +4. **Verschlüsselung** - LUKS2/LUKS1 auf Root-Partition +5. **Dateisysteme** - btrfs (mit Subvolumes) oder ext4 +6. **Mounts** - Alle Dateisysteme mounten +7. **Packages** - Base-System, Kernel, Network-Tools installieren +8. **Locale** - System-Sprache, Timezone, Keyboard konfigurieren +9. **Users** - Root-Passwort + Standard-User mit sudo anlegen +10. **Services** - dhcpcd (Netzwerk) aktivieren +11. **Post-Install** - initramfs, GRUB, crypttab, Swap-File + +## Verwendung ```bash -sudo ./src/main.sh [--dry-run] [--skip-installer] +sudo ./src/main.sh [--dry-run] ``` -## Flags +### Flags -- `--dry-run`: Zeigt die Konfiguration und bricht ohne Aenderungen ab. -- `--skip-installer`: Laesst den Start von `void-installer` aus (manuell starten). +- `--dry-run`: Zeigt die Konfiguration und bricht ohne Änderungen ab -## Installer Bedienung nach dem Script +## Konfiguration -Im `void-installer` musst du die vorbereiteten Mounts uebernehmen und darfst nichts formatieren. +Während der Installation werden folgende Parameter abgefragt: -1. Waehle die manuelle Partitionierung. -2. Setze nur die Mountpoints, ohne Formatierung. -3. Root: - - Device: `/dev/mapper/cryptroot` - - Label: `void-root` (btrfs und ext4) - - Mountpoint: `/` - - Format: aus -4. ESP: - - Device: erste Partition der Disk (meist `...1`) - - Label: `EFI` - - Mountpoint: `/boot/efi` - - Format: aus +### Disk-Konfiguration +- **Target Disk**: Zielplatte (z.B. `/dev/sda`) +- **Hostname**: System-Hostname +- **Filesystem**: `btrfs` (Standard) oder `ext4` +- **LUKS Version**: `2` (Standard) oder `1` (für ältere GRUB-Versionen) +- **ESP Size**: EFI System Partition Größe (Standard: `1GiB`) +- **Root End**: Ende der Root-Partition (Standard: `100%`) +- **Swap Size**: Swap-File Größe (Standard: `4GiB`, `0` zum Deaktivieren) -Wenn Labels nicht angezeigt werden, pruefe mit `lsblk -f`, welches Device `void-root` bzw. `EFI` traegt. -Bei btrfs sind Subvolumes bereits angelegt und gemountet: `@`, `@home`, `@var`, `@log`, `@snapshots`, `@swap`. -Der Installer soll keine neuen Subvolumes anlegen oder formatieren, sondern die vorhandenen Mounts unveraendert lassen. -Es reicht, im Installer nur `/` und `/boot/efi` zu setzen; die Subvolumes werden im Post-Install in `/etc/fstab` eingetragen. -Mapping der Subvolumes (gesetzt durch den Wrapper/Post-Install): -- `@` -> `/` -- `@home` -> `/home` -- `@var` -> `/var` -- `@log` -> `/var/log` -- `@snapshots` -> `/.snapshots` -- `@swap` -> `/swap` +### Locale-Konfiguration +- **Locale**: System-Sprache (Standard: `en_US.UTF-8`) +- **Timezone**: Zeitzone (Standard: `UTC`, z.B. `Europe/Berlin`) +- **Keyboard**: Console-Keyboard-Layout (Standard: `us`, z.B. `de-latin1`) + +### User-Konfiguration +- **Username**: Name des Standard-Benutzers (erforderlich) +- **Root-Passwort**: Wird interaktiv gesetzt +- **User-Passwort**: Wird interaktiv gesetzt + +Der Standard-User wird automatisch folgenden Gruppen zugeordnet: +- `wheel` - sudo-Zugang +- `audio` - Audio-Geräte +- `video` - Video-Geräte +- `storage` - Speicher-Geräte +- `network` - Netzwerk-Konfiguration + +## Btrfs Subvolumes + +Bei Auswahl von btrfs werden automatisch folgende Subvolumes angelegt: + +- `@` → `/` (Root) +- `@home` → `/home` (Benutzer-Daten) +- `@var` → `/var` (Variable Daten) +- `@log` → `/var/log` (System-Logs) +- `@snapshots` → `/.snapshots` (Snapshot-Speicher) +- `@swap` → `/swap` (Swap-File Container) + +## Package-Liste + +Der Installer installiert standardmäßig folgende Pakete: + +**Base-System:** +- `base-system` - Essential base packages +- `linux` - Linux Kernel +- `linux-firmware` - Hardware-Firmware +- `grub` - Bootloader +- `cryptsetup` - LUKS-Tools +- `dracut` - initramfs Generator + +**Netzwerk:** +- `dhcpcd` - DHCP-Client +- `iproute2` - IP-Konfiguration +- `iputils` - ping, traceroute + +**System-Tools:** +- `vim` - Text-Editor +- `nano` - Alternative Editor +- `sudo` - Privilege Escalation + +## Nach der Installation + +Nach erfolgreichem Abschluss: + +1. System neustarten: `reboot` +2. LUKS-Passphrase beim Boot eingeben +3. Mit Standard-User einloggen +4. Netzwerk ist via dhcpcd automatisch verfügbar +5. `sudo` funktioniert für wheel-Gruppen-Mitglieder + +## Systemanforderungen + +- **Boot-Modus**: UEFI (BIOS wird nicht unterstützt) +- **Architektur**: x86_64 +- **Live-Medium**: Void Linux Live-ISO +- **Netzwerk**: Für Package-Download erforderlich ## Hinweise -- Der Wrapper ist destruktiv und loescht die Zielplatte nach expliziter Bestaetigung. -- UEFI ist Pflicht; BIOS-Installationen sind nicht unterstuetzt. -- Logs landen unter `/tmp/void-wrapper-YYYY-MM-DD-HHMMSS.log`. +- **Destruktiv**: Der Installer löscht die Zielplatte nach expliziter Bestätigung +- **Interaktiv**: Passwörter werden aus Sicherheitsgründen interaktiv abgefragt +- **Logs**: Unter `/tmp/void-wrapper-YYYY-MM-DD-HHMMSS.log` + +## Fehlerbehebung + +Bei Fehlern während der Installation: + +1. **Fehler in Packages-Phase**: Netzwerk-Konnektivität und Mirror-Status prüfen +2. **Fehler in Users-Phase**: Passwort-Eingabe wiederholen +3. **Rollback angeboten**: Bei Fehler werden Mounts und LUKS-Mappings automatisch aufgeräumt + +Für detaillierte Fehleranalyse siehe Log-Datei. + +## Entwicklung + +### Struktur + +``` +src/ +├── main.sh # Orchestrierung aller Phasen +├── logging.sh # Logging-Funktionen +├── config.sh # Konfigurations-Prompts und Validierung +├── sanity.sh # System-Checks +├── partitioning.sh # GPT-Partitionierung +├── encryption.sh # LUKS-Setup +├── filesystems.sh # Dateisystem-Formatierung +├── mounts.sh # Mount-Management +├── packages.sh # Package-Installation +├── locale.sh # Locale/Timezone/Keyboard +├── users.sh # User-Management +├── services.sh # Service-Aktivierung +├── postinstall.sh # initramfs, GRUB, crypttab +└── rollback.sh # Cleanup bei Fehlern +``` + +### Architektur-Prinzipien + +- **Narrative Documentation**: Jedes Modul dokumentiert Motivation, Decisions, Alternatives +- **Modulare Phasen**: Jede Phase ist eigenständig und testbar +- **Error Handling**: `set -euo pipefail` + trap-basiertes Rollback +- **Logging**: Alle Operationen werden geloggt + +## Zukünftige Erweiterungen + +- Config-File Support (JSON) für unattended Installations +- Desktop-Environment Auswahl (XFCE, KDE, GNOME) +- Zusätzliche Service-Optionen (sshd, chronyd) +- Checkpoint-System für Phase-Wiederaufnahme + +## Lizenz + +Dieses Projekt ist für Void Linux Installationen optimiert und folgt den Best Practices der Void Linux Dokumentation.