This repository provides stprov, a System Transparency provisioning tool that
can be used for writing necessary stboot configurations to EFI-NVRAM.
Clone and build using make. For example:
$ git clone https://git.glasklar.is/system-transparency/core/stprov.git
$ cd stprov
$ make stprov DEFAULT_USER=alice
See Makefile for all options that can be customized. If the pre-defined defaults are good enough, you may use Go's tooling directly:
$ go install system-transparency.org/stprov/cmd/stprov@latest
One way to use stprov for platform provisioning is by building an OS package
that contains it. This OS package can then be written to the stboot
initramfs, and be loaded by default using so called provisioning mode. In
other words, on missing EFI-NVRAM configuration the stboot image would drop into
a provisioning environment where the stprov remote program is available.
Another way to achieve the same thing is to have a separate image just for
provisioning, e.g., built as an ISO that can be mounted on the platform.
The stprov CI contains examples of how to build provisioning OS packages and separate ISOs that use u-root's shell environment.
You are encouraged to file issues and open merge requests. For information on how we collaborate in GitLab, see accepted proposal that describes this.
If you are a first-time contributor, please review the stprov LICENSE and copyright in the AUTHORS file. Append your name to the list of authors at the bottom in a separate commit.
Our CI configuration builds the stprov program, runs (most)
unit tests, and performs a QEMU integration test. The QEMU integration test
contains a working example of stprov remote and stprov local. See the
testing stprov document for further details.
Please make sure that all CI tests pass before requesting review.
There are a few additional unit tests that are not running in our CI. These tests write to the system's EFI-NVRAM - be warned - and require root privileges. Feel free to skip this unless your changes concerned EFI NVRAM.
$ TEST_CLOBBER_EFI_NVRAM=y go test ./...
Add sudo to the above if you want EFI-NVRAM read/writes to succeed.
If you're updating the stprov command-line interface, please update the stprov manual as well. See instructions on how here.
If you're significantly changing or extending stprov's behavior, consider if an update to the system documentation is appropriate.
We enforce conventional commits using commitlint. The expected git-commit message format is as follows:
<type>: <Description starting with a capital letter>
[optional body]
[optional footer(s)]
Pick <type> from the following list:
- build: changes that are tooling/building related
- chore: housekeeping, dependency management, go.mod, etc.
- ci: continuous integration, workflows, etc.
- docs: README, .md files, documentation in code, etc.
- feat: source code changes introducing new functionality
- fix: bug fixes, no new functionality
- refactor: source code changes without changing behavior
- revert: used if something needs to be reverted
- test: e.g., when adding unit tests and QEMU tests that were not committed as part of a fix or feat commit
Note that we are not picky about an MR containing multiple conventional commits as a result of review. Keep all commits or rebase based on what feels easiest.
- IRC room
#system-transparency@ OFTC.net - Matrix room
#system-transparencywhich is bridged with IRC - System Transparency discuss list