blob: d84b8d444e747b23fd9a379a87fcdd71d02c56ee (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
# AGENTS.md
## Project purpose
VyOS fork of [rhboot/shim](https://github.com/rhboot/shim) — a first-stage UEFI bootloader used to satisfy UEFI Secure Boot on VyOS images. shim chains to the second-stage bootloader (GRUB) after validating its signature against a built-in vendor certificate. The fork carries the VyOS vendor certificate and any build-system tweaks needed for the VyOS ISO.
## Tech stack
- C with EFI/GNU-EFI conventions; built against the vendored `gnu-efi` submodule (pinned branch `shim-16.0`).
- GNU `make` build (`Makefile` at root). Current source version `16.0`.
- `.clang-format` present.
## Build / test / run
```
git submodule update --init --recursive # gnu-efi must be present
make VENDOR_CERT_FILE=pub.cer # DER-encoded vendor certificate
# Optional packaging release suffix (sets DASHRELEASE in install paths):
make RELEASE=1
```
See `BUILDING` for full options. Test plan in `testplan.txt`. To produce a Debian package, use the upstream `debian/` rules (consumers wrap this in `vyos-build-packages`).
## Repository layout
- `Makefile` — top-level build (variables: `VENDOR_CERT_FILE`, `RELEASE`,...).
- C sources for the shim itself plus fallback (`fallback.c`) and MOK manager.
- `gnu-efi/` — git submodule (`https://github.com/rhboot/gnu-efi.git`, branch `shim-16.0`).
- `BUILDING`, `README.md`, `README.fallback`, `README.tpm`, `testplan.txt`.
- `.github/`, `.clang-format`.
## Cross-repo context
Native UEFI artifact. Built once and embedded into VyOS ISOs assembled by `vyos/vyos-build`. Companion repo `vyos/shim-review` carries the public shim-review submission paperwork required by Microsoft to sign each VyOS-built shim. Both belong to the build-infrastructure / packaging category. The standard VyOS package mirror twin pattern does **not** apply here (no an internal repository).
## Conventions
- Commit / PR title format: `component: T12345: description` (Phorge task ID at https://vyos.dev mandatory). Enforced where consumed via `vyos/.github` reusables.
- Upstream-tracking fork — keep the diff against `rhboot/shim` minimal; bump `gnu-efi` submodule branch in lockstep with shim version.
- Branch model: VyOS train branches (`rolling`, `sagitta`, `circinus`) overlaid on upstream tags.
## Notes for future contributors
- Fork parent: `rhboot/shim`. The vendored `gnu-efi` submodule is also a Red Hat fork (`rhboot/gnu-efi`).
- A new VyOS shim must go through Microsoft shim review (see `vyos/shim-review`) before it can be signed for Secure Boot. Rebuilds without re-review will not be Secure-Boot-trusted.
- Security contact in upstream is `secalert@redhat.com`; for VyOS-specific issues file at https://vyos.dev.
|
