Sysible Controller

1. Overview

Sysible Controller is a self-hosted, point-and-click way to manage a fleet of Linux hosts. It is two pieces: a FastAPI backend (the sysible-backend service, HTTPS on port 9000, holding the fleet inventory, credentials, and task queue in SQLite) and a browser web console (the sysible-webgui service, HTTPS on port 8800). You administer everything from any browser on the network — no desktop environment is needed on the controller or your workstation.

Hosts are managed two interchangeable ways, mixable in one fleet:

The Sysible agent — a small Python daemon on the host that heartbeats to the controller and polls for work.
Direct SSH — hand the controller SSH credentials once; it installs its own key and drives the host from then on.

Every action runs as the administrator who triggered it. When alice runs a command, the agent executes it as the local alice account (runuser -u alice) with that user's sudo rights — not as a faceless root daemon. Reads are tried unprivileged first, then escalated only when the OS reports a privilege error. The run-as identity comes from the signed login token, never from the browser.

2. Requirements

A Linux controller host — Debian/Ubuntu, RHEL/CentOS/Fedora, or openSUSE/SLES — with root for install.
Python 3 (provisioned by the installer) and Node.js 18+ (installed by the installer; build-time only for the web console).
Any modern browser on a machine that can reach the controller. No desktop environment required.

3. Installation

# from the folder containing the project files
sudo ./install_sysible.sh

The installer deploys to /opt/sysible, creates a Python venv, generates a self-signed TLS certificate and admin API key, installs the two systemd services (sysible-backend, sysible-webgui), builds the React front end, and installs the sysible_controller CLI. The backend and web console start independently:

sudo sysible_controller start          # backend (port 9000)
sudo sysible_controller webgui start   # web console (https://<host>:8800/)

A fresh install seeds a default superuser named admin with a one-time password printed once, in red, at the end of the install output. Sign in at https://<controller>:8800/, then change it under Settings → My Account. If administrators already existed, no default is seeded — use sudo sysible_controller reset-admin to set one.

5. Roles & identity

Superuser

Full control, plus manages other administrators, TLS, the Webserver Portal, and controller/agent updates.

Sysadmin

Manages the fleet — every tool, Connect, enrollment, scheduling, alerting — but not administrators or the portal/TLS.

Auditor

Read-only oversight: sees the dashboard, patch status, performance, and the activity log, but cannot act. Enforced server-side, not just hidden in the UI.

6. Sudo modes — passwordless or password ("become")

Privileged commands run as your mapped user and escalate via that host's sudo. Passwordless-sudo hosts just work. For hosts that require a sudo password, store yours once with the header's Sudo Password button (encrypted at rest on the controller, fed to sudo -S over stdin only). Read-only actions (listing services/packages, check-in) never need sudo.

7. Dashboard

The home screen: a fleet-health overview (per-environment cards with disk/memory meters and problem signals) and a compliance/posture strip. Click a count (online/offline/enrolled) or a compliance signal to see exactly which hosts. Click a host to open its posture drill-down, where every warn/bad finding is actionable — reboot right there, or jump straight to the tool that fixes it (SSH → Security Administration, cert → Certificate Management, etc.).

The dashboard: fleet-health cards and the compliance/posture strip.

8. Update Hosts (patching)

A fleet-wide patch view: pending updates, security updates, and reboot-required per host, grouped by environment. Rescan recounts from cached repo metadata (fast); Refresh metadata & rescan forces a live repo refresh. Select hosts and Install security updates or Install all updates — installs run in the background with a live per-host progress bar and command output, and the counts refresh as hosts finish. Reboot selected hosts from the same screen.

Update Hosts — fleet-wide patch status grouped by environment.

9. Scheduled jobs

Recurring, unattended maintenance you set once. Pick an action, targets (all or selected hosts), and a cadence (hourly/daily/weekly at a chosen time). Actions: rescan patch status, rescan posture, install security/all updates, clean package cache, vacuum journal logs, trim filesystems (fstrim), clear failed units, sync clock, restart a named service, run a shell command, or reboot. Jobs run on the controller and dispatch as root on agent hosts. Each job shows its next/last run; Run now, pause, and delete are one click.

Creating a scheduled job — action, cadence, time, and per-environment targets.

10. Alerting

Notify on threshold crossings via email (SMTP) and/or a Slack-compatible webhook. Built-in rules include host offline, disk/memory/load thresholds, failed units, OOM kills, pending/security updates, reboot required, cert expiry, firewall disabled, SELinux/AppArmor not enforcing, SSH root login, and clock drift. Custom regex rules run a command on each host and alert when its output matches (or fails to match) a pattern. The controller evaluates rules every ~5 minutes, fires once per condition, and resolves when it clears. The SMTP password is encrypted at rest and never returned to the browser.

Alerting — built-in thresholds plus custom regex rules.

11. Performance

Time-series graphs (CPU, memory, swap, disk, network, disk I/O, load, processes) per environment or drilled into a single host. Hover for a crosshair and per-series values; drag to zoom a time range (shared across all charts); click a chart title to enlarge it into its own window for analysis.

Performance — interactive time-series charts.

12. Host enrollment

Host Enrollment (superuser) gives you the agent bundle to install on a host, and one-click SSH enrollment (password used once, then discarded for a generated key). Agent hosts are auto-enrolled for SSH so they also get a real terminal when an SSH server is present.

Host Enrollment — agent bundle and one-click SSH enrollment.

13. System Administration Tools

Every tool follows the same pattern: check the target hosts on the left, fill any fields, and run an action — results come back per host, grouped by environment, each collapsible with a one-line summary, an "Only problems" filter, and a search.

The System Administration Tools catalog — each tile opens to grouped actions with per-host, per-environment results.

User & Group Administration

Create, lock, and manage user accounts, passwords, sudo access, and groups across agent and SSH hosts.

System Health, Logs & Recovery

Disk usage, memory/CPU, failed services, logs, and process tools, plus boot/GRUB and kernel recovery — across agent and SSH hosts.

Service Management

Start, stop, restart, enable/disable, and troubleshoot systemd services, or create and configure new ones.

Environmental Policies

Set the baseline password, lockout, sudo, and umask policy for accounts on managed hosts, and push it out.

Cron & Systemd Timers

View, add, and remove cron jobs, and view, create, start/stop, enable/disable, and delete systemd timers.

Host Software Management

Detect each host's package manager, then install, remove, update, query, verify, and clean packages across dnf/yum, zypper, and apt hosts alike.

Repository Management

List, add, enable, disable, and remove software repositories across dnf/yum, zypper, and apt hosts.

Network Management

Diagnose connectivity and DNS, inspect ports and capture packets, and configure IP/DHCP/DNS/gateway/routing/hostname/bonding/teaming/VLANs/bridges/MTU across managed hosts.

File System Management

Create/remove directories, copy/move/rename files, manage ownership/permissions/ACLs and links, mount/unmount/resize/repair filesystems, configure /etc/fstab and quotas, and archive/compress files across managed hosts.

Storage Administration

Partition, format, and monitor disks, manage LVM physical volumes/volume groups/logical volumes, configure RAID and replace failed disks, and set up swap space across managed hosts.

Firewall Administration

Configure firewalld zones, ports, and rich rules, and manage the underlying nftables and iptables rule sets across managed hosts.

Security Administration

Configure and troubleshoot SELinux, harden SSH access and rotate keys, review audit logs and failed logins, install security updates, set password policy, harden systems, and run vulnerability scans across managed hosts.

Backup & Recovery

Back up and restore files, verify backup integrity, schedule backups, create and restore LVM snapshots, guide deleted-file recovery, and run disaster-recovery drills.

Time Synchronization

Configure NTP/chrony, verify synchronization, troubleshoot clock drift, and set the system time zone across managed hosts.

Certificate Management

Generate CSRs, install/renew/replace certificates, verify certificate chains, and troubleshoot TLS endpoints across managed hosts.

Containers & VMs

List and start/stop/restart Docker or Podman containers, view container logs and images, and manage libvirt virtual machines across managed hosts.

Directory Services (Active Directory / LDAP)

Join hosts to Active Directory (realmd/SSSD), manage realm status and login permits, enable home-dir creation, and configure/test LDAP and LDAPS.

Distro Subscription & Licensing

Register and manage commercial-distro subscriptions: Red Hat (subscription-manager), Ubuntu Pro, and SUSE (SUSEConnect) — status, attach/enable, and repositories.

14. Quick System Actions

A fast lane for everyday fixes across selected hosts, in its own sidebar item: restart/start/stop a service (with a live service browser — list running services on a host and click to pick one), restart NetworkManager / SSH / time sync / Docker / the Sysible agent, flush DNS, sync the clock, free memory, clean package cache, vacuum journal logs, trim filesystems, clear failed units, reload systemd, and reboot / power off.

Quick System Actions — the fast lane for everyday fixes.

15. Sysible Connect

A unified list of agent- and SSH-managed hosts. Double-click a host for a real PTY terminal (multiple sessions per host, opened as your administrator user, with file upload/download, find, save-output, and Send-sudo-password). The right side has Fleet Actions (run a script, restart the agent, reboot, power off — across the fleet, confirmed), file transfer, and SSH-enroll. Check In / Ping probes the checked hosts (or one, by clicking its status dot) and shows the reachable/unreachable results in a popup. Right-click a host to assign an environment.

Sysible Connect — a real browser terminal and fleet actions.

16. Activity & logs

The Activity feed attributes every action to the administrator who ran it, where, and when (visible to superusers and auditors). The Controller log tab (superuser only) tails the backend service journal.

17. Settings

My Account — change your own username/password.
Administrators (superuser) — add accounts with a role, reset passwords, promote/demote.
TLS certificate (superuser) — install a real cert/key/chain for the controller.
Webserver Portal (superuser) — run and credential the host-operator portal.
Software updates (superuser) — update the controller and agents together with live output, and download the update log.

Settings — accounts, TLS, portal, and software updates.

18. Webserver Portal

An optional, separate self-service site for host operators (not Sysible administrators) to download the agent bundle or exchange files with the controller from a browser — no shell access needed. Superusers start it, set its port, and manage its credentials and sessions from Settings.

19. CLI reference

Command	Root?	What it does
`start`	Yes	Start the backend service.
`stop` / `restart`	Yes	Stop / restart the backend (and web console).
`status` / `logs`	No	Backend + web console status; tail the backend log.
`webgui {start\|stop\|restart\|status\|logs}`	Yes*	Control the web console service; builds the front end on start.
`update`	Yes	Pull latest code, redeploy, and restart in place.
`reset-admin [user] [pass]`	Yes	Set/create a web-console admin password (printed once).
`self-enroll`	Yes	Enroll this controller as a managed host (privileged local agent). Idempotent; runs automatically on first `start` unless `SYSIBLE_NO_SELF_ENROLL=1`.
`destroy`	Yes	Remove the deployment.

20. Security model

Roles enforced server-side — the controller refuses privileged actions for an auditor token; the web BFF blocks every write route for auditors. Portal/TLS are superuser-only at both layers.
Run-as identity from the signed login token (never the browser), so each host's sudo policy and audit trail stay meaningful.
HTTPS everywhere, TOFU SSH host-key pinning, and secrets (sudo/SMTP passwords) encrypted at rest.
Session cookie — signed, http-only, SameSite=Strict; the controller API key never reaches the browser.

Contents