Upgrade Guide: Open Source → Professional+

Prerequisites

• A running open-source SysManage server (any release from v1.3.0 onward)
• Outbound HTTPS to license.sysmanage.org from the SysManage server (the module loader needs to pull the Cython engines + plugin bundles)
• A Professional or Enterprise license key — either purchased or evaluation
• ~50 MB free disk under /var/lib/sysmanage/modules/ for the cached binaries

Upgrade steps

1. Drop the license key into your config

Edit /etc/sysmanage.yaml and add (or replace) the license_key field under the pro_plus section:

pro_plus:
  license_key: "eyJhbGciOiJSUzI1NiIs...<your-jwt-here>"

The license is a signed JWT. Do not edit it; just paste the whole string.

2. Restart the server

Restart the SysManage backend so it picks up the license and contacts the license server. On systemd-managed installs:

sudo systemctl restart sysmanage

For developer installs (make start), stop and start as you normally would.

3. Watch the module loader log

During startup the loader fetches the public key, validates the license, and downloads each entitled module (one Cython binary plus one frontend plugin bundle per engine). Tail the log:

tail -f /var/log/sysmanage/backend.log | grep -E "license|module_loader|Pro\+ module"

You should see lines like:

License validated successfully: tier=enterprise, expires=...
Module downloaded: health_engine v2.0.7 ...
Module loaded: health_engine from /var/lib/sysmanage/modules/health_engine_3.14.so
...
Pro+ module routes mounted: {'health_engine': True, ..., 'av_management_engine': True}

First-time downloads can take 30-90 seconds depending on the link to license.sysmanage.org. Subsequent restarts use cached binaries and complete in seconds.

4. Hard-refresh the browser

The web UI caches the plugin bundle list in browser memory. After the server restart, hard-refresh (Ctrl+Shift+R / Cmd+Shift+R) so the new bundles load. Pro+ tabs and dashboard cards should appear.

5. Verify the new endpoints

In the browser DevTools console (logged in):

// Should return 200 (NOT 402) if the Health engine is licensed:
fetch('/api/v1/health/status', {credentials:'include'}).then(r => r.status).then(console.log)

Tier comparison: Professional vs Enterprise

Both tiers run the same open-source server with different bundles of modules unlocked.

Professional includes

• health_engine — AI-driven host health analysis
• vuln_engine — CVE database + per-host vulnerability scanning
• compliance_engine — CIS / STIG compliance checking
• alerting_engine — Email / webhook / Slack / Teams alert routing
• reporting_engine — Scheduled report generation
• audit_engine — Audit log retention + SIEM export
• secrets_engine — OpenBAO-backed secret deployment to hosts
• container_engine — Full WSL / LXD container lifecycle (open source has read-only)
• proplus_core — Pro+ settings + license management UI

Enterprise adds

• av_management_engine — Centralised ClamAV / ClamWin deployment, named policies, scan scheduling, commercial-AV detection (CrowdStrike, SentinelOne, Defender, etc.)
• firewall_orchestration_engine — Multi-platform firewall config generation (UFW, firewalld, pf, ipfw, npf, Windows Firewall, macOS), role assignment, fleet deployment, conflict detection, compliance reporting

What does NOT change

Upgrading to Pro+ is purely additive. None of the following move:

• Your PostgreSQL/SQLite database, hosts table, users, certificates, audit log
• Existing sysmanage.yaml settings (the pro_plus.license_key field is the only addition needed)
• Open-source API endpoints — existing scripts/integrations keep working byte-for-byte
• Connected agents — no agent-side changes are required to use Pro+ features (the new declarative apply_deployment_plan handler is already in the open-source agent)

License renewal & rotation

When your license is approaching expiry (visible in Settings → License in the web UI), generate a new key from the Pro+ portal and replace the license_key value in /etc/sysmanage.yaml. Restart the server. The module loader re-validates against the license server's public key on every restart and on a periodic background check (default every 24 hours).

If the license expires while the server is running, all Pro+ endpoints transition back to {"licensed": false, "expired": true}. The open-source functionality keeps working — nothing breaks; only the Pro+ surface is gated off.

Downgrade / removal

To go back to community edition: remove the license_key line from sysmanage.yaml and restart. The Pro+ engines will fail their license check and the server will mount the 402 stubs in their place. Optionally, delete the cached binaries to reclaim disk:

sudo rm -rf /var/lib/sysmanage/modules/*

Troubleshooting

"I added the license but Pro+ features don't appear"

1. Confirm the JWT is well-formed: echo "$LICENSE" | cut -d. -f2 | base64 -d | python3 -m json.tool — should show your tier and the modules array
2. Check the backend log for "License validated successfully" and the per-module download lines
3. Hard-refresh the browser to drop cached plugin bundle metadata
4. Log out and back in — some plugin state is per-session

"The first restart after adding the license takes forever"

Expected. The loader is downloading every entitled module (.so) and plugin bundle (.iife.js) from license.sysmanage.org for the first time. Subsequent restarts use the on-disk cache and complete in seconds.

"I see Pro+ features but every API call returns 402"

The license is valid but the specific feature isn't in your tier. Check the features array in your decoded JWT — if the feature code (e.g. av_install, firewall_compliance_check) isn't there, contact sales to upgrade tier.

"Module download failed: connection timeout"

The SysManage server can't reach license.sysmanage.org. Confirm outbound HTTPS (TCP/443) is allowed, especially through any corporate proxy. For air-gapped installations a separate offline-licensing flow is planned for Phase 11.