How do I update or roll back a signature generation?

A signature update is the most dangerous routine operation a scanner performs. It can quarantine a thousand healthy files across a hundred customers in one minute. Everything below exists to make that reversible.

The three commands

shelltrap feeds list
shelltrap feeds update
shelltrap feeds rollback 20260903T120000Z-0001

feeds list shows the generations present, which one is active and where it came from. feeds update fetches on demand instead of waiting for the timer. feeds rollback switches back to a named earlier generation.

What a rollback actually does

Activation and rollback are root-only. Signature, manifest canonicality and every file digest are re-verified immediately before the switch — including after the move out of staging, because a long gate run is a long window. The generation is moved into the feed root without overwriting anything, and the current symlink is swapped atomically through a temporary symlink and rename. Only then does the worker reload and the cache invalidate the previous generation.

If a step fails, a best-effort compensation restores the previous symlink, worker state and ClamAV files. Where a compensation cannot restore a consistent state, the actually loaded state is reported as it is, with the error, rather than falsely claiming a rejection.

A rollback target must not be expired, and a rollback onto a revoked generation is permanently blocked. Revocations are absorbed into an append-only tombstone file and entries are never removed, even if a later index stops listing them.

The automatic rollback

A multi-tenant circuit breaker compares the last hour against the 24-hour mean. By default it needs at least 50 quarantines and more than ten times the mean, and additionally at least three distinct accounts and at least 20 % of all active accounts. Both account thresholds are configurable in [feeds]:

circuit_min_accounts = 3
circuit_min_active_percent = 0.20

The point of those two extra conditions is blunt: a single account can never trigger a server-wide rollback. One customer uploading a hundred infected files is a customer problem, not a rule problem. Heuristic, missing or contradictory signals never trigger a rollback either.

When you should roll back by hand

If you see a burst of findings on files you recognise as legitimate — a plugin update, a framework everyone uses — roll back first and investigate afterwards. Then report the false positive so the rule is corrected for everyone; see "How do I report a false positive?".

Checking the state

shelltrap feeds list
shelltrap health
shelltrap audit tail

Health reports an unconfigured remote feed as feeds: not_configured, and that sub-status alone does not make the overall status degraded — a missing active generation does.