Privileged Agent
Last updated
jabali-agent.service. Root-privileged process; the only thing that performs privileged host operations. Callers (the panel API, the CLI, the reconciler) reach it over the Unix socket /run/jabali/agent.sock.
Why a separate process
- One privilege boundary: the panel runs as the unprivileged
jabaliuser; only the agent has root. - One auditable surface: every privileged op goes through one of N handlers under
panel-agent/internal/commands/. The audit log records the agent’s call, not the panel’s intent. - Restart-safe: restarting the panel doesn’t kill in-flight host ops; restarting the agent doesn’t lose panel state.
Wire protocol
Newline-delimited JSON over the Unix socket, one request per connection. The envelope types live in agentwire/wire.go. Each request:
{ "id": "01J...", "command": "domain.create", "params": { … }, "deadline": "2026-09-28T12:00:00Z" }
deadline is optional. Each response echoes the request id:
{ "id": "01J...", "ok": true, "data": { … } }
{ "id": "01J...", "ok": false, "error": { "code": "invalid_argument", "message": "human-readable" } }
Handler catalogue (representative; see panel-agent/internal/commands/)
Domains / nginx
domain.create,domain.update,domain.deletenginx.reload,nginx.cache.purge,nginx.ratelimits.apply
SSL
ssl.issue,ssl.issue_dns01,ssl.renew,ssl.revoke,ssl.self_sign,ssl.cert_infossl.install_custom,ssl.install_shared,ssl.delete_sharedssl.mail.issue,ssl.mail.delete(per-domainmail.<domain>certificates)ssl.panel.issue,ssl.panel.selfsign(the panel hostname and panel mail certificates)ssl.panel.mail_served(checks that IMAPS and SMTPS serve the new mail certificate before a mail hostname change is applied),ssl.panel.lineage_delete(removes the certbot lineage of a replaced custom mail hostname)
Webmail
webmail.vhost_apply,webmail.vhost_remove,webmail.branding.applywebmail.jmap_url.apply,nginx.webmail_redirect.apply(move webmail to the applied mail hostname)
DNS
dns.zone.upsert,dns.zone.deletedns.dnssec.enable,dns.dnssec.disable
Mail (Stalwart)
mail.mailbox.create,mail.mailbox.passwd,mail.mailbox.set_quota,mail.mailbox.deletemail.auth_cache.flush(clears Stalwart’s HTTP login cache). Stalwart answers webmail and JMAP logins from this cache, not the mailbox table, so without a flush an old password or a disabled mailbox kept working there. The panel calls it when a mailbox is disabled. The password, mailbox delete, domain purge and domain rename verbs flush it themselves. It runs at most once every 5 seconds; a change inside that gap gets one flush at its end.mail.forwarder.upsert,mail.forwarder.deletemail.autoresponder.upsert,mail.autoresponder.deletemail.catchall.setmail.disclaimer.setmail.shared_folder.*mail.directory.apply(a mail domain’s read-only directory address book)mailbox.trusted_senders.apply(a mailbox’s trusted senders, as contact cards in its Stalwart account)mail.mtasts.*
DB
db.create,db.deletedb.user.create,db.user.delete,db.user.passwddb.root.password.rotatedb.config.applydb.maintenance.run(OPTIMIZE / ANALYZE / CHECK / REPAIR)db.processlist,db.killdb.pma.admin.ensure
System / OS
user.create,user.deleteuser.limits.apply,user.limits.clearuser.egress.apply,user.egress.clearsshkey.writequota.set
PHP
php.pool.write,php.pool.deletephp.ext.enable,php.ext.disablephp.reload
Backups
backup.destination.testbackup.run(kind=account_full/system_backup)backup.restore
Apps
app.install,app.delete,app.clone,app.updateapp.sso.write(writes the self-deleting magic SSO file)
Security
crowdsec.allowlist.*appsec.policy.applyaide.scanmalware.scan.runquarantine.move
Misc
nginx.cache.purge,nspawn.*,systemd.restart,systemd.start,systemd.stop
What the agent never does
- Receive HTTP. The agent does not have an HTTP listener. The panel API is the HTTP entry point.
- Talk to Kratos directly. Identity lives in the panel.
- Make outbound calls to third parties without the panel telling it to. (Even certbot is invoked with
--standalone-only=falseagainst the existing nginx vhost; no rogue outbound.)
Hardening
- Two checks on every connection to the main socket:
- Socket permissions.
/run/jabali/isroot:jabali 0750and the socket isroot:jabali 0660, so only root and thejabaligroup can connect. - Caller UID. The agent reads the connecting process’s UID (
SO_PEERCRED) and accepts only the UIDs in-allowed-uids. install.sh passes the panel user and root. The agent refuses to start when the list is empty or unparsable; only the test flag-insecure-allow-any-uidturns the check off. So a service account left in thejabaligroup by mistake still cannot drive the agent.
- Socket permissions.
- Only the UIDs in
-admin-uidsmay request the root-scoped File Manager. By default this is the-allowed-uidslist. - No other service is a member of the
jabaligroup, and a restore never adds one back. - The agent has no AppArmor profile. It was removed because an AppArmor 4.x complain-mode bug blocked the agent’s MariaDB socket connection. See AppArmor.
- Each handled request is logged at debug level with
id,commandandok.
Adding a new handler
- New file
panel-agent/internal/commands/foo_bar.gowith the command name and param struct. - Wire-contract golden test (mirror
security_crowdsec_geoblock_golden_test.go). - Call site on the panel side (an API handler or a reconciler).
- ADR if the decision is load-bearing.