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.
| Argument | Type | Required | Description |
|---|
| host | string | yes | Machine (host) to update — must have a `docker` decoration |
| service? | string | no | Override the machine's docker.service |
| healthTimeoutSec? | number | no | |
| pollIntervalSec? | number | no | |
| rollbackOnFailure? | boolean | no | |
| retentionHours? | number | no | 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: snapshot → upgrade → re-scan →
| Argument | Type | Required | Description |
|---|
| host | string | yes | Machine (host) to update |
| mode? | enum | no | apt: 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? | number | no | How 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? | boolean | no | Roll back to the pre-update snapshot when the machine is unhealthy after the |
| healthGraceSec? | number | no | 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); 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.
| Argument | Type | Required | Description |
|---|
| host | string | yes | Machine (host) to reboot |
| force? | boolean | no | Reboot even when needsReboot is false / unknown |
| wait? | boolean | no | Wait for the host to return, then re-scan to confirm |
| waitTimeoutSec? | number | no | |
| healthGraceSec? | number | no | 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, 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.
| Argument | Type | Required | Description |
|---|
| host | string | yes | Machine (host) to roll back |
| snapshot? | string | no | Snapshot name; default = newest active retained snapshot |
| healthGraceSec? | number | no | Grace 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.
| Argument | Type | Required | Description |
|---|
| host? | string | no | Limit to one host (default: all tracked snapshots) |
| dryRun? | boolean | no | Report what would be pruned without deleting |
| requireRebootConfirmed? | boolean | no | 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 | Required | Description |
|---|
| host? | string | no | Limit to one host (default: all tracked images) |
| dryRun? | boolean | no | Report 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.
| Argument | Type | Required | Description |
|---|
| host? | string | no | One retired host (default: every retired host) |
| dryRun? | boolean | no | Report what would be deleted without deleting (default true) |
| keepHistory? | boolean | no | Keep run records and pruned snapshot/image records; delete only status records |
| force? | boolean | no | Also 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.
| Argument | Type | Required | Description |
|---|
| hosts? | array | no | Limit 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.
| Argument | Type | Required | Description |
|---|
| hosts? | array | no | Limit to these hosts (default: every machine) |
| dryRun? | boolean | no | Write 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.
| Argument | Type | Required | Description |
|---|
| hosts? | array | no | Limit to these hosts (default: every machine) |
| dryRun? | boolean | no | Write 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),
| Argument | Type | Required | Description |
|---|
| hosts? | array | no | Limit to these hosts (default: every machine) |
| userProbeVia? | enum | no | How 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