stboot

README

stboot

The System Transparency boot loader

The stboot bootloader is typically installed as the init program inside an initramfs. It can download an operating system package (OS package), verify that it is signed according to the configured trust policy, and then boot it.

Example usage

A minimal example starting stboot in QEMU

Build stboot, as a static executable in the current directory

GOBIN="$(pwd)" CGO_ENABLED=0 go install system-transparency.org/stboot@latest

Build an initramfs (uncompressed, for simplicity) containing only the stboot executable, under the name init

ln -s stboot init &&
  echo init | cpio -o -H newc -R 0:0 --dereference > initramfs

Test your initramfs (assuming your OS kernel at /boot/vmlinuz):

qemu-system-x86_64 -kernel /boot/vmlinuz -nographic --no-reboot -append "console=ttyS0,115200" -initrd initramfs -m 2048 --enable-kvm

You should see something like this:

[...]
[    0.452303] Run /init as init process
stboot: 2024/04/22 14:08:52 [INFO] Running as pid 1
stboot: 2024/04/22 14:08:52 [INFO] 
  _____ _______   _____   ____   ____________
 / ____|__   __|  |  _ \ / __ \ / __ \__   __|
| (___    | |     | |_) | |  | | |  | | | |
 \___ \   | |     |  _ <| |  | | |  | | | |
 ____) |  | |     | |_) | |__| | |__| | | |
|_____/   |_|     |____/ \____/ \____/  |_|

stboot: 2024/04/22 14:08:52 [ERROR] signing root certificate: open /etc/trust_policy/ospkg_signing_root.pem: no such file or directory
stboot: 2024/04/22 14:08:52 [ERROR] boot failed

The program will exit with an error, because of missing configuration data. After a short delay, it will attempt to reboot, and qemu exits.

More complete examples

See this integration test for a script that:

1. Creates an initramfs including stboot, needed configuration, and a signed Debian OS package.
2. Wraps it as a disk image that can be booted by UEFI firmware.
3. Boots a QEMU machine from the resulting disk image.

The stimages repository includes additional tooling, see stimages build-stboot for a more configurable script that creates an stboot image, configured for network boot.

Learn more

See stboot documentation for more information about what stboot does during boot. Refer to and see ST documentation for specifications as well as documentation for other related tools.