IF Commons GitHub

Netboot: the logical layer

0003Active

0003-netboot-logical · owner if · domain commons

Requirements

FR-001checkpassing

The GRUB menus MUST boot the local disk for a host that is not armed and for a machine that is not known (offering the armed hosts, with the local disk first and the default), and MUST install only an armed host, naming the installer image, the install's URL with the host's token and the MAC that GRUB reports.

Enforced (check): .github: cd commons/netboot && bun run verify — suite/netboot.test.ts

Proved by: netboot/suite/netboot.test.ts

Written in: netboot/src/logical/grub.ts

Tests: passed: suite/netboot.test.ts the menus boot the local disk for a host that is not armed and for a machine nobody knows,

FR-002checkpassing

An arming MUST carry a token that the install's URLs carry; a token MUST be compared whole (a short token is no token); a host MUST stay armed until the installer says it is done, which MUST disarm it and remember the MAC it installed from; the progress kept MUST be the last 200 lines.

Enforced (check): .github: cd commons/netboot && bun run verify — suite/netboot.test.ts

Proved by: netboot/suite/netboot.test.ts

Written in: netboot/src/logical/arming.ts

Tests: passed: suite/netboot.test.ts a host is armed with a token and stays armed until the installer is done, a token is compa

FR-003checkpassing

The guard MUST go on where every disk is blank, where a person confirmed that the disks may be erased, and where the host installed from this MAC before; it MUST stop, saying why and what lets it go on, for any other machine with data on its disks, and MUST stop where there is no disk, whatever was confirmed.

Enforced (check): .github: cd commons/netboot && bun run verify — suite/netboot.test.ts

Proved by: netboot/suite/netboot.test.ts

Written in: netboot/src/logical/guard.ts

Tests: passed: suite/netboot.test.ts the guard goes on for blank disks, for a confirmed erase and for a host that installed fro

FR-004checkpassing

The TFTP packets MUST be those of RFC 1350 with the options blksize, tsize and timeout (RFC 2347 to 2349): a request MUST be parsed with its options, the options agreed MUST be within bounds (a block size from 8, at most the server's maximum), a path that climbs out of the served tree or holds a NUL or a backslash MUST be refused, and block numbers MUST be taken modulo 65536.

Enforced (check): .github: cd commons/netboot && bun run verify — suite/netboot.test.ts

Proved by: netboot/suite/netboot.test.ts

Written in: netboot/src/logical/tftp.ts

Tests: passed: suite/netboot.test.ts a read request is parsed with its options, the options agreed are within bounds, and a pat

FR-005checkpassing

A request path MUST be classified as a boot file, the menu of the network GRUB, the menu of one MAC, a boot file of one host, the installer image, or one of the install's files under /install/<host>/<token>/<mac>/ (user-data, meta-data, vendor-data, guard.sh, facts, event, done) with a token of at least 16 hexadecimal digits; anything else, and a name that is only dots, MUST be unknown.

Enforced (check): .github: cd commons/netboot && bun run verify — suite/netboot.test.ts

Proved by: netboot/suite/netboot.test.ts

Written in: netboot/src/logical/routes.ts

Tests: passed: suite/netboot.test.ts a path is a boot file, a menu, the image or an install file, and nothing else

Acceptance scenarios

  1. Given a host that is not armed, When its menu is asked, Then it boots its own disk, per FR-001.
  2. Given a machine with a partition and no confirmation, When the guard decides, Then it stops, per FR-003.

Out of scope

  • The servers: the physical layer.

Edge cases

  • A path with .. in it: unknown, per FR-005.

Assumptions

Open questions

  • None.

Key entities

  • Pin, Arming, Guard.

Success criteria

SC-001success criterion

The tests of the library pass with real sockets on the loopback.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

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