Keyring heal - API reference

What one heal-owner-keyring call found and did. KEYFILE and KEYRING-PATH locate the seed and the keyring. DIAGNOSIS is the first keyring refusal seen, or NIL when the keyring loaded at once. ACTION is :accepted, :salvaged, :kept, :set-aside, or :taken-from-backup. SET-ASIDE-PATH names the damaged file's new name, or NIL. LIVE and RETIRED list the Ed25519 DIDs on the accepted keyring. HEAL-RETIRED pairs each key the heal retired with the line that named it, as (did . text). DROPPED lists the lines a salvage left out, as (line-number problem text). NOT-CARRIED lists keys the damaged file enrolled that a backup lacks. BACKUP-CARRIED-KEYRING is :yes or :no after a recondense from backup, else NIL. SET-ASIDE-NAMES lists DIDs found in a keyring the heal set aside. Only lines ending in a newline are read, and each distinct key= value is listed once. DAMAGED-UNREAD is true when a recondense found something at the keyring path that could not be read as a regular file, so none of its retirements were applied. ACCEPTED is true once the boot's loader accepts the keyring.

Signalled when the name a damaged keyring would be set aside under is already in use. PATH is that name.

Signalled when a restored state directory holds no seed, or a keyring the boot's loader refuses. PATH is the restored state directory and CAUSE the refusal or a description of what is missing.

Root of every refusal the keyring heal signals. PATH is the file or directory concerned. Nothing has been changed when one is signalled.

Signalled when a restored state directory's seed is another owner's. PATH is the restored state directory.

Signalled when nothing, or something other than a regular file, is at the keyfile path. A keyring is healed only beside the seed it belongs to.

Signalled when this image holds a factotum key store, which a running fabric does.

(keyring-heal-backup-unusable-cause condition)

The keyring refusal the boot's loader signalled, or a string naming what the restored state directory lacks.

(keyring-heal-error-path condition)

The file or directory the heal refused over.

(keyring-heal-foreign-backup-backup-owner condition)

The owner DID of the seed in the restored state directory.

(keyring-heal-foreign-backup-live-owner condition)

The DID of this node's owner, read from its seed.

(heal-owner-keyring &key state-dir)

Heal the owner keyring of a node whose boot refused it, by hand, from a REPL on the node's host. The standard heal is a recondense from backup: `valis –restore' into a fresh state directory, then a normal boot. This function is the manual path beside it, for an operator in SBCL with valis loaded on the host, running as the account that owns the keyfile. Slynk is optional: the plain SBCL debugger offers the same restarts. STATE-DIR is the node's StateDirectory; without it the data root this process's XDG<sub>DATAHOME</sub> names is used. The stages: locate the keyfile and the keyring beside it; refuse with keyring-heal-node-running when this image holds a key store, and hold the node configuration's lock for the whole heal, so a running resident makes it signal config-store-held; refuse with keyring-heal-no-seed unless a regular file is at the keyfile path; diagnose with load-factotum-key-store, the call the boot makes, leaving its keyring refusal unhandled, with the restarts that apply to it; after a restart acts, diagnose again, until the loader accepts. Returns a keyring-heal-report, which is also printed. The restarts, each also a function of the same name for handler-bind: keep-keyring, for a keyring refused only for the account that owns it, or for a mode that grants no write to its group or others, makes it private to this account at 0600; salvage-keyring keeps the longest prefix of whole valid records, retires every key a damaged line names, and sets the damaged file aside; recondense-from-backup, given a state directory `valis –restore' landed a backup in, takes the keyring that restore landed and retires every key the damaged keyring shows retired or names, refusing a backup of another owner; set-keyring-aside renames the keyring aside and writes none, so the node boots admitting no enrolled device. A damaged keyring is renamed to <keyring>.refused-<UTC stamp>, never removed, and the seed is never moved, rewritten, or minted.

(heal-restarts-for condition)

The names of the heal's restarts that apply to CONDITION, in the order they are offered: keep-keyring for a keyring-file-unsafe whose problem is :owner, or :mode when a regular file whose mode grants no write to its group or others is at the condition's path, read without following a link; salvage-keyring for a keyring-corrupt other than :unknown-version; recondense-from-backup and set-keyring-aside for every keyring-unusable. NIL for any other condition.

(keep-keyring &optional condition)

Invoke the keep-keyring restart the heal offers for CONDITION, or return NIL when none is offered. Keep applies only to a keyring its group and others cannot write. For a keyring refused for its mode, keep sets 0600 on the same file and changes nothing else; for one another account owns, it installs a copy this account owns at 0600 once the content parses whole under the seed's DID, and sets the original aside.

(keyring-heal-report-accepted instance)

True once the boot's loader accepts the keyring.

(keyring-heal-report-action instance)

What the heal did: :accepted, :salvaged, :kept, :set-aside, or :taken-from-backup.

(keyring-heal-report-backup-carried-keyring instance)

After a recondense from backup, :yes when the backup carried a keyring and :no when it did not; NIL otherwise.

(keyring-heal-report-damaged-unread instance)

True when a recondense found something at the keyring path it could not read as a regular file; no retirement made after the backup is then applied.

(keyring-heal-report-diagnosis instance)

The first keyring refusal the boot's loader signalled, or NIL when the keyring loaded at once.

(keyring-heal-report-dropped instance)

The lines a salvage left out, as (line-number problem text).

(keyring-heal-report-heal-retired instance)

Each key the heal retired, as (did . text), where text is the line that named it.

(keyring-heal-report-keyfile instance)

The pathname of the owner keyfile: the file holding the node's seed, beside which the examined keyring sits.

(keyring-heal-report-keyring-path instance)

The pathname of the keyring the heal examined.

(keyring-heal-report-live instance)

The Ed25519 DIDs live on the accepted keyring.

(keyring-heal-report-not-carried instance)

The DIDs the damaged keyring enrolled that the backup's keyring lacks. None of them is on the accepted keyring.

(keyring-heal-report-p object)

True when the object is a keyring-heal-report.

(keyring-heal-report-retired instance)

The Ed25519 DIDs retired on the accepted keyring.

(keyring-heal-report-set-aside-names instance)

The DIDs found in a keyring the heal set aside. Only lines ending in a newline are read, and each distinct key= value is listed once.

(keyring-heal-report-set-aside-path instance)

The pathname the damaged keyring was renamed to, or NIL when nothing was set aside.

(keyring-set-aside-path keyring-path &optional (time (get-universal-time)))

The native name a damaged keyring at KEYRING-PATH is renamed to at TIME, a universal time: <keyring>.refused-<yyyymmddThhmmssZ>, in UTC.

(recondense-from-backup restored-state-dir &optional condition)

Invoke the recondense-from-backup restart the heal offers for CONDITION with RESTORED-STATE-DIR, a state directory `valis –restore' landed a backup in, or return NIL when none is offered. The restored keyring is installed byte for byte, followed by a retirement of every key it shows live that the damaged keyring retires or names; a backup with no keyring sets the damaged keyring aside and writes none.

(salvage-keyring &optional condition)

Invoke the salvage-keyring restart the heal offers for CONDITION, or return NIL when none is offered. Salvage keeps the longest prefix of whole valid records, retires every key a dropped line names, sets the damaged file aside, and installs the result.

(set-keyring-aside &optional condition)

Invoke the set-keyring-aside restart the heal offers for CONDITION, or return NIL when none is offered. Setting aside renames whatever is at the keyring path, a link as the link, and writes nothing, so the next boot finds no keyring and admits no enrolled device.