Skip to main content

Patch

@dmc/patchv2026.11.14.1· MIT· 7d agoBEHAVIORSREPORTSACCEPTED WARNINGS
01README

Agentless fleet patch management — scan Proxmox VMs/CTs, bare-metal, and VPS hosts for pending updates, apply them safely (snapshot-guarded, health-checked, auto-rollback), and keep an auditable history over @swamp/ssh. Routine work runs as a restricted, audited login with exact sudo grants and a per-machine OS update policy. App updaters, snapshotters and OS updaters are pluggable: bring your own model without upstreaming it. Built-in OS support: apt, dnf, apk and pacman

02Behaviors1
@dmc/patch/fleetv2026.11.11.3patch_fleet.ts
fn scan()
Fan out over the fleet: collect OS + docker image-drift per machine (the bundled collector, or `scanOs` of the machine's osUpdater model), and fire checkUpdate on every app `source`.
fn import()
Emit a suggested `machines` block seeded from the sshModel host list (and, later, Proxmox guests) to paste into globalArguments and decorate.
fn safeUpdate(host: string, service?: string, healthTimeoutSec?: number, pollIntervalSec?: number, rollbackOnFailure?: boolean, retentionHours?: number)
Health-checked, rollback-capable docker update for one machine: record image ids, pull + up -d, wait for health, roll back to the prior image on failure.
ArgumentTypeDescription
hoststringMachine (host) to update — must have a `docker` decoration
service?stringOverride the machine's docker.service
healthTimeoutSec?number
pollIntervalSec?number
rollbackOnFailure?boolean
retentionHours?numberHow long the previous image is kept as a rollback point before pruneImages may delete it (default 7 days). Old images are never pruned inline.
fn safeOsUpdate(host: string, mode?: enum, retentionHours?: number, rollbackOnFailure?: boolean, healthGraceSec?: number)
Snapshot-guarded OS update for one machine: snapshot → upgrade → re-scan →
ArgumentTypeDescription
hoststringMachine (host) to update
mode?enumapt: safe = `upgrade` (never removes), full = `full-upgrade`. dnf/apk/pacman always do a full upgrade. Passed to an osUpdater model's upgradeOs as is.
retentionHours?numberHow long the pre-update snapshot is retained as a rollback point before pruneSnapshots may delete it (default 7 days). The snapshot is never auto-deleted.
rollbackOnFailure?booleanRoll back to the pre-update snapshot when the machine is unhealthy after the
healthGraceSec?numberGrace window for the post-update health check. While the machine is unhealthy, re-check every 10 s until healthy or this many seconds have passed (a docker-ce upgrade restarts every container). 0 = check once.
fn reboot(host: string, force?: boolean, wait?: boolean, waitTimeoutSec?: number, healthGraceSec?: number)
Gracefully reboot one machine. ssh hosts (VM / bare metal) → `systemctl reboot` over sshModel (scheduled with systemd-run so the call returns before the link drops); containers reached over ssh, or with an unsafe.pctExec record through pct → `pct reboot <ctid>` on the node. Guarded on the last scan's needsReboot unless force. Optionally waits for the host to return and re-scans to confirm needsReboot cleared. Refused, even with force, when the machine's effective osUpdatePolicy is scan-only.
ArgumentTypeDescription
hoststringMachine (host) to reboot
force?booleanReboot even when needsReboot is false / unknown
wait?booleanWait for the host to return, then re-scan to confirm
waitTimeoutSec?number
healthGraceSec?numberGrace window for the post-reboot health detection. While the machine is unhealthy, re-check every 10 s until healthy or this many seconds have passed. 0 = check once.
fn rollback(host: string, snapshot?: string, healthGraceSec?: number)
Deliberately revert a machine to a retained pre-update snapshot, through the snapshotter that took it (recorded on the snapshot: built-in VM node model / CT pct, or a pluggable `snapshotter` model). The explicit recovery for an update or reboot that left the host unhealthy — a reboot itself cannot be rolled back. Reverts to the newest active snapshot for the host unless `snapshot` is given.
ArgumentTypeDescription
hoststringMachine (host) to roll back
snapshot?stringSnapshot name; default = newest active retained snapshot
healthGraceSec?numberGrace window for the post-rollback health check. A rolled-back machine boots again, so while it is unhealthy, re-check every 10 s until healthy or this many seconds have passed. 0 = check once.
fn pruneSnapshots(host?: string, dryRun?: boolean, requireRebootConfirmed?: boolean)
Delete retained pre-update snapshots that are past their retention window, health-confirmed, reboot-confirmed (when the update needed a reboot), AND pass a fresh healthcheck now. Each one is deleted through the snapshotter that took it (recorded on the snapshot: built-in VM node model / CT pct, or a pluggable `snapshotter` model's deleteSnapshot). Nothing else deletes snapshots. Use dryRun to preview.
ArgumentTypeDescription
host?stringLimit to one host (default: all tracked snapshots)
dryRun?booleanReport what would be pruned without deleting
requireRebootConfirmed?booleanRequire rebootConfirmed for snapshots whose update needed a reboot
fn pruneImages(host?: string, dryRun?: boolean)
Delete retained previous docker images that are past their retention window and pass a fresh healthcheck (host reachable, old image no longer in use). Same retention timeline as snapshots. Use dryRun to preview.
ArgumentTypeDescription
host?stringLimit to one host (default: all tracked images)
dryRun?booleanReport what would be pruned without deleting
fn clearRetired(host?: string, dryRun?: boolean, keepHistory?: boolean, force?: boolean)
Remove the stored records of retired machines: hosts with records that are no longer in globalArguments.machines. dryRun defaults to TRUE, so a bare run only previews. Status records (inventory and last update, os-update, reboot results) and run history are deleted; ACTIVE snapshot/image records are kept (they track real snapshots/images) unless force=true. keepHistory keeps run and pruned retention records.
ArgumentTypeDescription
host?stringOne retired host (default: every retired host)
dryRun?booleanReport what would be deleted without deleting (default true)
keepHistory?booleanKeep run records and pruned snapshot/image records; delete only status records
force?booleanAlso delete ACTIVE snapshot/image records (the snapshots/images themselves are not touched)
fn renderAccess(hosts?: array)
Render the swamp-patch access login of each selected machine into an accessPlan record: the authorized_keys line (one key, restricted by from=), and the provisioning and revoke scripts with their digests. The sudoers grants include what the machine's plugged models declare with privileges({ host }). Contacts no host and does not use sshModel. A machine whose plug-in privileges are refused gets no plan, and fails the run after the others are written.
ArgumentTypeDescription
hosts?arrayLimit to these hosts (default: every machine)
fn provisionAccess(hosts?: array, dryRun?: boolean)
Install the swamp-patch access login on each selected machine through access.provisionSshModel, which must differ from sshModel.
ArgumentTypeDescription
hosts?arrayLimit to these hosts (default: every machine)
dryRun?booleanWrite the plans and a dry-run record per host, and contact no host (default true)
fn revokeAccess(hosts?: array, dryRun?: boolean)
Remove the swamp-patch access login from each selected machine through access.provisionSshModel, which must differ from sshModel. Only what @dmc/patch installed goes: the account and its group when the marker and token show that it made them, the sudoers grant, the managed cache and docker files. Dry run unless dryRun is false; a dry run contacts no host. Every host gets an accessRun record. A failed host fails the run after all hosts are tried.
ArgumentTypeDescription
hosts?arrayLimit to these hosts (default: every machine)
dryRun?booleanWrite a dry-run record per host, and contact no host (default true)
fn auditAccess(hosts?: array, userProbeVia?: enum)
Read-only audit of the swamp-patch access login on each selected machine. Probes each host as the patch login (through sshModel, no sudo; with userProbeVia root, as the patch login through access.provisionSshModel) and as root (through access.provisionSshModel),
ArgumentTypeDescription
hosts?arrayLimit to these hosts (default: every machine)
userProbeVia?enumHow the user probe reaches each host: ssh (default) logs in with the access key through sshModel; root runs the same read-only probe as the patch login through access.provisionSshModel (runuser, or su). Use root when the audit runs from a place the key's from= does not allow (for example a laptop, when from= names the patch runner only). root records the info finding user-probe-via-root: sshd's acceptance of the key from its from= source is not tested, but every other check runs

Resources

inventory(infinite)— Per-machine OS + docker patch status
seed(infinite)— A suggested machines block produced by `import`
update(infinite)— Result of a safeUpdate run
osUpdate(infinite)— Result of a safeOsUpdate run (snapshot-guarded host OS update)
reboot(infinite)— Result of a reboot run
run(infinite)— Append-only audit record, one per run (osUpdate / docker / reboot), uniquely named so runs accumulate for `swamp data list` / `swamp data query`.
snapshot(infinite)— Lifecycle of a pre-update snapshot (from any snapshotter, recorded in `snapshotter`): kept through the reboot, health-verified, pruned only after a retention window by pruneSnapshots, through the snapshotter that took it.
image(infinite)— A previous docker image kept as a rollback point after safeUpdate; retired by pruneImages after a retention window (same timeline as snapshots).
prune(infinite)— Result of a pruneSnapshots / pruneImages run
accessPlan(infinite)— The rendered swamp-patch access login of one host: the authorized_keys line, the provisioning and revoke scripts, with their SHA-256 digests
accessRun(infinite)— Append-only record of one host in provisionAccess or revokeAccess: dry run, applied, refused, skipped or failed, with the script digest and the result
accessAudit(infinite)— The read-only audit of one host's swamp-patch access login (auditAccess): the findings of the user and root probes, the accepted risks they matched, the summary counts, and whether the host passed the failOn level
03Reports4
@dmc/patch-accessmodel
patch_access.ts

Access audit of the swamp-patch login across fleet nodes: findings, accepted risks, missing or stale audits, last provision and revoke runs

patchpatchingaccesssecurityfleet
@dmc/patch-historymodel
patch_history.ts

Per-host detail: current status + run history with package/image changes

patchpatchinghistorydetailaudit
@dmc/patch-prune-historymodel
patch_prune_history.ts

History of snapshot and docker-image prune runs (retired vs kept)

patchpatchingpruneretentionhistory
@dmc/patch-statusmodel
patch_status.ts

Overall patch/update/reboot status across all fleet nodes

patchpatchingstatusfleet
04Previous Versions9
2026.11.11.3MIT
2026.11.11.2MIT
2026.11.11.1MIT
2026.11.07.1MIT

Modified 1 behaviors. Added 1 reports. updated dependencies

2026.10.25.1MIT(was none)
2026.10.16.1
2026.10.09.1

Modified 1 behaviors

2026.10.01.1
2026.09.30.1
05Stats
A
100 / 100
Downloads
78
Archive size
254.1 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned

07Platforms
08Labels