Dokumentation on Shelltrap

Installation und Erstinbetriebnahme

Mon, 01 Jan 0001 00:00:00 +0000

Voraussetzungen

Root-Zugriff oder ein Paket-Dienstkonto mit vollen Installationsrechten. Der Broker shelltrapd läuft als root; der Worker läuft als shelltrap-scan, einem Systembenutzer ohne Login-Shell und ohne Home-Verzeichnis.
Ein von CyberPanel unterstütztes Betriebssystem: Ubuntu 20.04, 22.04 oder 24.04; AlmaLinux, RockyLinux oder RHEL 8, 9 oder 10; CloudLinux 8; CentOS 9. Debian wird von CyberPanel nur über Dritte unterstützt und ist nicht zugesichert.
Ein Linux-Dateisystem unterhalb der konfigurierten Kundenverzeichnisse (standardmäßig /home), ausreichend Arbeitsspeicher und ein Kernel, auf dem der Installer die fanotify- und File-Handle-Capabilities tatsächlich prüfen kann.
Für das Full-Profil: mindestens 1,5 GiB MemAvailable, die nach der gemessenen Reload-Reserve verbleiben; diese umfasst den beobachteten clamd-Speicherbedarf zuzüglich eines festen Sicherheitszuschlags. Diese Messung darf nicht durch eine globale sysctl-Änderung ersetzt werden.
Für ClamAV im Full-Profil: ein laufender oder installierbarer clamd und ein Unix-Socket, der für den Benutzer shelltrap-scan erreichbar ist, standardmäßig /run/clamav/clamd.ctl. Ein nur für root lesbarer Socket genügt nicht. Fehlt der Dienst oder der Zugriff des Workers, wird der Zustand degraded und niemals clean.
Für den PHP-Upload-Adapter: eine unterstützte lsphp/LSWS-Installation. Der Adapter benötigt lediglich den lokalen Socket /run/shelltrap/upload.sock.
Werkzeuge: sha256sum, GnuPG und entweder curl oder wget für den Host-Installer; für das CyberPanel-Paket zusätzlich unzip. Abhängigkeiten löst der native Paketmanager auf.

Host-Preflight

Vor jedem Download gibt der Host-Installer rein lesende Fakten über die Maschine aus und verändert nichts:

Konfiguration und Richtlinien

Mon, 01 Jan 0001 00:00:00 +0000

Das Richtlinienmodell

Jede Einstellung, die das Verhalten steuert, ist eine Richtlinie auf drei Ebenen:

global — der gesamte Host
account — ein CyberPanel-Benutzer
domain — eine Website oder Child-Domain

Die spezifischere Ebene gewinnt, und jede Ebene kann einzelne Schlüssel erben oder überschreiben. Innerhalb einer Domain sind zusätzlich Pfadregeln mit Globs relativ zum Document-Root möglich.

Die Zuordnung erfolgt über einen Document-Root-Index, den der Broker aus der CyberPanel-Datenbank führt (Website, Child-Domain, Document-Root, Eigentümer) und der per Timer sowie bei Änderungen im Panel aktualisiert wird. fanotify-Ereignisse werden über das längste passende Document-Root-Präfix einem Konto und einer Domain zugeordnet. Der PHP-Adapter übergibt DOCUMENT_ROOT und SERVER_NAME; entscheidend ist der Document-Root, der Servername dient nur als Plausibilitätsprüfung. Dateien außerhalb jedes Document-Roots — E-Mail, Backups, das Home-Verzeichnis — fallen unter die Kontorichtlinie.

Das CyberPanel-Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Vor der Installation

Der Shelltrap-Broker muss laufen, /run/shelltrap/api.sock muss vorhanden sein, und CyberPanel muss installiert sein. Das Plugin-Archiv wird reproduzierbar gebaut und enthält genau ein Verzeichnis shelltrap/ auf oberster Ebene, ohne Caches und ohne Python-Bytecode.

cd /usr/local/CyberCP
/usr/local/CyberCP/bin/python /usr/local/CyberCP/pluginInstaller/pluginInstaller.py \
 install --pluginName shelltrap

Warum die Installation so vorsichtig vorgeht

Der CyberPanel-Installer patcht Kerndateien — CyberCP/settings.py, CyberCP/urls.py und das Sidebar-Template — durch das Einfügen von Zeilen, und seine Hook-Aufrufe nutzen subprocess.call und ignorieren Exit-Codes. Ein fehlgeschlagener Preflight kann die Installation daher nicht daran hindern, Erfolg zu melden.

Signatur-Feeds

Mon, 01 Jan 0001 00:00:00 +0000

Aktiviert wird nur, was signiert, zweifach verifiziert, gegen ein Known-good- und ein Known-bad-Korpus geprüft und widerrufbar gemacht wurde.

Generationen statt Updates

Ein Regelsatz ist kein Strom von Änderungen, sondern eine Generation: ein unveränderliches, signiertes Verzeichnis. Vendor-Generations-IDs lauten exakt YYYYMMDDTHHMMSSZ-NNNN, zum Beispiel 20260903T120000Z-0001. Lokale Overlays verwenden local-<64 hex characters>.

Lizenzierung und Aktivierung

Mon, 01 Jan 0001 00:00:00 +0000

Die Bestandteile

Begriff	Bedeutung
Lizenzschlüssel	`STL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX` — Crockford Base32, 25 Nutzzeichen einschließlich zweier Prüfzeichen. Wird bei der Erstellung der Lizenz erzeugt und genau einmal im Klartext zurückgegeben; der Dienst speichert nur `sha256(key)` sowie die ersten neun Zeichen als Anzeigepräfix.
Lizenz	Der Datensatz: Tarif, maximale Serveranzahl (standardmäßig 1), Status (`active`, `suspended`, `terminated`), Ablauf und die Verknüpfung mit Ihrem Konto.
Aktivierung	Die Bindung einer Lizenz an einen Server-Fingerabdruck. Höchstens `max_servers` gleichzeitig; `deactivate` gibt einen Platz frei.
Lizenz-Token	Ein Ed25519-signiertes Dokument, das der Daemon offline verifiziert.
Server-Fingerabdruck	`sha256` über ein festes Präfix und den Inhalt von `/etc/machine-id`. Der Hostname wird nur zur Information übermittelt.

Aktivierung

shelltrap license activate STL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
shelltrap license status
shelltrap license renew
shelltrap license deactivate

Das Token landet in /etc/shelltrap/license.token, Eigentümer root, Modus 0600. Der Schlüssel selbst wird nur als Präfix in /etc/shelltrap/license.key abgelegt, ebenfalls 0600, damit Sie ihn für Erneuerungen nicht erneut eingeben müssen. Wenn Sie den Schlüssel lieber gar nicht auf dem Server haben möchten, löschen Sie diese Datei und erneuern manuell.