Documentation on Shelltrap

Installation and first run

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

Requirements

Root access, or a package service account with full installation rights. The broker shelltrapd runs as root; the worker runs as shelltrap-scan, a system user without a login shell and without a home directory.
A supported CyberPanel operating system: Ubuntu 20.04, 22.04 or 24.04; AlmaLinux, RockyLinux or RHEL 8, 9 or 10; CloudLinux 8; CentOS 9. Debian is only third-party supported by CyberPanel and is not promised.
A Linux filesystem under the configured customer roots (/home by default), enough memory, and a kernel on which the installer can actually probe the fanotify and file-handle capabilities.
For the Full profile: at least 1.5 GiB of MemAvailable remaining after the measured reload reserve, which includes the observed clamd footprint plus a fixed safety margin. This measurement must not be replaced by a global sysctl change.
For ClamAV in the Full profile: a running or installable clamd and a Unix socket reachable by the shelltrap-scan user, /run/clamav/clamd.ctl by default. A socket readable only by root is not enough. If the service or the worker’s access is unavailable, the state becomes degraded and never clean.
For the PHP upload adapter: a supported lsphp/LSWS installation. The adapter needs only the local socket /run/shelltrap/upload.sock.
Tools: sha256sum, GnuPG and either curl or wget for the host installer; unzip in addition for the CyberPanel package. The native package manager resolves dependencies.

Host preflight

Before any download, the host installer prints read-only facts about the machine and changes nothing:

Configuration and policies

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

The policy model

Every setting that steers behaviour is a policy on three levels:

global — the whole host
account — one CyberPanel user
domain — one website or child domain

The more specific level wins, and each level may inherit or override individual keys. Inside a domain there can also be path rules using globs relative to the document root.

Assignment works through a document-root index the broker keeps from the CyberPanel database (website, child domain, document root, owner), refreshed on a timer and on panel changes. fanotify events are mapped to an account and a domain by the longest matching document-root prefix. The PHP adapter passes DOCUMENT_ROOT and SERVER_NAME; the document root decides and the server name is only used as a plausibility check. Files outside every document root — mail, backups, the home root — fall under the account policy.

The CyberPanel plugin

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

Before you install

The Shelltrap broker must be running, /run/shelltrap/api.sock must exist, and CyberPanel must be installed. The plugin archive is built reproducibly and contains a single top-level directory shelltrap/, without caches or Python bytecode.

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

Why the install is so careful

The CyberPanel installer patches core files — CyberCP/settings.py, CyberCP/urls.py and the sidebar template — by inserting lines, and its hook calls use subprocess.call and ignore exit codes. A failed preflight therefore cannot stop the installation from claiming success.

Signature feeds

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

Nothing is activated that has not been signed, verified twice, gated against a known-good and a known-bad corpus, and made revocable.

Generations, not updates

A rule set is not a stream of edits; it is a generation: an immutable, signed directory. Vendor generation IDs are exactly YYYYMMDDTHHMMSSZ-NNNN, for example 20260903T120000Z-0001. Local overlays use local-<64 hex characters>.

Licensing and activation

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

The pieces

Term	Meaning
Licence key	`STL-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX` — Crockford Base32, 25 payload characters including two check characters. Generated when the licence is created and returned in clear text exactly once; the service stores only `sha256(key)` plus the first nine characters as a display prefix.
Licence	The record: plan, maximum servers (1 by default), status (`active`, `suspended`, `terminated`), expiry, and the link to your account.
Activation	Binding a licence to a server fingerprint. At most `max_servers` at a time; `deactivate` frees a slot.
Licence token	An Ed25519-signed document the daemon verifies offline.
Server fingerprint	`sha256` over a fixed prefix and the contents of `/etc/machine-id`. The hostname is sent for information only.

Activation

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

The token lands in /etc/shelltrap/license.token, root, mode 0600. The key itself is stored only as a prefix in /etc/shelltrap/license.key, also 0600, so renewals do not need you to type it again. If you would rather not have the key on the server at all, delete that file and renew manually.