Patch
@dmc/patchv2026.10.01.1
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
02Models
@dmc/patch/fleetv2026.10.01.1patch_fleet.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshModel | string | Name of the @swamp/ssh model instance used to reach hosts (required — no default) |
| proxmoxNodes | array | Optional @keeb/proxmox/node / @dmc/proxmox model names, for VM/CT discovery in `import` |
| machines | array | The decorated fleet |
fn scan()
Fan out over the fleet: collect OS + docker image-drift per machine, and fire community-script checkUpdate for proxmox-referenced machines.
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.
| Argument | Type | Description |
|---|---|---|
| host | string | Machine (host) to update — must have a `docker` decoration |
| service? | string | Override the machine's docker.service |
| healthTimeoutSec | number | |
| pollIntervalSec | number | |
| rollbackOnFailure | boolean | |
| retentionHours | number | How 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. Proxmox VM (vm decoration): snapshot via the node model → upgrade over ssh → re-scan; roll back the snapshot when the host does not return healthy. Proxmox CT (proxmox decoration): delegate to the community-script safeUpdate. Bare metal: plain safe upgrade, no snapshot. Reboot is never automatic.
| Argument | Type | Description |
|---|---|---|
| host | string | Machine (host) to update |
| mode | enum | apt: safe = `upgrade` (never removes), full = `full-upgrade`. dnf/apk always upgrade. |
| retentionHours | number | How long the pre-update VM snapshot is retained as a rollback point before pruneSnapshots may delete it (default 7 days). The snapshot is never auto-deleted. |
| rollbackOnFailure | boolean | Roll back when the machine is unhealthy after the upgrade |
| healthGraceSec | number | Grace 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); Proxmox CTs (reach=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.
| Argument | Type | Description |
|---|---|---|
| host | string | Machine (host) to reboot |
| force | boolean | Reboot even when needsReboot is false / unknown |
| wait | boolean | Wait for the host to return, then re-scan to confirm |
| waitTimeoutSec | number | |
| healthGraceSec | number | Grace 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)
Deliberately revert a machine to a retained pre-update snapshot (VM snapshot rollback / pct rollback). 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.
| Argument | Type | Description |
|---|---|---|
| host | string | Machine (host) to roll back |
| snapshot? | string | Snapshot name; default = newest active retained snapshot |
fn pruneSnapshots(host?: string, dryRun: boolean, requireRebootConfirmed: boolean)
Delete retained pre-update VM snapshots that are past their retention window, health-confirmed, reboot-confirmed (when the update needed a reboot), AND pass a fresh healthcheck now. Nothing else deletes snapshots. Use dryRun to preview.
| Argument | Type | Description |
|---|---|---|
| host? | string | Limit to one host (default: all tracked snapshots) |
| dryRun | boolean | Report what would be pruned without deleting |
| requireRebootConfirmed | boolean | Require 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.
| Argument | Type | Description |
|---|---|---|
| host? | string | Limit to one host (default: all tracked images) |
| dryRun | boolean | Report what would be pruned without deleting |
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 VM snapshot: kept through the reboot, health-verified, pruned only after a retention window by pruneSnapshots.
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
03Reports
@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 Versions
2026.09.30.1
05Stats
A
100 / 100
Downloads
13
Archive size
80.7 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
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels