|
1 | | -# blsforme |
| 1 | +# disks-rs |
2 | 2 |
|
3 | | -> [!WARNING] |
4 | | -> This repository is in a state of constant flux as we enable baremetal Serpent installations. |
| 3 | +This project began life in the [blsforme](https://github.com/serpent-os/blsforme) project for Serpent OS. |
| 4 | +However as time went on it became clear we needed to extend the capabilities beyond simple topology scanning |
| 5 | +and superblocks to support the installer and other use cases. |
5 | 6 |
|
6 | | -A management tool and library enabling Linux distributions to more easily adopt the [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification). |
| 7 | +This is a WIP project to extend support for more disk configurations whilst providing backend support to the |
| 8 | +blsforme project and installers like lichen. |
7 | 9 |
|
8 | | - - Discovery of ESP through [Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE/) - allow suppression of ESP & XBOOTLDR automounting to alleviate weak data integrity concerns. |
9 | | - - Automatic promotion of kernels/initrds to `$BOOT` |
10 | | - - Synchronise `$BOOT` state with the source intent, i.e. mirroring `/usr/lib/kernel` to facilitate garbage collection. |
11 | | - - Cascading filesystem policy allowing vendor overrides/masking for initrds, cmdlines, etc. |
12 | | - - Heavy focus on enabling `type 1` BLS entries with automatic `root=` cmdline generation. |
13 | | - - `XBOOTLDR` support per the [Discoverable Partitions Specification](https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/) |
14 | | - - Concrete policy for kernel packaging, prebuilt vendor initrds, etc. |
15 | | - - Rudimentary fallback for non-UEFI cases (GRUB2 chained bootloader) |
16 | | - |
17 | | -Primarily this tooling has been designed to assist the [moss](https://github.com/serpent-os/moss.git) package manager, but will remain agnostic to support the use case of [Solus](https://getsol.us) and other interested parties. |
18 | | - |
19 | | -## Testing |
20 | | - |
21 | | -```bash |
22 | | -# Update your clone with git pull |
23 | | -# Build fresh release |
24 | | -cargo build |
25 | | -# Show commit of the build |
26 | | -git log -1 |
27 | | -# Run blsforme test |
28 | | -sudo RUST_LOG=trace ./target/debug/blsctl status |
29 | | -# Compare to existing boot arguments |
30 | | -cat /proc/cmdline |
31 | | -# Compare blsforme discovery to blkid discovery |
32 | | -sudo lsblk -f |
33 | | -``` |
34 | | - |
35 | | -Paste a suitable excerpt of the above to e.g. https://bpa.st and link to it in the 'General - Serpent OS' channel on matrix |
36 | | - |
37 | | -## Difference to alternatives |
38 | | - |
39 | | -As the original author of [clr-boot-manager](https://github.com/clearlinux/clr-boot-manager) it needs listing here as "prior art", in terms of synchronising `$BOOT` and `/usr/lib/kernel` for type 1 BLS entries. |
40 | | - |
41 | | -However the original design has a number of weaknesses and doesn't provide a sane schema for the automated discovery of kernel assets without a compile-time vendor prefix. |
42 | | - |
43 | | -In a similar vein, [kernel-install](https://www.freedesktop.org/software/systemd/man/latest/kernel-install.html) is very fuzzy on type 1 vendoring and instead relies on plugins to generate an initramfs (or indeed a staging directory for dracut via a package trigger). |
44 | | - |
45 | | -Additionally `kernel-install` is designed to be a one-shot utility invoked by packaging triggers (or users) rather than a more contained facility to synchronise the target `ESP` (or `$BOOT`) with the expected state as provided by the final package-managed state. |
46 | | - |
47 | | - |
48 | | -In the scope of [Serpent OS](https://serpentos.com/) and [Solus](https://getsol.us) - prebuilt initrds have been in use for years with great success. Given the requirement for both distributions to function correctly in dual-boot and non-appliance use cases, a `.uki` isn't going to permit our use case of generating dynamic cmdlines and shipping pre-signed assets. |
49 | | - |
50 | | -## Filesystem layout |
51 | | - |
52 | | -For discovery to work, `blsforme` expects kernels to live in versioned directories under `/usr/lib/kernel`: |
53 | | - |
54 | | -```bash |
55 | | - /usr/lib/kernel |
56 | | - 6.8.9-289.current/ |
57 | | - vmlinuz # Kernel boot image |
58 | | - |
59 | | - boot.json # Kernel manifest |
60 | | - |
61 | | - # Version specific files. |
62 | | - 10-default.initrd |
63 | | - 10-default.cmdline |
64 | | - |
65 | | - initrd.d/ |
66 | | - # Non-version specific initrd |
67 | | - 01-firmware.initrd |
68 | | - |
69 | | - cmdline.d/ |
70 | | - 99-global.cmdline |
71 | | - |
72 | | - /etc/kernel |
73 | | - initrd.d/ |
74 | | - # Non-version specific |
75 | | - ... |
76 | | - cmdline.d/ |
77 | | - 00-local.cmdline |
78 | | - |
79 | | - cmdline -> cmdline.d/00-local.cmdline |
80 | | -``` |
81 | | - |
82 | | -## `boot.json` |
83 | | - |
84 | | -To further facilitate the development of utilities to enumerate and manipulate boot entries, we augment the kernel packages with a JSON file. Right now this is a developing format which primarily lists the **variant** of the kernel, allowing users to set their preferred default variant when updating/manipulating kernels. As an example, `lts` vs `mainline`. |
85 | | - |
86 | | -```json |
87 | | -{ |
88 | | - "name": "linux-current", |
89 | | - "version": "6.8.9-289.current", /* uname -r */ |
90 | | - "variant": "lts", /* effectively a grouping key. */ |
91 | | -} |
92 | | -``` |
93 | 10 | ## License |
94 | 11 |
|
95 | | -`blsforme` is available under the terms of the [MPL-2.0](https://spdx.org/licenses/MPL-2.0.html) |
| 12 | +`disks-rs` is available under the terms of the [MPL-2.0](https://spdx.org/licenses/MPL-2.0.html) |
0 commit comments