IF Commons GitHub

logical/guard

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-netboot-logical FR-003

The blank-disk guard's decision. Before Ubuntu's installer touches a disk it reports what the machine is (its firmware tables, /proc and its disks) as key=value lines, and the server answers ok or stop: why. The install goes on by itself only where every disk is blank, where a person confirmed that the disks may be erased, or where the machine is this host already (it installed as this host from this MAC). Anything else stops before a byte is written. With no answer there is no install: the script fails closed.

import { parseFacts, decide } from "./guard.ts";
decide("athens", parseFacts("disk=sda 100 sata\n"), {}, undefined, undefined).go; // true

Source: commons/netboot/src/logical/guard.ts

3 of 16 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.MachineFactstypeno test imports it
type MachineFacts = {
  vendor?: string;
  model?: string;
  serial?: string;
  memKiB?: number;
  cpus?: number;
  /** Name, size in bytes and how attached. */
  disks: Array<{ name: string; bytes: number; transport?: string }>;
  /** Partition tables and file systems found: `/dev/sda gpt`, `/dev/sda2 ext4`. */
  signatures: string[];
};

What a machine says about itself.

logical.parseFactsfunctionno test imports it
function parseFacts(text: string): MachineFacts

The script's key=value lines as facts. Unknown keys are ignored and firmware filler is dropped.

logical.describeFactsfunctionno test imports it
function describeFacts(f: MachineFacts): string

One line, as the machine describes itself.

logical.GuardDecisiontypeno test imports it
type GuardDecision = { readonly go: true; readonly why: string } | { readonly go: false; readonly why: string; readonly fix: string };

The guard's answer: go (and why), or stop (why, and what lets it go on).

logical.GuardContexttypeno test imports it
type GuardContext = {
  /** A person confirmed that the disks may be erased. */
  readonly confirmDestroy?: boolean;
  /** The MAC the host installed from before, if it has. */
  readonly installedMac?: string;
};

What the decision knows besides the facts.

logical.decidefunctionno test imports it
function decide(host: string, f: MachineFacts, ctx: GuardContext, bootMac: string | undefined): GuardDecision

Whether this install may go on.

logical.answerOffunctionno test imports it
function answerOf(d: GuardDecision): string

The answer the script reads: ok and the reason, or stop: why and the fix.

logical.GUARD_SCRIPTconstno test imports it
const GUARD_SCRIPT: "#!/bin/sh\n# archon: before any disk is touched, report this machine's facts to the boot server and… (1570 characters)
const GUARD_SCRIPT: "#!/bin/sh\n# archon: before any disk is touched, report this machine's facts to the boot server and do what it answers. Nothing here writes a disk.\nB=\"$1\"\nF=/tmp/archon-facts\n{\n  for k in sys_vendor product_name product_serial board_vendor board_name; do\n    echo \"$k=$(cat /sys/class/dmi/id/$k 2>/dev/null)\"\n  done\n  echo \"mem_kib=$(awk '/^MemTotal:/ { print $2 }' /proc/meminfo)\"\n  echo \"cpus=$(nproc 2>/dev/null)\"\n  lsblk -dnbro NAME,SIZE,TYPE,TRAN -e 1,7,11 2>/dev/null |\n    awk '$3 == \"disk\" && $1 !~ /^zram/ { print \"disk=\" $1 \" \" $2 \" \" $4 }'\n  for d in $(lsblk -dnro NAME,TYPE -e 1,7,11 2>/dev/null | awk '$2 == \"disk\" && $1 !~ /^zram/ { print \"/dev/\" $1 }'); do\n    command -v wipefs >/dev/null || { echo \"signature=$d unchecked (no wipefs)\"; continue; }\n    for x in $d $(lsblk -nrpo NAME,TYPE \"$d\" 2>/dev/null | awk '$2 == \"part\" { print $1 }'); do\n      [ \"$x\" = \"$d\" ] || echo \"signature=$x partition\"\n      wipefs -n --noheadings -O DEVICE,TYPE \"$x\" 2>/dev/null | awk 'NF > 1 { print \"signature=\" $1 \" \" $2 }' ||\n        echo \"signature=$x unchecked\"\n    done\n  done\n} >\"$F\"\nA=$(curl -fsS --noproxy \"*\" -m 30 -X POST -H 'content-type: text/plain' --data-binary @\"$F\" \"${B}facts\") ||\n  A=\"stop: the boot server did not answer, so nothing was erased\"\ncase \"$A\" in\n  ok*) exit 0 ;;\nesac\necho \"archon: $A\" | tee /dev/console\necho \"archon: nothing was written to any disk; this machine powers off in 30 seconds.\" | tee /dev/console\nsleep 30\npoweroff -f\n"

The script the installer runs (as early-commands) before it touches a disk, served as guard.sh under the install's URL: it reports the machine's facts and does what the server answers; with no answer, nothing is erased.

MachineFactstypeno test imports it
type MachineFacts = {
  vendor?: string;
  model?: string;
  serial?: string;
  memKiB?: number;
  cpus?: number;
  /** Name, size in bytes and how attached. */
  disks: Array<{ name: string; bytes: number; transport?: string }>;
  /** Partition tables and file systems found: `/dev/sda gpt`, `/dev/sda2 ext4`. */
  signatures: string[];
};

What a machine says about itself.

parseFactsfunction
function parseFacts(text: string): MachineFacts

The script's key=value lines as facts. Unknown keys are ignored and firmware filler is dropped.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

describeFactsfunction
function describeFacts(f: MachineFacts): string

One line, as the machine describes itself.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

GuardDecisiontypeno test imports it
type GuardDecision = { readonly go: true; readonly why: string } | { readonly go: false; readonly why: string; readonly fix: string };

The guard's answer: go (and why), or stop (why, and what lets it go on).

GuardContexttypeno test imports it
type GuardContext = {
  /** A person confirmed that the disks may be erased. */
  readonly confirmDestroy?: boolean;
  /** The MAC the host installed from before, if it has. */
  readonly installedMac?: string;
};

What the decision knows besides the facts.

decidefunction
function decide(host: string, f: MachineFacts, ctx: GuardContext, bootMac: string | undefined): GuardDecision

Whether this install may go on.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

answerOffunctionno test imports it
function answerOf(d: GuardDecision): string

The answer the script reads: ok and the reason, or stop: why and the fix.

GUARD_SCRIPTconstno test imports it
const GUARD_SCRIPT: "#!/bin/sh\n# archon: before any disk is touched, report this machine's facts to the boot server and… (1570 characters)
const GUARD_SCRIPT: "#!/bin/sh\n# archon: before any disk is touched, report this machine's facts to the boot server and do what it answers. Nothing here writes a disk.\nB=\"$1\"\nF=/tmp/archon-facts\n{\n  for k in sys_vendor product_name product_serial board_vendor board_name; do\n    echo \"$k=$(cat /sys/class/dmi/id/$k 2>/dev/null)\"\n  done\n  echo \"mem_kib=$(awk '/^MemTotal:/ { print $2 }' /proc/meminfo)\"\n  echo \"cpus=$(nproc 2>/dev/null)\"\n  lsblk -dnbro NAME,SIZE,TYPE,TRAN -e 1,7,11 2>/dev/null |\n    awk '$3 == \"disk\" && $1 !~ /^zram/ { print \"disk=\" $1 \" \" $2 \" \" $4 }'\n  for d in $(lsblk -dnro NAME,TYPE -e 1,7,11 2>/dev/null | awk '$2 == \"disk\" && $1 !~ /^zram/ { print \"/dev/\" $1 }'); do\n    command -v wipefs >/dev/null || { echo \"signature=$d unchecked (no wipefs)\"; continue; }\n    for x in $d $(lsblk -nrpo NAME,TYPE \"$d\" 2>/dev/null | awk '$2 == \"part\" { print $1 }'); do\n      [ \"$x\" = \"$d\" ] || echo \"signature=$x partition\"\n      wipefs -n --noheadings -O DEVICE,TYPE \"$x\" 2>/dev/null | awk 'NF > 1 { print \"signature=\" $1 \" \" $2 }' ||\n        echo \"signature=$x unchecked\"\n    done\n  done\n} >\"$F\"\nA=$(curl -fsS --noproxy \"*\" -m 30 -X POST -H 'content-type: text/plain' --data-binary @\"$F\" \"${B}facts\") ||\n  A=\"stop: the boot server did not answer, so nothing was erased\"\ncase \"$A\" in\n  ok*) exit 0 ;;\nesac\necho \"archon: $A\" | tee /dev/console\necho \"archon: nothing was written to any disk; this machine powers off in 30 seconds.\" | tee /dev/console\nsleep 30\npoweroff -f\n"

The script the installer runs (as early-commands) before it touches a disk, served as guard.sh under the install's URL: it reports the machine's facts and does what the server answers; with no answer, nothing is erased.

Titles, headings, exports, tables, columns and requirements. Esc closes.