Wartung & Eigenbau
Das Projekt selbst pflegen: die App bauen mit hochzählender Version, das EchtOS-Image bauen und ausliefern, eigene EchtOS-Plugins schreiben und einbinden.
Alle Befehle zum Kopieren. Quelle: WARTUNG.md im Projekt-Repo.
Was liegt wo
| Ordner | Inhalt |
|---|---|
rechenknecht_app/ | Android-App (Kotlin/Compose). Build über build.sh. |
server/rechenknecht_server/ | Python-Server: verteilt Aufgaben an die Handys, liefert Plugins aus. |
werkbank-image-build/ | EchtOS-Images bauen (echtos-image.sh + die rootfs/-Bäume). |
plugins/<name>/ | Austauschbare EchtOS-Plugins (ohne App-Neubau einbindbar). |
Host-spezifisch ist nur der Server belana und der Download-Pfad /home/www/dev/rechenknecht/download/. Auf einem anderen Server die Variablen SRV/DL oben in build.sh und echtos-image.sh anpassen.
Hier geht es um die EchtOS-Plugins (Ordner mit plugin.json, laufen im Gast auf dem Handy). Die Server-Plugins (einzelne .py auf dem Rechner) sind ein eigenes System und stehen auf der Plugins-Seite.
1 · App bauen und Version hochzählen
Version setzen
Vor jedem Release die Version in rechenknecht_app/app/build.gradle.kts erhöhen:
versionCode = 112 // GANZZAHL, muss bei jedem Upload größer werden (Self-Update vergleicht die) versionName = "0.9.76" // Anzeigename, frei wählbar
versionCode ist die Pflicht-Stellschraube: Der Upload bricht ab, wenn er nicht größer ist als die zuletzt veröffentlichte Nummer. versionName ist nur Text.
Bauen
cd rechenknecht_app ./build.sh // nur bauen → APK nach ../rechenknecht-apk/ ./build.sh hochladen // bauen UND auf den Server stellen + Self-Update scharf schalten ./build.sh install // bauen UND per adb aufs angeschlossene Gerät
Was ./build.sh hochladen nacheinander tut:
- Tests (
:app:testDebugUnitTest) — schlägt einer fehl, bricht alles ab. - Signierte Release-APK (R8), 16-KB-Ausrichtung und Signatur geprüft.
- Version aus der fertigen APK gelesen (nie aus einer Konstante).
- Prüft, dass
versionCodegrößer ist als die veröffentlichte Nummer. - APK per
rsyncnach belana,app-version.jsongesetzt. - Gegenprüfung von außen: lädt die veröffentlichte APK zurück und vergleicht den SHA-256.
- Registriert die Version beim Deck-Server, damit die Handys das Update finden.
Regeln
- Der Build läuft über
gradle-sicher.sh(eigener systemd-Scope + Sperre), damit der oom-Killer auf dem Deck nicht die Sitzung abräumt. Nie direkt./gradlewaufrufen. - Der Keystore liegt in
~/.keystores/rechenknecht.jks(+.ks_pass). Fehlt er, bricht der Build ab. - Build immer am Ende eines Arbeitsblocks, nicht zwischendurch (Ressourcen).
2 · EchtOS-Image bauen
Werkzeug: werkbank-image-build/echtos-image.sh. Es ändert das rootfs/ (Pakete/Dateien), baut daraus ein tar.gz, lädt es nach belana und pinnt SHA-256 + Größe in Distro.kt. Alles mit Gegenprüfung des Hashes.
Es gibt zwei Images: desktop (Standard, XFCE/VNC, rootfs/) und console (schlanke Konsole, konsole/rootfs/, mit -k oder --image console).
Befehle
cd werkbank-image-build // Ändern: ./echtos-image.sh add <pkg…> // Pakete ins Image (apk, aarch64, ohne Skripte) ./echtos-image.sh del <pkg…> // Pakete entfernen ./echtos-image.sh search <muster> // Paket im Alpine-Repo suchen ./echtos-image.sh cp <lokal> <ziel> // Datei ins rootfs kopieren ./echtos-image.sh edit <pfad> // Datei im rootfs mit $EDITOR öffnen ./echtos-image.sh enter // Gast-Shell (braucht qemu-aarch64) // Bauen & ausliefern: ./echtos-image.sh build // strip + tar.gz packen (SHA + Größe) ./echtos-image.sh upload // tar nach belana (mit Hash-Gegenprüfung) ./echtos-image.sh pin // Distro.kt auf aktuelle SHA + Größe setzen ./echtos-image.sh release // build + upload + pin in einem ./echtos-image.sh status // SHA/Größe lokal vs belana vs Distro.kt // Für das Konsolen-Image jeweils -k davor: ./echtos-image.sh -k add tor ./echtos-image.sh -k release
Typischer Ablauf (ein Paket hinzufügen)
cd werkbank-image-build ./echtos-image.sh add conky greybird-themes // ins rootfs ./echtos-image.sh release // bauen, hochladen, Distro.kt pinnen cd ../rechenknecht_app && ./build.sh hochladen // APK zeigt auf das neue Image
Am Gerät danach: Linux-Reiter → Verwalten ▾ → Neu einrichten (lädt das neue Image).
Fallen
Pakete müssen INS Image gebacken werden — am Handy kann der Gast nichts nachinstallieren (kein Netz im proot, apk add scheitert). Niemals apk fix/Reinstall zur Laufzeit, das zerstört auf einem --no-cache-Image offline Dateien. strip (läuft bei build automatisch) hält das Image klein. enter braucht qemu-aarch64; ohne das reichen für Änderungen add/del/cp/edit.
Desktop lokal ansehen und stylen
Den XFCE-Desktop auf dem Rechner (statt am Handy) hochziehen, live hübsch machen und die Werte automatisch übernehmen.
Einmalig: qemu-user-static
sudo pacman -S --needed qemu-user-static qemu-user-static-binfmt sudo systemctl restart systemd-binfmt
Zeigen & stylen
cd werkbank-image-build ./echtos-image.sh desktop // startet den Desktop (nspawn+qemu), blockiert dann
Im Browser öffnen: http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale (beenden: im Terminal Strg+] dreimal). Läuft auf freiem Display :8, weil der Rechner selbst :0/:1 belegt; am Gerät bleibt es bei :1.
Werte übernehmen (automatisch)
./echtos-image.sh theme // GTK-Theme, Icons, DPI, Fensterrahmen → theme.env
Danach bauen: neue Themes/Icons installiert → ./echtos-image.sh release; und immer (cd ../rechenknecht_app && ./build.sh hochladen).
Wallpaper wechseln
./echtos-image.sh wallpaper /pfad/zum/bild.png // PNG oder JPG (cd ../rechenknecht_app && ./build.sh hochladen) // kein release nötig (App-Asset)
Vorschau vorher mit ./echtos-image.sh desktop.
Grenze. Das Panel-Layout steckt noch fest in start-desktop.sh.
3 · EchtOS-Plugins schreiben und einbinden
EchtOS-Plugins sind austauschbar ohne App-Neubau: ein Ordner unter plugins/<name>/, den der Server SHA-256-gepinnt ans Handy ausliefert. Verwaltet werden sie im Plugins-Reiter der App (an/aus, synchronisieren).
plugin.json — Felder
name- Werkzeugname, Kleinbuchstaben/Unterstrich (z. B.
cve_matcher). beschreibung- Ein, zwei Sätze, wann das Plugin hilft (sieht die KI).
schema- JSON-Schema-Objekt:
properties+required. Das sind die Argumente. skript*- Einstiegsdatei.
.pyläuft mitpython3,.shmitsh. dateien- Liste aller mitzuliefernden Dateien (Skript, Datenbanken …).
nur_lesentrue= läuft ohne Rückfrage;false= erst nach Bestätigung.shellechtos(Pentest-Gast) odersystem(Android-Shell, ohne su).tortrue= Verkehr über Tor; läuft nur bei aktivem Tor-Plugin (SOCKS 9050 live), sonst Abbruch.
* Reine Dienst-Plugins (wie tor) haben statt skript die Felder start/stop, kein_werkzeug: true und ggf. braucht_pkg.
Minimalbeispiel
plugins/hallo/plugin.json:
{
"name": "hallo",
"beschreibung": "Begrüßt einen Namen. Nur ein Test.",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Wen grüßen" }
},
"required": ["name"]
},
"nur_lesen": true,
"shell": "echtos",
"tor": false,
"skript": "skript.py",
"dateien": ["skript.py"]
}
plugins/hallo/skript.py:
import sys, json
args = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
print(f"Moin, {args.get('name', 'Welt')}!")
Runner-Vertrag
- Das Plugin bekommt seine Argumente als ein JSON-String als erstes Argument und gibt sein Ergebnis über stdout zurück (reiner Text).
shell: echtosläuft im Gast (/root/plugins/<name>/),shell: systemin der Android-Shell (App-privat).- Bei
tor: truesetzt der RunnerRK_PROXY/ALL_PROXYaufsocks5://127.0.0.1:9050— aber nur, wenn das Tor-Plugin aktiv und der Port live ist. - Ergebnisse werden zusätzlich im Gast unter
/root/ergebnisse/<name>-<zeit>.txtabgelegt (überleben einen abgebrochenen Aufruf).
Echte Beispiele zum Abgucken
Zwei fertige, nutzbare Plugins liegen als Vorlage im Repo — gute Muster für eigene (HTTP holen, HTML parsen, Text ausgeben):
plugins/kleinanzeigen/— Suche auf Kleinanzeigen.de (Ort/Umkreis, Preisfilter, Trefferliste).plugins/wayback/— Wayback Machine (archive.org): Aufnahmen finden, auflisten, lesen, zwei Zeitpunkte vergleichen.
Beide nutzen requests + beautifulsoup4 (liegen im Image) und spiegeln eingebaute App-Werkzeuge. wayback heißt anders als das eingebaute wayback_machine, kollidiert also nicht; kleinanzeigen gibt es nur noch als Plugin, eingebaut ist es nicht mehr.
Einbinden (am Gerät, ohne App-Neubau)
Ordner unter
plugins/<name>/ablegen, Server läuft.In der App: Plugins-Reiter → Deck-Plugins → Synchronisieren. Die App lädt geänderte Dateien SHA-geprüft in den Gast.
Plugin anschalten. Danach kennt die KI es als Werkzeug.
Braucht dein Plugin ein Programm im Gast (z. B. nmap), muss das vorher ins Image (Abschnitt 2, add). Reine Python-Skripte mit Standardbibliothek brauchen das nicht.
Sicherheit
nur_lesen: true nur für Plugins, die wirklich nichts verändern — alles andere fragt vor jedem Lauf. Tor-gebundene Plugins (tor: true) laufen nie ungeschützt direkt: ohne aktives Tor-Plugin bricht der Runner ab.
4 · Spickzettel: Reihenfolge
Nur App geändert (Kotlin)
cd rechenknecht_app // Version in app/build.gradle.kts hochzählen ./build.sh hochladen
Image geändert (Paket/Datei im Gast)
cd werkbank-image-build ./echtos-image.sh add <pkg> // oder del/cp/edit ./echtos-image.sh release cd ../rechenknecht_app && ./build.sh hochladen // Gerät: Linux → Verwalten ▾ → Neu einrichten
Plugin geändert (kein Build nötig)
// Datei in plugins/<name>/ ändern → in der App: Plugins → Synchronisieren