Amiga Unix — 68040 · 68060

Manual pages › System administration commands (1M)

kbootset(1M)

compose, commit and roll back boot generations

Package: kbootset, added for amigaux.

NAME · SYNOPSIS · DESCRIPTION · OPTIONS · COMMANDS · GATES · EXIT STATUS · ENVIRONMENT · FILES · EXAMPLES · SEE ALSO · NOTES

kbootset - compose, commit and roll back boot generations

kbootset [-R root] [--image file | --dev path] [--offset n] [--journal path] command [argument ...]

kbootset keeps the boot store: the UNI\0 boot slice that the Amix boot loader reads. The store holds generations. A generation is one kernel with its root-class modules, the manifest that names them, and the boot- and demand-class modules the manifest names under /stand/gen/id/mod. The loader boots one generation; its menu, safe mode and the try-once rule choose another when asked or when one fails.

A generation is in one of four states:

the generation the install laid down; never deleted and never marked bad.
it completed a full multi-user boot.
committed and not yet good. The loader boots a trial once; if that boot does not reach the end of run level 2, the next boot takes the previous good generation.
a trial that failed, or a generation marked bad by hand.

The kept set is the pristine generation, the default, the two newest good generations and at most one trial. commit and collect remove every other generation.

After a transaction that changes a kernel-space package, apkg runs kbootset build and kbootset commit itself when bootset=auto in /etc/default/bootset, and prints the two commands otherwise. The base system runs namelist, retry and mark-good on every boot.

Without --image or --dev, kbootset works on the running box. It reads the box's identity from /dev/kinfo (and makes the node, character 53 0, mode 0444, when it is missing), and finds the boot store from the store= line of /etc/default/bootset, else from the loader record, else by scanning every disk.

Work on a mounted target: the packages, the records and /stand under root, and the store named by root/etc/default/bootset or by --bootdev. The installer and repair mode use it.
The store is in the disk image file.
The store is on the raw device path.
The store starts n bytes into the image or device (default 0).
The commit journal. The default is root/var/kbootset/journal on the box; with --image or --dev there is none unless one is named.

Prints the store header and its set id (store-id:), the control block, every generation with its state and members, the booted generation, the loader that booted it and the kernel (from kinfo), each module of the booted generation as loaded or not (and why, in a safe boot), whether /stand/unix is the booted kernel's namelist, and the box's facts. A note: line says when /stand/loader holds a loader the store does not. It writes nothing.
Composes the next generation from the packages installed under the root into /stand/gen/id and runs every gate (see GATES). It writes nothing to the store. The box's facts come from the options, then kinfo, then /etc/default/bootset:
the kernel line.
the boot disk's controller, as a match key (zorro:0202:54).
the root disk's controller.
the root file system type (ufs, s5).
the box's fast memory.
the root and swap records of the manifest, given once on the pristine build; later builds carry them from the default generation.
When the built generation equals the default one, build says that commit will write nothing. When another good generation holds it, it says that kbootset default id makes that one the default without a new generation.
Writes the built generation into the store as the trial: the journal, the members, a read-back of every extent, the manifest, then the control block, which is the commit point. It prints generation N committed; power-cycle to boot it. When the generation equals the default one (the same line, kabi, root, swap, members by name, size and SHA-256, and parameters), it writes nothing and prints the default generation M already has these members; nothing to commit, and removes what the build put in /stand/gen/id. Either line ends with the way to install the loader when /stand/loader/boot2 differs from the store's; a loader is never installed unasked. On the running box it then makes the disk nodes, as nodes does.
commit --again
Commits the built generation even when it equals the default: a fresh copy as a new generation, the repair for store bytes that check found damaged.
commit --spec spec
Commits the generation a spec file gives, in the format of the host tool mkstore; for tests and media built without packages.
Recomputes the SHA-256 and CRC-32 of every member in the store and of every file the manifests name under the root, compares each module kernel's major table with this kbootset's registry (a different table is a problem, none a note), and compares the installed packages with the default generation. An installed kernel the default does not hold is named as what it is: on trial in generation N, good in generation N, or in no generation yet; each line gives the next step, and none is a problem. So is a loader in /stand/loader that the store does not hold. It never writes. Exit status 1 when it finds a problem.
Run once per boot, as the last script of run level 2. When the booted generation (from kinfo's loader record) is the trial, it becomes good and the default; on any other boot nothing is marked. After a new boot loader's trial boot it accepts the new loader, or reports that the secondary loader booted. When the loader passed over the default by itself, it verifies the default: damaged members mark it bad, and the booted generation becomes the default. It also writes the namelist, as namelist does. --booted and --secondary replace the loader record's answers. After a boot from a CD or a floppy pair it marks nothing.
Run by the base system just before the reboot that follows a root file system repair. When the booted generation is the trial, its attempt does not count, at most twice per trial. It writes the boot store's control block and nothing on the root; otherwise it does nothing.
Makes the newest good generation older than the default the new default, or the pristine one when there is none. A pending trial is cancelled. The line names the way back.
Makes the good or pristine generation id the default, for every boot from the next on, writing no new generation. It is refused while a generation is on trial: boot that one first, or mark it bad.
Marks generation id bad. The pristine generation cannot be marked bad.
A request for the next boot only: the previous good generation, safe mode, development loading (modules outside the manifest may load, and the loader and kernel say so), no request, or generation id.
Removes the generations outside the kept set. Whatever removes a generation from the store also removes its /stand/gen/id from the root, except the running generation's, which goes after the next boot.
Installs a new boot loader as the primary one; the old primary becomes the secondary, which boot1 runs when the new one does not complete a boot. While a new loader is on trial or damaged, an install replaces only it: the secondary stays the loader that last completed a boot. boot1 is replaced only with --boot1. --version is the version of the given boot2 (default: this kbootset's own).
Lays an empty store of size bytes with the loader boot2; it needs --dev or --image. A slice that already holds a store or a bootblock is refused unless --force is given; the first 64 KiB are zeroed first.
Writes the booted kernel's namelist to /stand/unix, the file netstat, ifconfig and crash read symbols from: an ELF file of the booted kernel's symbols at their addresses in this boot, with each loaded module's globals and, in a section of its own, crash_sync's word as the running kernel holds it, which crash checks the file against. It writes only when the content differs, as a new file renamed into place; modadmin runs it after loading or unloading a module. A kernel shipped without symbols takes them from /stand/gen/id/unix.sym when the generation has one, else from the line's unix.sym, which it then saves there, so that a rollback's boot still has them after a package replaces the line's file. Exit status 3 when it cannot make one; the line says why.
Makes the disk nodes a four-card kernel needs (/dev/dsk and /dev/rdsk c0 to c1f, d0, s0 to s7), removes the d1 nodes, and registers the change to the core package on the running box. It does nothing unless sdcards=4 is in /stand/k30/kabi or /stand/k46/kabi. It needs neither kinfo nor a store.
Prints the majors that the major registry gives module name, one line each, c n for a character major and b n for a block major, with nothing else on the line: kbootset major z3660eth prints c 51. It reads neither the store nor kinfo nor the root, so it answers the same on a static kernel, in safe mode and after a boot from a CD or a floppy pair. Exit status 1, with a message on the standard error and nothing on the standard output, for a name the registry does not know; the registry names only modules, never a stock driver such as aen. With -l it prints every row of the registry instead, as module type n (z3660eth c 51).
Prints the disk controllers the running kernel drives, from the card table of /dev/kinfo, one line per card: card k: cN-cM key with base address after it for a Zorro board. The disks of card k are c(8k) to c(8k+7) in the cndmsk names, n in lowercase hex as the stock names write it (c8-cf for card 1, c10-c17 for card 2), and key is the controller's match key, the value build takes for --bootdev and --rootdev: zorro:144b:01, mobo:gayle, mobo:a4000t-710. Given a disk node (/dev/dsk/c8d0s1, /dev/dsk/ced0s1, /dev/rdsk/..., or the name alone), it prints only the key of that disk's card. A card is listed only when its driver is linked and registered with sd in the running kernel. It reads kinfo and nothing else and writes nothing. Exit status 1, with a message on the standard error and nothing on the standard output, when there is no kinfo record or the disk's card is not in the table; 2 for a name that is not a disk node.
The card lines, and under each card one line per unit that answers an INQUIRY, as inquiry prints it after unit u: . Exit status 0 whatever the units answer.
Sends one unit one SCSI SYNCHRONIZE CACHE through /dev/scsi, as kbootset does after each store write on a Gayle disk, and says whether the unit took it. That tells whether it takes the command, not whether it has a cache.
Asks one unit its type with one SCSI INQUIRY through /dev/scsi (char major 11), and nothing else: it reads, opens no disk and writes nothing, so an installer knows a CD from a disk before anything reads it. card is the number cards prints (0-3) and unit the target id (0-7). It prints type n vendor product revision (type 5 hp PLDS_DVDRW_DU8AE 6HSM): n is the peripheral device type (0 a disk, 5 a CD), and each field is one word, its blanks turned into _ and - when it is empty. Exit status 1, with a message on the standard error and nothing on the standard output, when no unit answers (a non-zero qualifier, type 0x1f, a failed or unanswered command, a card the kernel did not register, or no /dev/scsi); 2 for usage.
Builds the pristine generation of a new medium (a disk image, a floppy pair, a CD tree). Only the host build of kbootset has it.

build and commit refuse, with exit status 4 and a line naming the gate, when:

1
a kernel-space member's SHA-256 is not the one apkg recorded at install, or no record names it (hash): the file was changed or placed by hand or by a bare pkgadd; the line names the package, and apkg -f install package puts it right;
2
the members disagree on the kernel ABI, or a module needs a symbol that neither the kernel nor a module it depends on gives (kabi);
3
no driver in the kernel or the root-class modules covers the boot disk's controller, the root disk's controller or the root file system, or a module is missing its board, its majors or a dependency (closure);
4
the root-class modules do not fit the kernel's arena (arena);
5
the generation does not fit the free store space beside the kept set (store space);
6
the box's fast memory is too small for the kernel, the arena and the RAM disk (memory);
7
the installed loader is older than the generation needs (loader);
8
the boot store cannot be identified unambiguously (boot disk);
9
the boot disk carries more than one UNI\0 slice (one boot slice);
10
the kernel's line does not match the box's processor (line).

0
done: the store changed as asked, or there was nothing to do.
1
an I/O error, a read-back mismatch, or a damaged store. A commit interrupted before its commit point leaves the store unchanged, and the next run reports the journal.
2
usage.
3
refused by a rule: a read-only store, a pristine generation marked bad, no older good generation, an unknown booted generation.
4
refused by a gate (see GATES).

Nothing is written when the status is 2, 3 or 4. Every line kbootset prints for a person starts with kbootset: ; the lines of major, cards and inquiry are for scripts and do not.

commit announces each step on the standard error (kbootset: step N), and with this set it syncs and waits before step n, for power-cut tests.

/etc/default/bootset
bootset=auto or manual, the store (store=, store-id=) and the box's facts (line=, bootdev=, rootdev=, rootfs=, mem=).
/stand/gen/id/
a built generation: its manifest, mod/, the modules the kernel loads from the root, and for a kernel without symbols unix.sym.
/stand/loader/boot2
the loader package's boot2; loader-install puts it on the store.
/stand/unix
the booted kernel's namelist.
/var/kbootset/journal
the commit journal.
/dev/kinfo
the booted kernel's identity, loader record and loaded modules.
/etc/conf/mod.d/name
an installed module object.
/etc/conf/modreg.d/name
a module's parameters from its package; /etc/conf/modreg.local.d/name holds the administrator's, which win.
/etc/init.d/kbnamelist
run as /etc/rc2.d/S01kbnamelist: kbootset namelist early in run level 2.
/etc/init.d/kbmarkgood
run as /etc/rc2.d/S99zkbootset, the last script of run level 2: kbootset mark-good.
/etc/rc.conf
kbnamelist=no or kbmarkgood=no turns the boot script off; both are on by default. With kbmarkgood=no no trial generation is ever kept: the loader takes it back on the next boot, and the console says so at every boot. The status of each call is logged in /var/adm/rc.log.

After installing a kernel-space package by hand with bootset=manual:

kbootset build
kbootset commit

then power-cycle the box. To make the previous good generation the default again:

kbootset rollback

and to go back to generation 4 after that:

kbootset default 4

A boot script that re-creates a missing node:

set -- `kbootset major z3660eth`
mknod /dev/zen0 $1 $2 0

An installer that takes the controller from the disk the user picked:

key=`kbootset cards /dev/dsk/c8d0s1` || exit 1
kbootset -R /mnt build --bootdev $key --rootdev $key ...

apkg(1), rc.subr(1M), rc.conf(4)

A real 68060 is power-cycled to boot a new generation, not rebooted in software.

2026-11-04 kbootset