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.

Building stboot

Being a go program, stboot is built using the go tools. To ensure that the resulting executable is statically linked, CGO_ENABLED=0 should be set in the environment, e.g., CGO_ENABLED=0 go install.

There are several ways to get and build stboot. The first two can benefit from verification of release signatures.

1. Clone the stboot git repository and checkout one of the signed release tags and build.

2. Get a signed ST collection release archive, unpack, and build in the stboot subdirectory.

3. Let the go tools download stboot, e.g., CGO_ENABLED=0 go install system-transparency.org/stboot@v0.4.3. This method relies on go's checksum database for integrity, but there is no easy way to verify release signatures.

Embedded stboot version information

The build process embeds an stboot version. The version is displayed when booting using stboot, and in response to the stboot --version option. In most cases this is set automatically based on go module version or git revision. However, for installation method (2) above, neither module version nor git revision is available.

The version can be overridden by passing a linker flag to assign a non-empty string to the symbol main.ConfiguredVersion. E.g., when building the st-1.2.0 collection release, it's suggested to build using CGO_ENABLED=0 go build --ldflags="-X main.ConfiguredVersion=st-1.2.0.

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.459360] Run /init as init process
stboot: 2024/12/17 11:08:41 [INFO] Running as pid 1
stboot: 2024/12/17 11:08:41 [INFO] 
  _____ _______   _____   ____   ____________
 / ____|__   __|  |  _ \ / __ \ / __ \__   __|
| (___    | |     | |_) | |  | | |  | | | |
 \___ \   | |     |  _ <| |  | | |  | | | |
 ____) |  | |     | |_) | |__| | |__| | | |
|_____/   |_|     |____/ \____/ \____/  |_|

stboot: 2024/12/17 11:08:41 [INFO] version: v0.5.0
stboot: 2024/12/17 11:08:41 [ERROR] trust policy: opening trust policy failed: open /etc/trust_policy/trust_policy.json: no such file or directory

Due to missing configuration files, stboot fails. 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.