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.
-
Clone the stboot git repository and checkout one of the signed
release tags and build.
-
Get a signed ST collection release archive, unpack, and build
in the stboot subdirectory.
-
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.
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:
- Creates an initramfs including stboot, needed configuration, and a
signed Debian OS package.
- Wraps it as a disk image that can be booted by UEFI firmware.
- 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.